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:

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).

See Also:

RIMKeyStore, SyncableRIMKeyStore, PersistableRIMKeyStore

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

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

_persist

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

SECURITY_LEVEL_HIGH, SECURITY_LEVEL_LOW, SECURITY_LEVEL_MEDIUM, SECURITY_LEVEL_NOT_APPLICABLE

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.
	String	getName() Returns the localised string representing this key store name for the Trusted Key Store.
	boolean	isAllowed(Certificate certificate) This method determines if the certificate passed into the method is allowed to be added to the trusted key store in the presence of IT policy.
	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.
	KeyStoreData	set(AssociatedData[] associatedData, String label, SymmetricKey symmetricKey, String symmetricKeyEncodingAlgorithm, int securityLevel, 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, 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, deleteKey, elements, elements, elements, elements, elements, elements, exists, existsIndex, getBackingKeyStore, isMember, isMember, isMember, isMember, removeCollectionListener, 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 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

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.

SecurityException - if you attempt to set a key into this keystore and that certificate is not allowed according to the IT Policy specified by the IT Admin for this handheld.

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

set

public KeyStoreData set(AssociatedData[] associatedData,
                        String label,
                        SymmetricKey symmetricKey,
                        String symmetricKeyEncodingAlgorithm,
                        int securityLevel,
                        KeyStoreTicket ticket)
                 throws NoSuchAlgorithmException,
                        InvalidKeyEncodingException,
                        InvalidKeyException,
                        CryptoTokenException,
                        CryptoUnsupportedOperationException,
                        KeyStoreCancelException

Description copied from interface: KeyStore

Adds a KeyStoreData class containing the information that will be associated with the array of aliases contained inside this class.

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

Specified by:

set in interface KeyStore

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.

symmetricKey - A symmetric key to be stored in the key store.

symmetricKeyEncodingAlgorithm - The encoding algorithm associated with the 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. Note: This method does not affect any underlying keystores.

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).

Returns:

the KeyStoreData object that was added to the keystore.

Throws:

NoSuchAlgorithmException - Thrown when the specified cipher is invalid.

InvalidKeyEncodingException - Thrown when the specified key is improperly formatted.

InvalidKeyException - Thrown when the specified key is invalid.

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.

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 4.0.0

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.

Specified by:

removeKey in interface 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.

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

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.

Specified by:

checkTicket in interface KeyStore

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.

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

isAllowed

public boolean isAllowed(Certificate certificate)

This method determines if the certificate passed into the method is allowed to be added to the trusted key store in the presence of IT policy. IT Policy can be enabled to restrict the certificates that are allowed to be in the Trusted Key Store. As such, this method will tell a developer before attempting to actually place the certificate in the keystore whether or not it will be allowed.

Parameters:

certificate - the certificate to check for IT policy compliance.

Returns:

true if the certificate is allowed and false otherwise.

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 4.0.0

getName

public String getName()

Returns the localised string representing this key store name for the Trusted Key Store. In English it would return "Trusted Key Store".

Specified by:

getName in interface KeyStore

Overrides:

getName in class RIMKeyStore

Returns:

the localised name for the Trusted Key Store.

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.7.0