SHOW Signed
 

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

java.lang.Object
  |
  +--net.rim.device.api.crypto.keystore.RIMKeyStore
        |
        +--net.rim.device.api.crypto.keystore.PersistableRIMKeyStore
              |
              +--net.rim.device.api.crypto.keystore.SyncableRIMKeyStore
                    |
                    +--net.rim.device.api.crypto.keystore.TrustedKeyStore
All Implemented Interfaces:
Collection, CollectionEventSource, KeyStore

public final class TrustedKeyStore
extends SyncableRIMKeyStore

Implements the key storage necessary for storing keys used on the Blackberry Wireless Handheld. These keys would be used for applications such as browsing since they contain trusted keys. Trusted meaning that the user trusts the issuers of these keys.

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

It is important to note that all keys placed in the trusted key store will be set to the SECURITY_LEVEL_HIGH security level (only applicable to private and symmetric keys).

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:
RIMKeyStore, SyncableRIMKeyStore, PersistableRIMKeyStore

Field Summary
 
Fields inherited from class net.rim.device.api.crypto.keystore.PersistableRIMKeyStore
_persist
 
Fields inherited from interface net.rim.device.api.crypto.keystore.KeyStore
SECURITY_LEVEL_HIGH, SECURITY_LEVEL_LOW, SECURITY_LEVEL_MEDIUM, SECURITY_LEVEL_NOT_APPLICABLE
 
Method Summary
 Category: Signed  boolean checkTicket(KeyStoreTicket ticket)
          Returns a boolean denoting whether or not this ticket will work for this KeyStore.
 Category: Signed static KeyStore getInstance()
          Returns an instance of the trusted key store.
 Category: Signed  String getName()
          Returns the localised string representing this key store name for the Trusted Key Store.
 Category: Signed  boolean isAllowed(Certificate certificate)
          This method determines if the certificate passed into the method is allowed to be added to the trusted key store in the presence of IT policy.
 Category: Signed  void removeKey(KeyStoreData data, KeyStoreTicket ticket)
          Removes this key store data from the key store and ensures that any links to this object are removed from the key store.
 Category: Signed protected  KeyStoreData set(AssociatedData[] associatedData, String label, PrivateKey privateKey, String privateKeyEncodingAlgorithm, int securityLevel, PublicKey publicKey, long keyUsage, Certificate certificate, CertificateStatus certStatus, KeyStoreTicket ticket)
          Adds a KeyStoreData class containing the information that will be associated with the array of aliases contained inside this class.
 Category: Signed  KeyStoreData set(AssociatedData[] associatedData, String label, SymmetricKey symmetricKey, String symmetricKeyEncodingAlgorithm, int securityLevel, KeyStoreTicket ticket)
          Adds a KeyStoreData class containing the information that will be associated with the array of aliases contained inside this class.
 
Methods inherited from class net.rim.device.api.crypto.keystore.SyncableRIMKeyStore
getTicket, getTicket, set
 
Methods inherited from class net.rim.device.api.crypto.keystore.PersistableRIMKeyStore
addIndex, changePassword, removeIndex
 
Methods inherited from class net.rim.device.api.crypto.keystore.RIMKeyStore
addCollectionListener, addIndices, deleteKey, elements, elements, elements, elements, elements, elements, exists, existsIndex, getBackingKeyStore, isMember, isMember, isMember, isMember, removeCollectionListener, set, set, set, set, set, size
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

checkTicket

public boolean checkTicket(KeyStoreTicket ticket)
Returns a boolean denoting whether or not this ticket will work for this KeyStore. It is important to note that not only do you have to possess a valid ticket for this KeyStore but you also need to be signed by RIM for checkTicket to return true.

Overrides:
checkTicket in class SyncableRIMKeyStore
Parameters:
ticket - the KeyStoreTicket we want to check.
Returns:
true if the ticket is valid for this record and false otherwise.
Throws:
ControlledAccessException - thrown if someone attempts to check a ticket for this keystore and the code calling this method is not code signed by RIM.
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.

getInstance

public static KeyStore getInstance()
Returns an instance of the trusted key store.

Note that you are not allowed to make any removals/overwrites to this key store and that any additions to this key will be checked for permissions before actually being executed. Any changes made with permission will be saved to the database.

Returns:
The keystore.
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.

getName

public String getName()
Returns the localised string representing this key store name for the Trusted Key Store. In English it would return "Trusted Key Store".
Overrides:
getName in class RIMKeyStore
Returns:
the localised name for the Trusted Key Store.
Since:
JDE 3.7.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.

isAllowed

public boolean isAllowed(Certificate certificate)
This method determines if the certificate passed into the method is allowed to be added to the trusted key store in the presence of IT policy. IT Policy can be enabled to restrict the certificates that are allowed to be in the Trusted Key Store. As such, this method will tell a developer before attempting to actually place the certificate in the keystore whether or not it will be allowed.
Parameters:
certificate - the certificate to check for IT policy compliance.
Returns:
true if the certificate is allowed and false otherwise.
Since:
JDE 4.0.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.

removeKey

public void removeKey(KeyStoreData data,
                      KeyStoreTicket ticket)
               throws KeyStoreCancelException
Removes this key store data from the key store and ensures that any links to this object are removed from the key store. It is important to note that this method will not remove the key from the KeyStore unless the calling application has been code signed by RIM. Note: This does not affect the underlying keystore.

Overrides:
removeKey in class PersistableRIMKeyStore
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.
ControlledAccessException - if the calling application is not signed by RIM and yet they attempt to remove a key from the TrustedKeyStore.
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.

set

protected KeyStoreData set(AssociatedData[] associatedData,
                           String label,
                           PrivateKey privateKey,
                           String privateKeyEncodingAlgorithm,
                           int securityLevel,
                           PublicKey publicKey,
                           long keyUsage,
                           Certificate certificate,
                           CertificateStatus certStatus,
                           KeyStoreTicket ticket)
                    throws NoSuchAlgorithmException,
                           InvalidKeyEncodingException,
                           InvalidKeyException,
                           CryptoTokenException,
                           CryptoUnsupportedOperationException,
                           KeyStoreCancelException
Adds a KeyStoreData class containing the information that will be associated with the array of aliases contained inside this class. It is important to note that only applications signed by RIM will be able to add keys to the TrustedKeyStore.

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

Overrides:
set in class RIMKeyStore
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.

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.

publicKey - the public key for this record.
keyUsage - this is only applicable for public keys. If one is specified you should specify the keyUsage. For certificates specify -1 and the keyusage will be taken from the certificate itself.
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).
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.
ControlledAccessException - if you attempt to set a key into this keystore and you are not code signed by RIM.
SecurityException - if you attempt to set a key into this keystore and that certificate is not allowed according to the IT Policy specified by the IT Admin for this handheld.
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.

set

public KeyStoreData set(AssociatedData[] associatedData,
                        String label,
                        SymmetricKey symmetricKey,
                        String symmetricKeyEncodingAlgorithm,
                        int securityLevel,
                        KeyStoreTicket ticket)
                 throws NoSuchAlgorithmException,
                        InvalidKeyEncodingException,
                        InvalidKeyException,
                        CryptoTokenException,
                        CryptoUnsupportedOperationException,
                        KeyStoreCancelException
Description copied from interface: KeyStore
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.

Overrides:
set in class RIMKeyStore
Since:
JDE 4.0.0

Following copied from 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.

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



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.