SHOW Signed
 

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.

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:
JDE 3.6.0
See Also:
KeyStore, KeyStoreIndex

Method Summary
 Category: Signed  void changePassword()
          Changes the passphrase.
 Category: Signed  boolean checkTicket(KeyStoreDataTicket ticket)
          Returns a boolean denoting whether or not this ticket will work for this KeyStoreData record.
 Category: Signed  AssociatedData[] getAssociatedData()
          Returns an array of AssociatedData objects that were passed into this KeyStoreData.
 Category: Signed  byte[][] getAssociatedData(long association)
          Returns the data that is associated with the long passed into this method.
 Category: Signed  Certificate getCertificate()
          Returns the certificate that is stored in the key store data object.
 Category: Signed  String getLabel()
          Returns the label associated with this class.
 Category: Signed  int getPasswordVersion()
          Returns the current password version of this KeyStoreData object.
 Category: Signed  PrivateKey getPrivateKey(KeyStoreDataTicket ticket)
          Returns the private key contained within the key store data.
 Category: Signed  PublicKey getPublicKey()
          Returns the public key that is stored within the key store data object.
 Category: Signed  int getSecurityLevel()
          Returns the security level of the key store data.
 Category: Signed  SymmetricKey getSymmetricKey(KeyStoreDataTicket ticket)
          Returns the symmetric key contained within the key store data.
 Category: Signed  KeyStoreDataTicket getTicket()
          Returns a ticket detailing what type of access the calling application has in the keystore.
 Category: Signed  KeyStoreDataTicket getTicket(String prompt)
          Returns a ticket detailing what type of access the calling application has in the keystore.
 Category: Signed  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.
 Category: Signed  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.
 Category: Signed  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.
 Category: Signed  void setLabel(String newLabel)
          Sets the new label into the KeyStoreData record.
 

Method Detail

changePassword

public 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!!

Since:
JDE 3.6.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.

checkTicket

public 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.
Since:
JDE 3.6.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.

getAssociatedData

public 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.
Since:
JDE 3.6.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.

getAssociatedData

public 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.
Since:
JDE 3.6.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.

getCertificate

public 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.
Since:
JDE 3.6.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.

getLabel

public 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.
Since:
JDE 3.6.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.

getPasswordVersion

public 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.
Since:
JDE 3.6.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.

getPrivateKey

public 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.
Since:
JDE 3.6.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.

getPublicKey

public 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.
Since:
JDE 3.6.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.

getSecurityLevel

public 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 either KeyStore.SECURITY_LEVEL_HIGH or KeyStore.SECURITY_LEVEL_HIGH.
Since:
JDE 3.6.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.

getSymmetricKey

public 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.
Since:
JDE 3.6.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.

getTicket

public 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.
Since:
JDE 3.6.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.

getTicket

public 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.
Since:
JDE 3.6.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.

isPrivateKeySet

public 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.
Since:
JDE 3.6.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.

isSymmetricKeySet

public 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.
Since:
JDE 3.6.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.

queryKeyUsage

public 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.
Since:
JDE 3.6.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.

setLabel

public 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.
Since:
JDE 3.6.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.



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.