net.rim.device.api.crypto
Class CryptoSmartCardKeyStoreData

java.lang.Object
  extended by net.rim.device.api.crypto.CryptoSmartCardKeyStoreData
All Implemented Interfaces:
KeyStoreData, Persistable

public class CryptoSmartCardKeyStoreData
extends Object
implements KeyStoreData

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:
BlackBerry API 4.1.0

Constructor Summary
Category: Signed CryptoSmartCardKeyStoreData(AssociatedData[] associatedData, String label, PrivateKey privateKey, SymmetricKey symmetricKey, int securityLevel, Certificate certificate, CertificateStatus certStatus, PublicKey publicKey, long keyUsage)
          Adds a KeyStoreData class containing the information that will be associated with the array of aliases contained inside this class.
 
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 the data that is associated with the long passed into this method.
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()
          Returns the private key contained within the key store data.
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  CertificateStatus getStatus()
          Retrieves the CertificateStatus for this object.
Category: Signed  SymmetricKey getSymmetricKey()
          Returns the symmetric key contained within 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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

CryptoSmartCardKeyStoreData

public CryptoSmartCardKeyStoreData(AssociatedData[] associatedData,
                                   String label,
                                   PrivateKey privateKey,
                                   SymmetricKey symmetricKey,
                                   int securityLevel,
                                   Certificate certificate,
                                   CertificateStatus certStatus,
                                   PublicKey publicKey,
                                   long keyUsage)
Adds a KeyStoreData class containing the information that will be associated with the array of aliases contained inside this class.

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

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.
symmetricKey - A symmetric key to be stored in the key store.
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.

HighThe user will be asked for a passphrase
LowThe user will not be prompted.

Note: Once the security level is set it cannot be changed.

certificate - A certificate corresponding to this key store data.
certStatus - The certificate status that is accompanying the certificate for this key store data.
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.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0


Method Detail

getSymmetricKey

public SymmetricKey getSymmetricKey(KeyStoreDataTicket ticket)
Returns the symmetric key contained within the key store data.

Specified by:
getSymmetricKey in interface KeyStoreData
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.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getSymmetricKey

public SymmetricKey getSymmetricKey()
Returns the symmetric key contained within the key store data.

Returns:
The symmetric key or null if there is no symmetric key.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getPrivateKey

public PrivateKey getPrivateKey(KeyStoreDataTicket ticket)
Returns the private key contained within the key store data.

Specified by:
getPrivateKey in interface KeyStoreData
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.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getPrivateKey

public PrivateKey getPrivateKey()
Returns the private key contained within the key store data.

getTicket).

Returns:
The private 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 4.1.0

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.

Specified by:
isPrivateKeySet in interface KeyStoreData
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 4.1.0

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.

Specified by:
isSymmetricKeySet in interface KeyStoreData
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 4.1.0

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.

Specified by:
getPublicKey in interface KeyStoreData
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 4.1.0

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.

Specified by:
getCertificate in interface KeyStoreData
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 4.1.0

setLabel

public void setLabel(String newLabel)
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.

Specified by:
setLabel in interface KeyStoreData
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.

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

getLabel

public String getLabel()
Returns the label associated with this class.

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

Specified by:
getLabel in interface KeyStoreData
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 4.1.0

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

Specified by:
changePassword in interface 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 4.1.0

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.

Specified by:
queryKeyUsage in interface KeyStoreData
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 4.1.0

getAssociatedData

public byte[][] getAssociatedData(long association)
Returns the data that is associated with the long passed into this method.

Specified by:
getAssociatedData in interface KeyStoreData
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 4.1.0

getAssociatedData

public AssociatedData[] getAssociatedData()
Returns the data that is associated with the long passed into this method.

Specified by:
getAssociatedData in interface KeyStoreData
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 4.1.0

getTicket

public KeyStoreDataTicket getTicket()
Returns a ticket detailing what type of access the calling application has in the keystore.

This method may prompt for a passphrase from user.

Specified by:
getTicket in interface KeyStoreData
Returns:
The key store ticket.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getTicket

public KeyStoreDataTicket getTicket(String prompt)
Returns a ticket detailing what type of access the calling application has in the keystore.

This method may prompt for a passphrase from user.

Specified by:
getTicket in interface KeyStoreData
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.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

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.

Specified by:
checkTicket in interface KeyStoreData
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 4.1.0

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.

Specified by:
getSecurityLevel in interface KeyStoreData
Returns:
An integer representing the security level which is either KeyStore.SECURITY_LEVEL_HIGH 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 4.1.0

getPasswordVersion

public int getPasswordVersion()
Returns the current password version of this KeyStoreData object.

Specified by:
getPasswordVersion in interface 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 4.1.0

getStatus

public CertificateStatus getStatus()
Retrieves the CertificateStatus for this object.

Returns:
the current CertificateStatus stored for this smart card key store data on the device. 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 6.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal