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

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

All Implemented Interfaces:

CollectionEventSource, KeyStore

Direct Known Subclasses:

PersistableRIMKeyStore

public class RIMKeyStore
extends Object
implements KeyStore, CollectionEventSource

This class contains the basic key store implementation. It will store keys but only temporarily (until the device is reset) so it should NOT be used to store permanent keys. For sample code on how to use a key store see: here

NOTE: In previous versions of this api, there was a protected variable ( called _vector ) that a subclass could use to access all of the members of the keystore. This variable has been made private since there wasn't enough functionality exposed to really make use of it. If you need to access all of the KeyStoreData members for this class, use the elements() function.

See Also:

PersistableRIMKeyStore, SyncableRIMKeyStore

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 interface net.rim.device.api.crypto.keystore.KeyStore

SECURITY_LEVEL_HIGH, SECURITY_LEVEL_LOW, SECURITY_LEVEL_MEDIUM, SECURITY_LEVEL_NOT_APPLICABLE

Constructor Summary
		RIMKeyStore(String name) This constructor allows the developer to create a key store with no underlying keystore.
	protected	RIMKeyStore(String name, String className, long id, CodeSigningKey key, KeyStore keyStore) A protected constructor used for the subclasses who extend this class directly.
	protected	RIMKeyStore(String name, String className, long id, CodeSigningKey key, KeyStore keyStore, Vector vector)
		RIMKeyStore(String name, KeyStore keyStore) This constructor allows one to create a key store with an underlying key store.

Method Summary
	void	addCollectionListener(Object listener) Registers a listener to receive collection events.
	boolean	addIndex(KeyStoreIndex index) Adds an index to all of the information currently in the key store.
	void	addIndices(KeyStoreIndex[] indices) Adds an array of indices to 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.
	boolean	checkTicket(KeyStoreTicket ticket) Checks the validity of the ticket.
	protected void	deleteKey(KeyStoreData data) A protected function to allow a subclass to remove a key without a ticket prompt.
	Enumeration	elements() Returns an enumeration of all the KeyStoreData[] that are stored in the KeyStore.
	Enumeration	elements(boolean backingKeyStore) Returns an enumeration of all the KeyStoreData that are stored in the KeyStore AND the backing keystore if the boolean is set to true.
	Enumeration	elements(long index) Returns an enumeration of all the elements KeyStoreData inside the key store according to the index provided with the parameter.
	Enumeration	elements(long index, boolean backingKeyStore) Returns an enumeration of all the elements KeyStoreData inside the key store according to the index provided with the parameter.
	Enumeration	elements(long index, Object target) Returns an array of keystore information that contains the certificates, keys and other data associated with this alias.
	Enumeration	elements(long index, Object target, boolean backingKeyStore) Returns an array of keystore information that contains the certificates, keys and other data associated with this alias.
	boolean	exists(long index, Object target) Returns a boolean denoting whether an object exists with the given alias and the given index class.
	boolean	existsIndex(long index) Returns a boolean denoting whether this index already exists in the key store.
	KeyStore	getBackingKeyStore() This method returns the backing keystore if it exists.
	String	getName() Returns the name of the key store.
	KeyStoreTicket	getTicket() Returns a ticket that allows the caller to use the keystore without prompting the user for their password.
	KeyStoreTicket	getTicket(String prompt) Returns a ticket that allows the caller to use the keystore without prompting the user for their password.
	boolean	isMember(byte[] certificateEncoding) Returns a boolean dictating whether or not this certificate is contained inside the KeyStore.
	boolean	isMember(Key key) Returns a boolean dictating whether or not this key is contained inside the KeyStore.
	boolean	isMember(Certificate certificate) Returns a boolean dictating whether or not this certificate is contained inside the KeyStore.
	boolean	isMember(KeyStoreData data) Returns a boolean dictating whether or not this KeyStoreData is contained inside the KeyStore.
	void	removeCollectionListener(Object listener) Removes a listener object from the list of those receiving events.
	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.
	protected KeyStoreData	set(AssociatedData[] associatedData, String label, PrivateKey privateKey, String privateKeyEncodingAlgorithm, int securityLevel, PublicKey publicKey, long keyUsage, Certificate certificate, CertificateStatus status, KeyStoreTicket ticket)
	KeyStoreData	set(AssociatedData[] associatedData, String label, PrivateKey privateKey, String privateKeyEncodingAlgorithm, int securityLevel, PublicKey publicKey, long keyUsage, 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, PrivateKey privateKey, String privateKeyEncodingAlgorithm, int securityLevel, 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, PrivateKey privateKey, String privateKeyEncodingAlgorithm, int securityLevel, 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, PublicKey publicKey, long keyUsage, 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.
	KeyStoreData	set(AssociatedData[] associatedData, String label, 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.
	protected void	set(AssociatedData[] associatedData, KeyStoreData data) Adds a KeyStoreData class containing the information that will be associated with the array of aliases contained inside this class.
	int	size() Returns the number of elements inside the key store.

Methods inherited from class java.lang.Object

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

Constructor Detail

RIMKeyStore

public RIMKeyStore(String name)
            throws KeyStoreRegisterException

This constructor allows the developer to create a key store with no underlying keystore.

Note that a RIMKeyStore does not allow for the record to be persisted. That means that anything you place in this keystore will be lost when the device is reset. It will mostly be used for temporary key stores and nothing more. For a persistent key store, please see the subclass.

Parameters:

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

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

RIMKeyStore

public RIMKeyStore(String name,
                   KeyStore keyStore)
            throws KeyStoreRegisterException

This constructor allows one to create a key store with an underlying key store.

Note that a RIMKeyStore does not allow for the record to be persisted. That means that anything you place in this keystore will be lost when the device is reset. It will mostly be used for temporary key stores and nothing more. For a persistent key store, please see the subclass.

Parameters:

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

keyStore - An underlying keystore that can be used to search through when keys are not found in this current keystore.

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

RIMKeyStore

protected RIMKeyStore(String name,
                      String className,
                      long id,
                      CodeSigningKey key,
                      KeyStore keyStore)
               throws KeyStoreRegisterException

A protected constructor used for the subclasses who extend this class directly.

It allows for a string for registration info to be sent down and to ensure that only one registration request needs to occur.

Parameters:

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

className - A string containing the class name of the factory that we are going to instantiate after a reset.

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.

keyStore - An additional underlying keystore where requests are sent when the data is not found in this keystore.

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

KeyStoreRegisterException - Thrown if the class could not be instantiated correctly.

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

RIMKeyStore

protected RIMKeyStore(String name,
                      String className,
                      long id,
                      CodeSigningKey key,
                      KeyStore keyStore,
                      Vector vector)
               throws KeyStoreRegisterException

Throws:

KeyStoreRegisterException

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

Method Detail

set

public KeyStoreData set(AssociatedData[] associatedData,
                        String label,
                        PrivateKey privateKey,
                        String privateKeyEncodingAlgorithm,
                        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

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.

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. Note: This method does not affect any underlying keystores.

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 3.6.0

set

public KeyStoreData set(AssociatedData[] associatedData,
                        String label,
                        PrivateKey privateKey,
                        String privateKeyEncodingAlgorithm,
                        int securityLevel,
                        PublicKey publicKey,
                        long keyUsage,
                        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

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 data associated with the private key that will be stored in the key store. Note that we make no restrictions on what is stored in these records. The public key does not have to match the private key (make a key pair) if not desired. Note: This method does not affect any underlying keystores.

keyUsage - Specifies the key usage of the key - see KeyUsage. These fields can be OR'd together to produce the correct key usage stored as an integer.

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 3.6.0

set

public KeyStoreData set(AssociatedData[] associatedData,
                        String label,
                        PrivateKey privateKey,
                        String privateKeyEncodingAlgorithm,
                        int securityLevel,
                        Certificate certificate,
                        CertificateStatus certStatus,
                        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

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. Note: This method does not affect any underlying keystores.

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

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 3.6.0

set

public KeyStoreData set(AssociatedData[] associatedData,
                        String label,
                        PublicKey publicKey,
                        long keyUsage,
                        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

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. Note: This method does not affect any underlying keystores.

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.

publicKey - The public key data associated with the private key that will be stored in the key store. Note that we make no restrictions on what is stored in these records. The public key does not have to match the private key (make a key pair) if not desired.

keyUsage - Specifies the key usage of the key - see KeyUsage. These fields can be OR'd together to produce the correct key usage stored as an integer.

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 3.6.0

set

public KeyStoreData set(AssociatedData[] associatedData,
                        String label,
                        Certificate certificate,
                        CertificateStatus certStatus,
                        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

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. Note: This method does not affect any underlying keystores.

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.

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

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 3.6.0

set

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

Throws:

NoSuchAlgorithmException

InvalidKeyEncodingException

InvalidKeyException

CryptoTokenException

CryptoUnsupportedOperationException

KeyStoreCancelException

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

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 3.6.0

set

protected void set(AssociatedData[] associatedData,
                   KeyStoreData data)

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

Parameters:

associatedData - An associated data array containing all of the aliases to index this record on in the keystore.

data - The information that is to be stored in 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

elements

public Enumeration elements(long index,
                            Object target)

Description copied from interface: KeyStore

Returns an array of keystore information that contains the certificates, keys and other data associated with this alias. Note that this method will not return any records from the underlying keystore UNLESS there are no records found in the existing keystore. If you want it to always search the underlying keystore as well then use the other method with the boolean.

Specified by:

elements in interface KeyStore

Parameters:

index - A string representing the Index class that denotes where to find the alias and how it is used.

target - An object denoting which key store information should be returned.

Returns:

An Enumeration of KeyStoreData objects.

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

elements

public Enumeration elements(long index,
                            Object target,
                            boolean backingKeyStore)

Description copied from interface: KeyStore

Returns an array of keystore information that contains the certificates, keys and other data associated with this alias. This method will search the backing keystore if the boolean is set to true. If set to false it will have the same behavior as the other similar elements method.

Specified by:

elements in interface KeyStore

Parameters:

index - A string representing the Index class that denotes where to find the alias and how it is used.

target - An object denoting which key store information should be returned.

backingKeyStore - a boolean denoting whether or not to automatically search through the underlying key store.

Returns:

An Enumeration of KeyStoreData objects.

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

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

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

deleteKey

protected final void deleteKey(KeyStoreData data)

A protected function to allow a subclass to remove a key without a ticket prompt.

Parameters:

data - The KeystoreData 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 4.0.0

elements

public Enumeration elements()

Description copied from interface: KeyStore

Returns an enumeration of all the KeyStoreData[] that are stored in the KeyStore. Note that this function will not return any elements from the backing keystore.

Specified by:

elements in interface KeyStore

Returns:

An Enumeration of KeyStoreData objects.

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

elements

public Enumeration elements(boolean backingKeyStore)

Description copied from interface: KeyStore

Returns an enumeration of all the KeyStoreData that are stored in the KeyStore AND the backing keystore if the boolean is set to true. If the boolean is set to false then it simply returns all the elements in the current keystore.

Specified by:

elements in interface KeyStore

Returns:

An Enumeration of KeyStoreData objects.

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

elements

public Enumeration elements(long index)

Description copied from interface: KeyStore

Returns an enumeration of all the elements KeyStoreData inside the key store according to the index provided with the parameter. Note that this method will NOT return any elements from the backing keystore.

Specified by:

elements in interface KeyStore

Parameters:

index - A long representing what index to return an enumeration of the elements for.

Returns:

An enumeration of all the KeyStoreData items.

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

elements

public Enumeration elements(long index,
                            boolean backingKeyStore)

Description copied from interface: KeyStore

Returns an enumeration of all the elements KeyStoreData inside the key store according to the index provided with the parameter.

Specified by:

elements in interface KeyStore

Parameters:

index - A long representing what index to return an enumeration of the elements for.

backingKeyStore - a boolean which determines whether elements should also be returned from the backing keystore.

Returns:

An enumeration of all the KeyStoreData items.

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

exists

public boolean exists(long index,
                      Object target)

Description copied from interface: KeyStore

Returns a boolean denoting whether an object exists with the given alias and the given index class. Note that this function does not look in the underlying keystore.

Specified by:

exists in interface KeyStore

Parameters:

index - The long denoting the index class.

target - An object representing the alias to the key store information.

Returns:

Returns true if the object exists, 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 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

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

addIndices

public void addIndices(KeyStoreIndex[] indices)

Description copied from interface: KeyStore

Adds an array of indices to the key store. This method allows us to take advantage of possible overlaps in indexing 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 indices to the underlying keystore.

Specified by:

addIndices in interface KeyStore

Parameters:

indices - An array of Index classes 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.

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

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

existsIndex

public boolean existsIndex(long index)

Description copied from interface: KeyStore

Returns a boolean denoting whether this index already exists in the key store. Note: This does not check the underlying keystore.

Specified by:

existsIndex in interface KeyStore

Parameters:

index - The long representing the index.

Returns:

A boolean that returns true if the index 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

size

public int size()

Description copied from interface: KeyStore

Returns the number of elements inside the key store.

Specified by:

size in interface KeyStore

Returns:

An integer that specifies the size.

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()
                    throws KeyStoreDecodeRuntimeException

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

Throws:

KeyStoreDecodeRuntimeException

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

getName

public String getName()

Description copied from interface: KeyStore

Returns the name of the key store.

Specified by:

getName in interface KeyStore

Returns:

The name of the 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.6.0

isMember

public boolean isMember(Certificate certificate)

Description copied from interface: KeyStore

Returns a boolean dictating whether or not this certificate is contained inside the KeyStore. Note: This does not check the underlying keystore.

Specified by:

isMember in interface KeyStore

Parameters:

certificate - The specified certificate.

Returns:

A boolean that specifies if the certificate was found within the key store. Returns true if the certificate was found.

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

isMember

public boolean isMember(byte[] certificateEncoding)

Description copied from interface: KeyStore

Returns a boolean dictating whether or not this certificate is contained inside the KeyStore. Note: This does not check the underlying keystore.

Specified by:

isMember in interface KeyStore

Parameters:

certificateEncoding - The encoding of the specified certificate.

Returns:

A boolean that specifies if the certificate was found within the key store. Returns true if the certificate was found.

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

isMember

public boolean isMember(Key key)

Description copied from interface: KeyStore

Returns a boolean dictating whether or not this key is contained inside the KeyStore.

Note that a key can represent a PublicKey, PrivateKey, or SymmetricKey at this time.

Note: This does not check the underlying keystore.

Specified by:

isMember in interface KeyStore

Parameters:

key - The specified key.

Returns:

A boolean that specifies if the key was found within the key store. Returns true if the key was found.

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

isMember

public boolean isMember(KeyStoreData data)

Description copied from interface: KeyStore

Returns a boolean dictating whether or not this KeyStoreData is contained inside the KeyStore. Note: This does not check the underlying keystore.

Specified by:

isMember in interface KeyStore

Parameters:

data - The key store data.

Returns:

A boolean that determines if the specified key store data is found within the key store. Returns true if the data was found.

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

getTicket

public KeyStoreTicket getTicket()
                         throws KeyStoreCancelException

Description copied from interface: KeyStore

Returns a ticket that allows the caller to use the keystore without prompting the user for their password.

This method may prompt for a passphrase from the user.

Specified by:

getTicket in interface KeyStore

Returns:

The key store ticket.

Throws:

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 3.6.0

getTicket

public KeyStoreTicket getTicket(String prompt)
                         throws KeyStoreCancelException

Description copied from interface: KeyStore

Returns a ticket that allows the caller to use the keystore without prompting the user for their password.

This method may prompt for a passphrase from the user.

Specified by:

getTicket in interface KeyStore

Parameters:

prompt - an additional string provided to the allow the application developer to customize the ticket prompt dialog to better fit their application needs.

Returns:

The key store ticket.

Throws:

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 3.6.0

checkTicket

public boolean checkTicket(KeyStoreTicket ticket)

Checks the validity of the ticket.

Specified by:

checkTicket in interface KeyStore

Parameters:

ticket - The specified ticket.

Returns:

A boolean that represents validity of the ticket. Returns true if the ticket is valid, 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 3.6.0

addCollectionListener

public void addCollectionListener(Object listener)

Registers a listener to receive collection events. Note: object parameters that are passed back to the listener when an event occurs should be down cast to a KeyStoreData object.

Specified by:

addCollectionListener in interface CollectionEventSource

Specified by:

addCollectionListener in interface KeyStore

Parameters:

listener - Object to register as a listener which must implement CollectionListener or one of its derived interfaces.

See Also:

CollectionEventSource.addCollectionListener(java.lang.Object)

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

removeCollectionListener

public void removeCollectionListener(Object listener)

Removes a listener object from the list of those receiving events. Note: object parameters that are passed back to the listener when an event occurs should be down cast to a KeyStoreData object.

Specified by:

removeCollectionListener in interface CollectionEventSource

Specified by:

removeCollectionListener in interface KeyStore

Parameters:

listener - Listener to remove.

See Also:

CollectionEventSource.removeCollectionListener(java.lang.Object)

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

getBackingKeyStore

public KeyStore getBackingKeyStore()

Description copied from interface: KeyStore

This method returns the backing keystore if it exists. The backing keystore is a keystore that the creator of the existing keystore passed into the constructor. It allows for chaining of existing keystores using the get and elements method. The biggest advantage of the backing keystore is during searching for a KeyStoreData record. In the case where it is not found in the current keystore the code will look in the backing keystore if one exists.

Specified by:

getBackingKeyStore in interface KeyStore

Returns:

the backing KeyStore if it exists and null 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 3.6.0