net.rim.device.api.system
Class ControlledAccess

java.lang.Object
  net.rim.device.api.system.ControlledAccess

All Implemented Interfaces:

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:

BlackBerry API 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) Determines If signature on caller's code file is verified with the provided key.

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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 3.6.0

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 ControlledAccess.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:

BlackBerry API 3.6.0

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:

BlackBerry API 3.6.0

verifySignatures

public static boolean verifySignatures(boolean checkProcess,
                                       int signerId)

Determines If signature on caller's code file is verified with the provided key.

Parameters:

checkProcess - true if the process module should also be checked

signerId - the key to use to verify the signature

Returns:

True if the signature on the caller's code file is verified with the provided key; otherwise, false.

Since:

BlackBerry API 4.0.2