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:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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(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.
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.
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.
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.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
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 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
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 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
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 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
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 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
Note: You do not need to know the passphrase to access the label.
Returns:
A String representing the label.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
Returns the private key contained within the key store data.
getTicket).
Returns:
The private key. May be null.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
Returns the private key contained within the key store data.
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.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
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 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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_LOW.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
Returns the symmetric key contained within the key store data.
Returns:
The symmetric key or null if there is no symmetric key.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
Returns the symmetric key contained within the key store data.
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.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
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.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
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.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
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.
Since:
JDE 4.1.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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-2008 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.