net.rim.device.api.crypto.keystore
Class PersistableRIMKeyStore

java.lang.Object
  net.rim.device.api.crypto.keystore.RIMKeyStore
      net.rim.device.api.crypto.keystore.PersistableRIMKeyStore

All Implemented Interfaces:

CollectionEventSource, KeyStore

Direct Known Subclasses:

SyncableRIMKeyStore

public class PersistableRIMKeyStore
extends RIMKeyStore

A persistable version of the rim key store that provides the functionality required to persist the rim key store. For sample code on how to use a key store see: here

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

Field Summary
	protected PersistentObject	_persist The persistent store object that we use to store and retrieve the hash table containing the certificates and keys from the memory of the device.

Fields inherited from interface net.rim.device.api.crypto.keystore.KeyStore

SECURITY_LEVEL_HIGH, SECURITY_LEVEL_LOW, SECURITY_LEVEL_MEDIUM, SECURITY_LEVEL_NOT_APPLICABLE

Constructor Summary
	PersistableRIMKeyStore(String name, long id, CodeSigningKey key, PersistableRIMKeyStoreFactory factory) This constructor initializes the hashtable and ensures that the hashtable is persisted correctly on the device.
	PersistableRIMKeyStore(String name, long id, CodeSigningKey key, PersistableRIMKeyStoreFactory factory, KeyStore keyStore) This constructor allows one to construct a keystore given another key store.

Method Summary
	boolean	addIndex(KeyStoreIndex index) Adds an index to all of the information currently in the key store.
	void	changePassword() Changes the password for the underlying private keys in each of the KeystoreData classes and should NOT be called directly.
	void	removeIndex(long index) Removes the index from the key store and ensures that the aliases used to index key store information regarding this Index class will be removed.
	void	removeKey(KeyStoreData data, KeyStoreTicket ticket) Removes this key store data from the key store and ensures that any links to this object are removed from the key store.

Methods inherited from class net.rim.device.api.crypto.keystore.RIMKeyStore

addCollectionListener, addIndices, checkTicket, deleteKey, elements, elements, elements, elements, elements, elements, exists, existsIndex, getBackingKeyStore, getName, getTicket, getTicket, isMember, isMember, isMember, isMember, removeCollectionListener, set, set, set, set, set, set, set, set, size

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_persist

protected PersistentObject _persist

The persistent store object that we use to store and retrieve the hash table containing the certificates and keys from the memory of the device.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

Constructor Detail

PersistableRIMKeyStore

public PersistableRIMKeyStore(String name,
                              long id,
                              CodeSigningKey key,
                              PersistableRIMKeyStoreFactory factory)
                       throws KeyStoreRegisterException

This constructor initializes the hashtable and ensures that the hashtable is persisted correctly on the device.

Parameters:

name - An identifying name for the keystore that can be displayed to the user.

id - A unique long identifying the hashtable that will be persisted underneath the key store. It is imperative that this is unique since you will overwrite someone elses storage if this is identical to another long passed in. So, you should use your class name or something unique to denote this keystore.

key - a CodeSigningKey which can be used to prevent unauthorized access to your keystore.

factory - The factory used to create the key store.

Throws:

KeyStoreRegisterException - thrown when there is an error registering this class with the KeyStoreManager which is typically caused by one of three exceptions being thrown in that method (ClassNotFoundException, InstantiationException, IllegalAccessException).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

PersistableRIMKeyStore

public PersistableRIMKeyStore(String name,
                              long id,
                              CodeSigningKey key,
                              PersistableRIMKeyStoreFactory factory,
                              KeyStore keyStore)
                       throws KeyStoreRegisterException

This constructor allows one to construct a keystore given another key store. It is like daisy chaining the keystores together. That is, if a key cannot be found in this key store, you can go to the next keystore in an attempt to find it.

Parameters:

name - An identifying name for the keystore that can be displayed to the user.

id - A long representing which key store this is. It has to be unique.

key - a CodeSigningKey which can be used to prevent unauthorized access to your keystore.

factory - The factory used to create the key store.

keyStore - The secondary key store to search through for data.

Throws:

KeyStoreRegisterException - thrown when there is an error registering this class with the KeyStoreManager which is typically caused by one of three exceptions being thrown in that method (ClassNotFoundException, InstantiationException, IllegalAccessException).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

Method Detail

removeKey

public void removeKey(KeyStoreData data,
                      KeyStoreTicket ticket)
               throws KeyStoreCancelException

Description copied from interface: KeyStore

Removes this key store data from the key store and ensures that any links to this object are removed from the key store. Note: This does not affect the underlying keystore.

Specified by:

removeKey in interface KeyStore

Overrides:

removeKey in class RIMKeyStore

Parameters:

data - The data to be removed from the key store.

ticket - A ticket denoting whether or not the developer has access to the keystore. A ticket can be retrieved from the getTicket method in the key store or keystore data. The ticket can also be null which will most likely prompt for a passphrase from the user automatically (essentially calls getTicket for you).

Throws:

KeyStoreCancelException - Thrown if the user fails to enter a password.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

addIndex

public boolean addIndex(KeyStoreIndex index)

Description copied from interface: KeyStore

Adds an index to all of the information currently in the key store. This now enables the developer to access information in the key store according to this new alias field. Note: This does not add the index to the underlying keystore.

Specified by:

addIndex in interface KeyStore

Overrides:

addIndex in class RIMKeyStore

Parameters:

index - An Index class that is implemented by the developer. It denotes how the key store information is indexed according to fields currently contained in key store objects such as certificates.

Returns:

A boolean denoting if the index was added correctly. It will return false if the index already exists.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

removeIndex

public void removeIndex(long index)

Description copied from interface: KeyStore

Removes the index from the key store and ensures that the aliases used to index key store information regarding this Index class will be removed. Note: This does not remove the index from the underlying keystore.

Specified by:

removeIndex in interface KeyStore

Overrides:

removeIndex in class RIMKeyStore

Parameters:

index - The long denoting the index class to remove.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

changePassword

public void changePassword()

Description copied from interface: KeyStore

Changes the password for the underlying private keys in each of the KeystoreData classes and should NOT be called directly. It should only be called by the KeyStoreManager. If this method is called it will cause the keystore to enter into a weird state and will disable its use. If you are designing your own keystore this method should be implemented to call changePassword on each of the KeyStoreData items in the keystore.

Specified by:

changePassword in interface KeyStore

Overrides:

changePassword in class RIMKeyStore

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0