net.rim.device.api.system
Class ControlledAccess

java.lang.Object
  |
  +--net.rim.device.api.system.ControlledAccess
All Implemented Interfaces:
Persistable, net.rim.vm.Persistable

public final class ControlledAccess
extends Object
implements Persistable

Restricts access to an object to those callers than have permission.

You can use this class to enforce Data Access Control.

Typical uses for this class include enforcing access control in the RuntimeStore or in a PersistentObject: you can control read and replace access to any object you want to place in the RuntimeStore or in a persistent object by wrapping it in a controlled access object.

To control access to an object in the RuntimeStore
Use code similar to this example:

    long MY_DATA_ID = 0x33abf322367f9018L;
    Hashtable myHashtable = new Hashtable();
    
    // Get the code signing key associated with "ACME"
    CodeSigningKey codeSigningKey = CodeSigningKey.get( moduleHandle, "ACME" );   

    // Store myHashtable in the RuntimeStore but protect it
    // with the "ACME" code signing key
    RuntimeStore.put( MY_DATA_ID, new ControlledAccess( myHashtable, codeSigningKey ) );  
    
    // Now, only code files signed with the ACME key can read or replace myHashtable
 

To retrieve something from the RuntimeStore, use code similar to this example:

    Hashtable myHashtable = (Hashtable) RuntimeStore.get( MY_DATA_ID );  
    // Note: no need to unwrap ControlledAccess
 

Or, to check if your data is protected with a particular code signing key, use code similar to this:

    Hashtable myHashtable = (Hashtable) RuntimeStore.get( MY_DATA_ID, codeSigningKey );  
    // Note: no need to unwrap ControlledAccess
 

To control access to an object in a persistent object
Use code similar to this example:

    long MY_DATA_ID = 0x33abf322367f9018L;
    Hashtable myHashtable = new Hashtable();
    
    PersistentObject persistentObject = PersistentStore.getPersistentObject( MY_DATA_ID );
    
    // Get the code signing key associated with "ACME"
    CodeSigningKey codeSigningKey = CodeSigningKey.get( moduleHandle, "ACME" );   

    // Store myHashtable in the PersistentObject but protect it with the "ACME" code signing key
    persistentObject.setContents( new ControlledAccess( myHashtable, codeSigningKey ) );  
    
    // Now, only code files signed with the ACME key can read or replace myHashtable
 

To retrieve something from the persistent object, use code similar to this example:

    Hashtable myHashtable = (Hashtable) persistentObject.getContents();  
    // Note: no need to unwrap ControlledAccess
 

Or, to check if your data is protected by your ControlledAccess object, use code similar to this:

    Hashtable myHashtable = (Hashtable) persistentObject.getContents( codeSigningKey );  
    // Note: no need to unwrap ControlledAccess
 

Since:
JDE 3.6.0

Constructor Summary
ControlledAccess(Object obj)
          Creates new ControlledAccess instance for wrapping provided object.
ControlledAccess(Object obj, CodeSigningKey readAndReplaceKey)
          Creates new ControlledAccess object for wrapping provided object using provided key.
ControlledAccess(Object obj, CodeSigningKey readKey, CodeSigningKey replaceKey)
          Creates new ControlledAccess object for wrapping provided object using provided keys.
 
Method Summary
 void assertKeys(CodeSigningKey readKey, CodeSigningKey replaceKey)
          Determines if provided code signing keys match wrapped object's keys.
 boolean checkKeys(CodeSigningKey readKey, CodeSigningKey replaceKey)
          Determines if the specified code signing keys match the wrapped object's keys.
static boolean verifyCodeModuleSignature(int moduleHandle, CodeSigningKey key)
          Determines if provided code module has been signed with provided key.
static boolean verifySignatures(boolean checkProcess, int signerId)
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ControlledAccess

public ControlledAccess(Object obj)
                 throws ControlledAccessException
Creates new ControlledAccess instance for wrapping provided object.

This method uses the code signing key associated with the provided object's class to control read and replace permissions.

Parameters:
obj - Object to which to control access.
Throws:
ControlledAccessException - If the calling code file is not signed with the associated code signing key.
Since:
JDE 3.6.0

ControlledAccess

public ControlledAccess(Object obj,
                        CodeSigningKey readAndReplaceKey)
                 throws ControlledAccessException
Creates new ControlledAccess object for wrapping provided object using provided key.

Parameters:
obj - Object to which to control access.
readAndReplaceKey - Key used to control read and replace permission; if null, then everyone has read and replace permission.
Throws:
ControlledAccessException - If the calling code file is not signed with provided key.
Since:
JDE 3.6.0

ControlledAccess

public ControlledAccess(Object obj,
                        CodeSigningKey readKey,
                        CodeSigningKey replaceKey)
                 throws ControlledAccessException
Creates new ControlledAccess object for wrapping provided object using provided keys.

Parameters:
obj - Object to which to control access.
readKey - Key used to control read permission; if null, then everyone has read permission.
replaceKey - Key used to control replace permission; if null, then everyone has replace permission.
Throws:
ControlledAccessException - If the calling code file is not signed with both provided keys.
Since:
JDE 3.6.0
Method Detail

checkKeys

public boolean checkKeys(CodeSigningKey readKey,
                         CodeSigningKey replaceKey)
Determines if the specified code signing keys match the wrapped object's keys.

Parameters:
readKey - Key to match against wrapped object's read key; if null is specified instead of a key, the match will return true.
replaceKey - Key to match against wrapped object's replace key; if null is specified instead of a key, the match will return true.
Returns:
True if both provided keys match the wrapped object's keys or if null is specified instead of valid keys, otherwise false.
Since:
JDE 4.0.2

assertKeys

public void assertKeys(CodeSigningKey readKey,
                       CodeSigningKey replaceKey)
                throws ControlledAccessException
Determines if provided code signing keys match wrapped object's keys.

Note that this method simply invokes checkKeys(net.rim.device.api.system.CodeSigningKey, net.rim.device.api.system.CodeSigningKey).

Parameters:
readKey - Key to match against wrapped object's read key; if null, this always matches.
replaceKey - Key to match against wrapped object's replace key; if null, this always matches.
Throws:
ControlledAccessException - If one or both keys do not match wrapped object's keys.
Since:
JDE 4.0.2

verifyCodeModuleSignature

public static boolean verifyCodeModuleSignature(int moduleHandle,
                                                CodeSigningKey key)
Determines if provided code module has been signed with provided key.

Parameters:
moduleHandle - Handle to code module.
key - the key to use to verify the signature
Returns:
True if the module has been signed by provided key; otherwise, false.
Since:
JDE 4.0.2

verifySignatures

public static boolean verifySignatures(boolean checkProcess,
                                       int signerId)
Since:
JDE 4.0.2


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.