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

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

All Implemented Interfaces:

CollectionEventSource, KeyStore

public class CombinedKeyStore
extends Object
implements KeyStore

This class allows a developer to combine several keystores into what looks like one keystore.

This is useful when you have several keystores that might contain the key you are looking for. You can combine these keystores temporarily and search through them.

Note: It should be noted that some operations do not make sense to operate on a collection of keystores. For example, the set method would add a new key to a keystore. It does not make sense to add the new key automatically to all of the keystores. So, the concept of a preferred keystore exists to enable those kinds of operations to be performed on one of the keystores. Any operation that only operates on a preferred key store is denoted as such. Ensure that you check the javadocs for each function you are calling so you know exactly what operations are being performed.

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

Category:

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

Since:

BlackBerry API 3.6.0

Field Summary

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
	CombinedKeyStore(KeyStore[] keyStores) Initializes the combined keystore with an array of underlying keystores.
	CombinedKeyStore(KeyStore[] keyStores, int preferredKeyStore) Initializes the combined keystore with an array of underlying keystores.

Method Summary
	void	addCollectionListener(Object listener) This method is called when the developer wants to listen in on when records are added and removed to/from a particular keystore.
	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 all of the information currently in the key store.
	void	addKeyStores(KeyStore[] keyStores) Allows for the addition of more keystores to the combined key store.
	void	changePreferredKeyStore(int newPreferredKeyStore) Allows you to change the preferred key store.
	boolean	checkTicket(KeyStoreTicket ticket) Calls the checkTicket method on the preferred key store.
	Enumeration	elements() Returns an enumeration of the KeyStoreData that are stored in the KeyStore.
	Enumeration	elements(boolean backingKeyStore) Returns an enumeration of the KeyStoreData that are stored in the KeyStore.
	Enumeration	elements(long index) Returns an enumeration of 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 the elements (KeyStoreData) inside the key store according to the index provided with the parameter.
	Enumeration	elements(long index, Object associatedData) Returns an array of keystore information that contains the certificates, keys and other data associated with this alias.
	Enumeration	elements(long index, Object associatedData, 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 associatedData) 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 for the preferred keystore currently set in the combined keystore.
	KeyStore	getKeyStore(int index) This method returns the KeyStore associated with the index specified as the only parameter.
	String	getName() Returns the name of the preferred key store.
	int	getNumKeyStores() This method returns the number of keystores that are currently contained in the CombinedKeyStore.
	KeyStoreTicket	getTicket() Calls the getTicket method on the preferred key store.
	KeyStoreTicket	getTicket(String prompt) Calls the getTicket method on the preferred key store.
	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) This method is called when the developer wants to remove the listener from this keystore.
	void	removeIndex(long index) Removes an index from all of the keystores in the combined keystore.
	void	removeKey(KeyStoreData data, KeyStoreTicket ticket) Remove the key from the preferred keystore.
	void	removeKeyStore(int index) Allows you to remove a keystore from the combined keystore.
	KeyStoreData	set(AssociatedData[] associatedData, String label, PrivateKey privateKey, String privateKeyEncodingAlgorithm, int securityLevel, PublicKey publicKey, long keyUsage, KeyStoreTicket ticket) Sets a new key into the preferred keystore.
	KeyStoreData	set(AssociatedData[] associatedData, String label, PrivateKey privateKey, String privateKeyEncodingAlgorithm, int securityLevel, Certificate certificate, CertificateStatus certStatus, KeyStoreTicket ticket) Sets a new key into the preferred keystore.
	KeyStoreData	set(AssociatedData[] associatedData, String label, PrivateKey privateKey, String privateKeyEncodingAlgorithm, int securityLevel, KeyStoreTicket ticket) Sets a new key into the preferred keystore.
	KeyStoreData	set(AssociatedData[] associatedData, String label, PublicKey publicKey, long keyUsage, KeyStoreTicket ticket) Sets a new key into the preferred keystore.
	KeyStoreData	set(AssociatedData[] associatedData, String label, SymmetricKey symmetricKey, String symmetricKeyEncodingAlgorithm, int securityLevel, KeyStoreTicket ticket) Sets a new key into the preferred keystore.
	KeyStoreData	set(AssociatedData[] associatedData, String label, Certificate certificate, CertificateStatus certStatus, KeyStoreTicket ticket) Sets a new key into the preferred keystore.
	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

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

changePassword

Constructor Detail

CombinedKeyStore

public CombinedKeyStore(KeyStore[] keyStores)

Initializes the combined keystore with an array of underlying keystores.

You can also add to this array later on if desired. It should be noted that by default the preferred keystore will be the first keystore given in the array unless otherwise specified.

Parameters:

keyStores - The array of keystores that you want as part of the combined 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

CombinedKeyStore

public CombinedKeyStore(KeyStore[] keyStores,
                        int preferredKeyStore)

Initializes the combined keystore with an array of underlying keystores.

You can also add to this array later on if desired.

Parameters:

keyStores - The array of keystores that you want as part of the combined keystore.

preferredKeyStore - An integer representing the index within the array of keystores that will be considered the preferred keystore. The preferred keystore will be the keystore that new keys are added to and other operations that are not obviously made for multiple key stores. (i.e. anything that causes a change in the state of a keystore). Remember that arrays are indexed at zero. Hence, if you want the very first keystore to be the preferred keystore it would have an index of 0.

Category:

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

Since:

BlackBerry API 3.6.0

Method Detail

set

public KeyStoreData set(AssociatedData[] associatedData,
                        String label,
                        PrivateKey privateKey,
                        String privateKeyEncodingAlgorithm,
                        int securityLevel,
                        KeyStoreTicket ticket)
                 throws NoSuchAlgorithmException,
                        InvalidKeyEncodingException,
                        CryptoTokenException,
                        CryptoUnsupportedOperationException,
                        KeyStoreCancelException,
                        InvalidKeyException

Sets a new key into the preferred keystore.

The new key exists exactly as it did in the original keystore implementation.

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.

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.

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,
                        CryptoTokenException,
                        CryptoUnsupportedOperationException,
                        KeyStoreCancelException,
                        InvalidKeyException

Sets a new key into the preferred keystore.

The new key exists exactly as it did in the original keystore implementation.

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.

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.

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

Sets a new key into the preferred keystore.

The new key exists exactly as it did in the original keystore implementation.

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

Sets a new key into the preferred keystore.

The new key exists exactly as it did in the original keystore implementation.

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

Sets a new key into the preferred keystore.

The new key exists exactly as it did in the original keystore implementation.

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

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

Sets a new key into the preferred keystore.

The new key exists exactly as it did in the original keystore implementation.

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

elements

public Enumeration elements(long index,
                            Object associatedData)

Returns an array of keystore information that contains the certificates, keys and other data associated with this alias.

Specified by:

elements in interface KeyStore

Parameters:

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

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

Returns:

An enumeration of all of the keystore data objects ( KeyStoreData ) that fit the description given by the index and alias.

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 associatedData,
                            boolean backingKeyStore)

Returns an array of keystore information that contains the certificates, keys and other data associated with this alias.

Specified by:

elements in interface KeyStore

Parameters:

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

associatedData - 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 all of the keystore data objects ( KeyStoreData ) that fit the description given by the index and alias.

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

Remove the key from the preferred 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

elements

public Enumeration elements()

Returns an enumeration of the KeyStoreData that are stored in the KeyStore. Note that this is akin to retrieving an enumeration of all the keys in every keystore in the combined keystore. Note that this function will not return any KeyStoreData records from the backing keystore.

Specified by:

elements in interface KeyStore

Returns:

An enumeration of keystore data objects ( KeyStoreData ).

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)

Returns an enumeration of the KeyStoreData that are stored in the KeyStore. Note that this is akin to retrieving an enumeration of all the keys in every keystore in the combined keystore.

Specified by:

elements in interface KeyStore

Parameters:

backingKeyStore - if true this method will return the elements from the backing key store as well.

Returns:

An enumeration of keystore data objects ( KeyStoreData ).

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)

Returns an enumeration of 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.

Returns:

An enumeration of keystore data objects ( KeyStoreData ).

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)

Returns an enumeration of 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 keystore data objects ( KeyStoreData ).

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

Returns a boolean denoting whether an object exists with the given alias and the given index class.

Specified by:

exists in interface KeyStore

Parameters:

index - The long denoting the index class.

associatedData - An object representing the associated data to the key store information.

Returns:

A boolean that indicates if the object 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

addIndex

public boolean addIndex(KeyStoreIndex index)

Adds an index to all of the information currently in the key store.

This enables the developer to access information in the key store according to this new associatedData field. For a combined key store this will add the index to all of the underlying keystores.

Specified by:

addIndex in interface KeyStore

Parameters:

index - An Index class that is implemented by the developer. It denotes 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. Return false if the index already exists. This method may return false if the index exists in one of the many keystores in the combined keystore. It will however be added to any of the keystores that this index is not already added to even if it returns false.

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)

Adds an array of indices to all of the information currently in the key store.

This enables the developer to access information in the key store according to this new associatedData field. For a combined key store this will add the index to all of the underlying keystores.

Specified by:

addIndices in interface KeyStore

Parameters:

indices - A KeyStoreIndex class that is implemented by the developer. It denotes 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)

Removes an index from all of the keystores in the combined keystore.

Specified by:

removeIndex in interface KeyStore

Parameters:

index - the long representing the ID of the index 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)

Returns a boolean denoting whether this index already exists in the key store. In the combined keystore this will return a boolean if and only if all of the keystores underlying the combined keystore have an index specified as the parameter.

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

Returns the number of elements inside the key store.

For the combined key store this returns the number of elements in all of the keystores added together. That is, if you had five elements in one key store and six elements in a second key store then this would return 11 elements.

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

addKeyStores

public void addKeyStores(KeyStore[] keyStores)

Allows for the addition of more keystores to the combined key store.

Note This will not make the distinction of checking to see if a keystore has already been added to the combined keystore. This is left to the developer since there is no real way to uniquely identify a keystore.

Parameters:

keyStores - An array of additional key stores that will be added to the combined 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

removeKeyStore

public void removeKeyStore(int index)
                    throws IllegalArgumentException

Allows you to remove a keystore from the combined keystore.

Parameters:

index - the index into the array of keystores that you would like to remove.

Throws:

IllegalArgumentException - Thrown if the integer is not in the following range 0 < x < size where x is the new preferred key store and size is the number of keystores currently in the combined 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

changePreferredKeyStore

public void changePreferredKeyStore(int newPreferredKeyStore)
                             throws IllegalArgumentException

Allows you to change the preferred key store. This will now be the keystore that will have all of the modifying operations performed on it.

Parameters:

newPreferredKeyStore - A new key store index that will be used to index into the array of stored keystores.

Throws:

IllegalArgumentException - Thrown if the integer is not in the following range 0 < x < size where x is the new preferred key store and size is the number of keystores currently in the combined 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

getTicket

public KeyStoreTicket getTicket()
                         throws KeyStoreCancelException

Calls the getTicket method on the preferred key store.

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

Calls the getTicket method on the preferred key store.

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)

Calls the checkTicket method on the preferred key store.

Specified by:

checkTicket in interface KeyStore

Parameters:

ticket - the KeyStoreTicket we want to check.

Returns:

true if the ticket is valid for this record 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 3.6.0

getName

public String getName()

Returns the name of the preferred 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)

Returns a boolean dictating whether or not this certificate is contained inside the 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)

Returns a boolean dictating whether or not this certificate is contained inside the 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)

Returns a boolean dictating whether or not this key is contained inside the 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)

Returns a boolean dictating whether or not this KeyStoreData is contained inside the 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

addCollectionListener

public void addCollectionListener(Object listener)

This method is called when the developer wants to listen in on when records are added and removed to/from a particular keystore. This method will add a collection listener to all of the keystores in this combined keystore. Note: This does not add the listener to the underlying keystore.

Specified by:

addCollectionListener in interface CollectionEventSource

Specified by:

addCollectionListener in interface KeyStore

Parameters:

listener - The KeyStoreListener interface that must be implemented by the calling class which will be called when a record is added or removed.

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)

This method is called when the developer wants to remove the listener from this keystore. This method will add a collection listener to all of the keystores in this combined keystore. Note: This does not remove the listener from the underlying keystore.

Specified by:

removeCollectionListener in interface CollectionEventSource

Specified by:

removeCollectionListener in interface KeyStore

Parameters:

listener - The KeyStoreListener to be removed.

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

This method returns the backing keystore for the preferred keystore currently set in the combined keystore.

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

getNumKeyStores

public int getNumKeyStores()

This method returns the number of keystores that are currently contained in the CombinedKeyStore. This allows one to find out exactly which KeyStores are contained in the CombinedKeyStore.

Returns:

the number of KeyStores contained in the CombinedKeyStore.

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

getKeyStore

public KeyStore getKeyStore(int index)
                     throws IllegalArgumentException

This method returns the KeyStore associated with the index specified as the only parameter. If this index is less than 0 or greater than the number of keystores then this will throw an IllegalArgumentException.

Parameters:

index - the index into the array of KeyStores that we should return.

Returns:

the KeyStore associated with the index passed into the method.

Throws:

IllegalArgumentException - if the index is invalid.

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