SHOW Signed

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

java.lang.Object
  |
  +--net.rim.device.api.crypto.keystore.RIMKeyStore
        |
        +--net.rim.device.api.crypto.keystore.PersistableRIMKeyStore
              |
              +--net.rim.device.api.crypto.keystore.SyncableRIMKeyStore
                    |
                    +--net.rim.device.api.crypto.keystore.TrustedKeyStore

All Implemented Interfaces:

Collection, CollectionEventSource, KeyStore

public final class TrustedKeyStore

extends SyncableRIMKeyStore

Implements the key storage necessary for storing keys used on the Blackberry Wireless Handheld. These keys would be used for applications such as browsing since they contain trusted keys. Trusted meaning that the user trusts the issuers of these keys.

For sample code on how to use a key store see: here

It is important to note that all keys placed in the trusted key store will be set to the SECURITY_LEVEL_HIGH security level (only applicable to private and symmetric keys).

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

See Also:

RIMKeyStore, SyncableRIMKeyStore, PersistableRIMKeyStore

Fields inherited from class net.rim.device.api.crypto.keystore.PersistableRIMKeyStore

_persist

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

_vector

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

SECURITY_LEVEL_HIGH, SECURITY_LEVEL_LOW

Method Summary

	boolean	checkTicket(KeyStoreTicket ticket) Returns a boolean denoting whether or not this ticket will work for this KeyStore.
	static KeyStore	getInstance() Returns an instance of the trusted key store.
	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.
	protected KeyStoreData	set(AssociatedData[] associatedData, String label, PrivateKey privateKey, String privateKeyEncodingAlgorithm, int securityLevel, PublicKey publicKey, long keyUsage, Certificate certificate, CertificateStatus certStatus, KeyStoreTicket ticket) Adds a KeyStoreData class containing the information that will be associated with the array of aliases contained inside this class.

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

getTicket, set

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

addIndex, changePassword, removeIndex

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

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

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static KeyStore getInstance()

Returns an instance of the trusted key store.

Note that you are not allowed to make any removals/overwrites to this key store and that any additions to this key will be checked for permissions before actually being executed. Any changes made with permission will be saved to the database.

Returns:

The keystore.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

set

protected KeyStoreData set(AssociatedData[] associatedData,
                           String label,
                           PrivateKey privateKey,
                           String privateKeyEncodingAlgorithm,
                           int securityLevel,
                           PublicKey publicKey,
                           long keyUsage,
                           Certificate certificate,
                           CertificateStatus certStatus,
                           KeyStoreTicket ticket)
                    throws NoSuchAlgorithmException,
                           InvalidKeyEncodingException,
                           InvalidKeyException,
                           CryptoTokenException,
                           CryptoUnsupportedOperationException,
                           KeyStoreCancelException

Adds a KeyStoreData class containing the information that will be associated with the array of aliases contained inside this class. It is important to note that only applications signed by RIM will be able to add keys to the TrustedKeyStore.

Note: ANY OF THESE PARAMETERS CAN BE NULL without causing any problems for the key store.

Overrides:

set in class RIMKeyStore

Parameters:

associatedData - An associated Data array containing all of the aliases to index this record on in the keystore. This can be null and we will simply rely on other indices added to the KeyStore to find your key.

label - The label that is shown to the user when the private key is accessed. This gives the user some information about what private key is being accessed so they can make a informed decision about inputting their private key password to unlock the key. It should be noted that this label will have a string prefixed to it such as "Please enter your passphrase for: " and then your string.

privateKey - The private key data to be stored in the keystore.

privateKeyEncodingAlgorithm - Allows the user to specify what encoding algorithm is used to encode the private key.

securityLevel - The security level associated with this key store data private key. That is, when someone attempts to access the private key they will be prompted according to the security level of the key store data.

High	The user will be asked for a passphrase
Low	The user will not be prompted.

Note: Once the security level is set it cannot be changed.

publicKey - the public key for this record.

keyUsage - this is only applicable for public keys. If one is specified you should specify the keyUsage. For certificates specify -1 and the keyusage will be taken from the certificate itself.

certificate - A certificate corresponding to this key store data.

certStatus - The certificate status that is accompanying the certificate for this key store data.

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:

NoSuchAlgorithmException - Thrown when the specified cipher is invalid.

InvalidKeyEncodingException - Thrown when the specified key is improperly formatted.

CryptoTokenException - Thrown when an error occurs with the crypto token or the crypto token is invalid.

CryptoUnsupportedOperationException - Thrown when a call is made to an unsupported operation.

KeyStoreCancelException - Thrown when the user fails to enter a password or decides to cancel the password entry operation.

InvalidKeyException - Thrown when the specified key is invalid.

ControlledAccessException - if you attempt to set a key into this keystore and you are not code signed by RIM.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

removeKey

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

Removes this key store data from the key store and ensures that any links to this object are removed from the key store. It is important to note that this method will not remove the key from the KeyStore unless the calling application has been code signed by RIM. Note: This does not affect the underlying keystore.

Overrides:

removeKey in class PersistableRIMKeyStore

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.

ControlledAccessException - if the calling application is not signed by RIM and yet they attempt to remove a key from the TrustedKeyStore.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

checkTicket

public boolean checkTicket(KeyStoreTicket ticket)

Returns a boolean denoting whether or not this ticket will work for this KeyStore. It is important to note that not only do you have to possess a valid ticket for this KeyStore but you also need to be signed by RIM for checkTicket to return true.

Overrides:

checkTicket in class SyncableRIMKeyStore

Parameters:

ticket - the KeyStoreTicket we want to check.

Returns:

true if the ticket is valid for this record and false otherwise.

Throws:

ControlledAccessException - thrown if someone attempts to check a ticket for this keystore and the code calling this method is not code signed by RIM.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.