net.rim.device.api.crypto.keystore
Interface KeyStoreData

All Superinterfaces:

Persistable, Persistable

All Known Implementing Classes:

CryptoSmartCardKeyStoreData

public interface KeyStoreData
extends Persistable

A container class used to store all of the key store information. This includes objects like certificates, keys, and other information. It should be noted that this class has UI functionality when it prompts for passphrases depending on the security level established with the key objects.

See Also:

KeyStore, KeyStoreIndex

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 Summary
	void	changePassword() Changes the passphrase.
	boolean	checkTicket(KeyStoreDataTicket ticket) Returns a boolean denoting whether or not this ticket will work for this KeyStoreData record.
	AssociatedData[]	getAssociatedData() Returns an array of AssociatedData objects that were passed into this KeyStoreData.
	byte[][]	getAssociatedData(long association) Returns the data that is associated with the long passed into this method.
	Certificate	getCertificate() Returns the certificate that is stored in the key store data object.
	String	getLabel() Returns the label associated with this class.
	int	getPasswordVersion() Returns the current password version of this KeyStoreData object.
	PrivateKey	getPrivateKey(KeyStoreDataTicket ticket) Returns the private key contained within the key store data.
	PublicKey	getPublicKey() Returns the public key that is stored within the key store data object.
	int	getSecurityLevel() Returns the security level of the key store data.
	SymmetricKey	getSymmetricKey(KeyStoreDataTicket ticket) Returns the symmetric key contained within the key store data.
	KeyStoreDataTicket	getTicket() Returns a ticket detailing what type of access the calling application has in the keystore.
	KeyStoreDataTicket	getTicket(String prompt) Returns a ticket detailing what type of access the calling application has in the keystore.
	boolean	isPrivateKeySet() Returns a boolean dictating whether or not the private key has been set for this record without actually requiring knowledge of the passphrase to access the private key.
	boolean	isSymmetricKeySet() Returns a boolean dictating whether or not the symmetric key has actually been set for this record without actually requiring knowledge of the passphrase to access the symmetric key.
	int	queryKeyUsage(long purpose) This method returns an integer that that specifies whether the usage for the key allows this key to be used for the given purpose.
	void	setLabel(String newLabel) Sets the new label into the KeyStoreData record.

Method Detail

getSymmetricKey

SymmetricKey getSymmetricKey(KeyStoreDataTicket ticket)
                             throws NoSuchAlgorithmException,
                                    InvalidKeyEncodingException,
                                    CryptoTokenException,
                                    CryptoUnsupportedOperationException,
                                    KeyStoreCancelException,
                                    KeyStoreDecodeException

Returns the symmetric key contained within the key store data.

NOTE: This method involves the use of UI and will prompt the user for the passphrase.

Parameters:

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

Returns:

The symmetric key or null if there is no symmetric key.

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 specified password is invalid.

KeyStoreDecodeException - Thrown when the underlying private was corrupted in some manner and the keystore was unable to retrieve it.

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

getPrivateKey

PrivateKey getPrivateKey(KeyStoreDataTicket ticket)
                         throws NoSuchAlgorithmException,
                                InvalidKeyEncodingException,
                                CryptoTokenException,
                                CryptoUnsupportedOperationException,
                                KeyStoreCancelException,
                                KeyStoreDecodeException

Returns the private key contained within the key store data.

NOTE: This method involves the use of UI and will prompt the user for the passphrase.

Parameters:

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

Returns:

The private key. May be null.

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 specified password is invalid.

KeyStoreDecodeException - Thrown when the underlying private was corrupted in some manner and the keystore was unable to retrieve it.

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

isPrivateKeySet

boolean isPrivateKeySet()

Returns a boolean dictating whether or not the private key has been set for this record without actually requiring knowledge of the passphrase to access the private key.

Returns:

A boolean denoting whether a private key has been set in this 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

isSymmetricKeySet

boolean isSymmetricKeySet()

Returns a boolean dictating whether or not the symmetric key has actually been set for this record without actually requiring knowledge of the passphrase to access the symmetric key.

Returns:

A boolean denoting whether a symmetric key has been set in this 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

getPublicKey

PublicKey getPublicKey()

Returns the public key that is stored within the key store data object.

Note: You do not need to know the passphrase to access the public key.

Returns:

The public key. May be null.

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

getCertificate

Certificate getCertificate()

Returns the certificate that is stored in the key store data object.

Note: You do not need to know the passphrase to access the certificate.

Returns:

The certificate. May be null.

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

setLabel

void setLabel(String newLabel)
              throws KeyStoreCancelException

Sets the new label into the KeyStoreData record. Note that this is the ONLY method which allows for any change in an existing KeyStoreData record.

Parameters:

newLabel - specifies the newLabel that will be set for this KeyStoreData. If this field is null the KeyStore will actually prompt for the new label for you.

Note: This method will pop up UI to ask for the new label given the old label and it will also ask for the password after asking for the new label. Note: You need to know the passphrase to set the label.

Throws:

KeyStoreCancelException - if the user cancels entering their password or cancels entering the new label.

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

getLabel

String getLabel()

Returns the label associated with this class.

Note: You do not need to know the passphrase to access the label.

Returns:

A String representing the label.

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

void changePassword()

Changes the passphrase. This changes the underlying passphrase of the key store data. It is the responsibility of the key store data to ensure that it correctly changes any internal structures that depend on the passphrase because otherwise they will become damaged (stale) after this function call. KeyStorePasswordManager provides the KeyStorePasswordManager.decryptReEncrypt(int, long, byte[]) method to decrypt and re-encrypt data.

Note for Implementors: If you are writing your own KeyStoreData class it is imperative that you implement this method correctly. If the password is changed and the structures inside the keystore are not updated then the keystore will be unable to decrypt the keys using the new password. This will essentially render the KeyStoreData class useless and perhaps even lost!!

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

queryKeyUsage

int queryKeyUsage(long purpose)

This method returns an integer that that specifies whether the usage for the key allows this key to be used for the given purpose.

Parameters:

purpose - This is the context or purpose that you are trying to determine if the key usage allows. See KeyUsage

Returns:

An integer specifying whether or not this usage is allowed, not allowed or not specified. See KeyUsageResult.

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

getAssociatedData

byte[][] getAssociatedData(long association)

Returns the data that is associated with the long passed into this method.

Parameters:

association - The long used to identify which data to return to the user.

Returns:

A byte array containing the data associated with the long passed in. May be null.

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

getAssociatedData

AssociatedData[] getAssociatedData()

Returns an array of AssociatedData objects that were passed into this KeyStoreData.

Returns:

An array of AssociatedData objects containing both the associated and data passed into this class. This may return null.

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

KeyStoreDataTicket getTicket()
                             throws KeyStoreCancelException

Returns a ticket detailing what type of access the calling application has in the keystore.

This method may prompt for a passphrase from user.

Returns:

The key store ticket.

Throws:

KeyStoreCancelException - Thrown if the user cancels 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

KeyStoreDataTicket getTicket(String prompt)
                             throws KeyStoreCancelException

Returns a ticket detailing what type of access the calling application has in the keystore.

This method may prompt for a passphrase from user.

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 if the user cancels 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

boolean checkTicket(KeyStoreDataTicket ticket)

Returns a boolean denoting whether or not this ticket will work for this KeyStoreData record. This is useful because it allows the developer to simply store the ticket and not have to store the KeyStoreData it is for in case there are several tickets being stored. As well, it will also be useful when you are about to retrieve data requiring a ticket and want to know whether or not the user is about to be prompted.

Parameters:

ticket - the KeyStoreDataTicket 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

getSecurityLevel

int getSecurityLevel()

Returns the security level of the key store data. This is typically one of two values. KeyStore.SECURITY_LEVEL_HIGH or KeyStore.SECURITY_LEVEL_LOW. If there is no private key in the KeyStoreData object then it will return the default security level which is KeyStore.SECURITY_LEVEL_HIGH.

Returns:

An integer representing the security level which is one of KeyStore.SECURITY_LEVEL_HIGH, KeyStore.SECURITY_LEVEL_MEDIUM, or KeyStore.SECURITY_LEVEL_LOW.

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

getPasswordVersion

int getPasswordVersion()

Returns the current password version of this KeyStoreData object. The password version indicates the version of the password that is used to protect the private key or symmetric key stored in this object. As such, if there is no private key or symmetric key then this method returns -1.

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