RIM Crypto API: Securing the RuntimeStore

The BlackBerry handheld uses a registry to store common software information on the device. The RuntimeStore class implements the registry functionality by providing a central location and associated operations to allow applications to share information. To ensure the integrity of specific data, the registry maintains a high level of security by coupling the RuntimeStore object with the ControlledAccess object. Using the ControlledAccess object you can supply, along with your registry data, a key to ensure that the data remains secure.

For more information, see the RuntimeStore object or the ControlledAccess object.

This tutorial describes the steps involved in adding and retrieving secure data from the RuntimeStore.

Adding an item into the RuntimeStore involves a key, the item you wish to add, an ID for the item, and a ControlledAccess object. The key is used to protect the item, the ControlledAccess object allows you to secure the item in the registry, and the ID allows you to identify and retrieve the item. In the following example, the key, called "ACME" is created and added to the RuntimeStore. The key instance is created using the get method of the CodeSigningKey class. The name of the key is supplied to return the specified key.

The item is added to the RuntimeStore using the put method of the RuntimeStore object. The put method accepts the ID of the item (this must be unique), and the ControlledAccess object which itself accepts the item to be placed in the registry and the key that will protect it.

The item is now secure within the RuntimeStore and cannot be modified, except by a user who has been signed with the same key. To store something in the RuntimeStore:

    long MY_DATA_ID = 0x33abf322367f9018L;
    Hashtable myHashtable = new Hashtable();
    // store myHashtable in the RuntimeStore
    CodeSignKey codeSigningKey = CodeSigningKey.get( "ACME" );   // use the code signing key with signer id of "ACME"
    RuntimeStore.put( MY_DATA_ID, new ControlledAccess( myHashtable, codeSigningKey );  // wrap myHashtable in a ControlledAccess object

Retrieving an item from RuntimeStore is much simpler. The following example creates a new RuntimeStore, then uses its get method to return the item associated with the ID. Since the data is protected by a controlledAccess object, the get method accepts the ID associated with the item and the key used to insert the item into the registry, and returns the item.

    Hashtable myHashtable = (Hashtable) RuntimeStore.get( MY_DATA_ID, codeSigningKey );
Since the code signing key is required for the operation, the item can only be modified by another user who has access to the same key used to insert the item.

The following example retrieves an object from the RuntimeStore without the use of the key.

	Hashtable myHashtable = (Hashtable) RuntimeStore.get( MY_DATA_ID );
  	// Note: no need to unwrap ControlledAccess
The object will be retrieved from the RuntimeStore if the user matches a key that is used to protect the object in the RuntimeStore. If either of these methods fail due to an incorrect or missing key, a ControlledAccessException is thrown.