This package contains the RIM KeyStore API.

The KeyStore API

Key management is perhaps the most crucial element of cryptography. It involves the secure creation, storage, distribution and destruction of keys and other cryptographic resources. Without a secure key management system in place, encryption is useless since any encryption scheme is only as secure as its keys.

In the RIM Crypto API, key management is handled by the keystore classes. The KeyStore classes provide an effective key store model that allows you to manage the distribution and access of keys both on the desktop and on the handheld device. A key store is a collection of KeyStoreData records. A KeyStoreData record contains any of the keying data that is to be stored in the key store. That is, a KeyStoreData record can contain public keys, private keys, symmetric keys, certificates, and a host of other items. This makes retrieving keys as easy as possible.

In addition, the KeyStoreData record contains items such as labels which identify a particular KeyStoreData record. It is very important that the user is aware of how programs are using their keys and when programs are attempting to access the keys. This is part of an effort to ensure that the digital signature and encryption schemes are as secure as the keys.

The KeyStore contains options that allow the user to customize settings. For instance, the user can decide how often they want to be prompted for their password.







KeyStore Class


A user can set, remove, and access any keys that are contained in that particular KeyStore. The KeyStore contains a very robust and powerful tool for accessing and retrieving KeyStoreData elements. The tool for doing so is referred to as a KeyStoreIndex. The KeyStoreIndex class allows the developer to specify exactly what part of a KeyStoreData record they want to search on. For example, the LabelKeyStoreIndex will search through all of the KeyStoreData records returning only records with matching labels. However, a user can also use the same index to retrieve all of the KeyStoreData records that contain a label by calling the KeyStore.elements method and passing in the ID for the LabelKeyStoreIndex as the only parameter.

For more information please see Using the KeystoreIndex.

The KeyStore contains powerful functionality in that you can specify an “underlying keystore”. An underlying KeyStore is one that is passed into the constructor of a newly created KeyStore. This underlying KeyStore will be searched on calls to some of the methods in the KeyStore depending on the situation. This is clearly defined in the Javadocs. For example, when searching for a specific record using the method element( Index.ID, alias) it will automatically search the underlying KeyStore if no matching records were found in the current KeyStore. This is very useful for situations where you are trying to build up a certificate chain and perhaps the next chain the certificate is in the underlying KeyStore. In the RIM KeyStore system the DesktopKeyStore has the TrustedKeyStore as its underlying KeyStore. If desired, it is entirely possible to make the TrustedKeyStore the underlying KeyStore for any newly created KeyStore.

There are three different types of keystore: the RIMKeyStore, and the PersistableRIMKeyStore and SyncableRIMKeyStore (the latter two extend the RIMKeyStore class). The RIMKeyStore is designed for temporary keys that will not withstand device resets. One example would be a SmartCard KeyStore since the keys are always stored on the smartcard the developer does not need to worry about losing the keys during a device reset.

The PersistableRIMKeyStore is used to store keys that are meant to withstand device resets, hence this keystore is persistable. Finally, the SyncableRIMKeyStore contains keys that are persistable as well as allowing the user to synchronize those keys with the desktop software (CertSync).

The DesktopKeyStore and TrustedKeyStore are both SyncableRIMKeyStores which allow the user to employ the desktop software to add, update and remove keys from the device. RIM applications use the DesktopKeyStore and TrustedKeyStore heavily. Use the DesktopKeyStore to store keys that will be shared between applications. Only RIM signed applications can add keys to the TrustedKeyStore.

API Reference

The KeyStore API Class Reference provides a table containing a brief description of all members in the API. This is the original entry page of the API documentation and can be used to navigate to classes within the API.


This tutorial provides information on using the common features provided in the KeyStore API.

  1. Using the KeyStore API provides a quick lesson on the basics of using the keyStore. It provides examples of the most basic KeyStore operations including: adding and removing keys and certificates from the keyStore, retrieving keys and certificates from the keyStore, and adding an index to the KeyStore.
  2. Using the KeyStore Index is a lesson on KeyStore Indexes. KeyStore indexes allow you to search and retrieve data based on a search parameter.

    The KeyStore API provides three types of indexes: the LabelKeyStoreIndex allows you to search through the KeyStore elements by label. The PrivateKeysKeyStoreIndex allows you to search through the KeyStore based on elements with associated private keys. Lastly, the AssociatedDataKeyStoreIndex allows you to search through the KeyStore based on the element associations.

  3. Implementing your own KeyStore provides notes and suggestions to consider when implementing your own custom KeyStore and KeyStoreData classes.