SHOW Signed

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

java.lang.Object
  |
  +--net.rim.device.api.crypto.keystore.KeyStorePasswordManager

public final class KeyStorePasswordManager

extends Object

Provides all of the keystore password functionality for the keystore.

This includes functionality of remembering how many attempts at the password, forcing the user to enter the password, remembering the password for a timeout period and other important functions. You should only use the key store password class when trying to determine if someone knows the key store password.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Since:

JDE 3.6.0

Method Summary

	void	challenge() Displays the password dialog and prompts the user to enter a correct password.
	void	challenge(String label) Displays a custom password dialog and prompts the user to enter a correct password.
	void	changePassword() This function is called to change the KeyStore password on the device.
	boolean	checkTicket(KeyStorePasswordTicket ticket) Checks to make sure that the ticket is valid and that it is of the appropriate type.
	boolean	clean() This method is called when the user wants to clean out the keystore information requiring the entry of the password the next time they try to access anything in the keystore.
	byte[]	decrypt(int securityLevel, long salt, byte[] input, int offset, int length, String label, KeyStorePasswordTicket ticket) Returns the byte array that is decrypted with the password.
	byte[]	decrypt(int securityLevel, long salt, byte[] input, String label, KeyStorePasswordTicket ticket) Returns the byte array that is decrypted with the password.
	byte[]	decryptReEncrypt(int securityLevel, long salt, byte[] ciphertext) During a change password operation this helper function allows an easy way to change the encryption of an object from the old password to the new password.
	byte[]	encrypt(int securityLevel, long salt, byte[] input, int offset, int length, String label, KeyStorePasswordTicket ticket) Returns the byte array that is encrypted with the password.
	byte[]	encrypt(int securityLevel, long salt, byte[] input, String label, KeyStorePasswordTicket ticket) Returns the byte array that is encrypted with the password.
	static KeyStorePasswordManager	getInstance()
	KeyStorePasswordTicket	getTicket() Returns a ticket if the operation to retrieve one was successful.
	KeyStorePasswordTicket	getTicket(String prompt) Returns a ticket if the operation to retrieve one was successful.
	byte[]	setPassword() Sets the password by prompting the user for it and then asking for its confirmation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static KeyStorePasswordManager getInstance()

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

challenge

public void challenge()
               throws KeyStoreCancelException

Displays the password dialog and prompts the user to enter a correct password.

Throws:

KeyStoreCancelException - Thrown if the user fails to enter a valid password or cancels out of the password dialog.

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

challenge

public void challenge(String label)
               throws KeyStoreCancelException

Displays a custom password dialog and prompts the user to enter a correct password.

Parameters:

label - The text label for the password dialog.

Throws:

KeyStoreCancelException - Thrown if the user fails to enter a valid password or cancels out of the password dialog.

Since:

JDE 3.7.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

encrypt

public byte[] encrypt(int securityLevel,
                      long salt,
                      byte[] input,
                      String label,
                      KeyStorePasswordTicket ticket)
               throws KeyStoreCancelException

Returns the byte array that is encrypted with the password.

Parameters:

securityLevel - The security level.

salt - The salt that is used to encrypt the password. This should be random.

input - The input byte array that is to be encrypted.

label - a label that will be shown to the user when they are prompted to encrypt their 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 password from the user automatically (calls getTicket).

Returns:

A byte array containing the encrypted input

Throws:

KeyStoreCancelException - Thrown when the user cancels out of the simple password dialog since they appear to not want to enter their password.

Since:

JDE 3.7.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

encrypt

public byte[] encrypt(int securityLevel,
                      long salt,
                      byte[] input,
                      int offset,
                      int length,
                      String label,
                      KeyStorePasswordTicket ticket)
               throws KeyStoreCancelException

Returns the byte array that is encrypted with the password.

Parameters:

securityLevel - The security level.

salt - The salt that is used to encrypt the password. This should be random.

input - The input byte array that is to be encrypted.

offset - The offset into the byte array to be encrypted.

length - The number of bytes to be encrypted.

label - a label that will be shown to the user during the prompt for their passphrase if necessary.

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 password from the user automatically (essentially calls getTicket for you).

Returns:

A byte array containing the encrypted input.

Throws:

KeyStoreCancelException - Thrown when the user cancels out of the simple password dialog since they appear to not want to enter their password.

Since:

JDE 3.7.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

decrypt

public byte[] decrypt(int securityLevel,
                      long salt,
                      byte[] input,
                      String label,
                      KeyStorePasswordTicket ticket)
               throws KeyStoreCancelException,
                      KeyStoreDecodeException

Returns the byte array that is decrypted with the password.

Parameters:

securityLevel - The security level.

salt - The salt that is used to encrypt the password. This should be random.

input - The input byte array that is to be encrypted.

label - a string that will be shown to the user on a prompt for passphrase if necessary.

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 password from the user automatically (essentially calls getTicket for you).

Returns:

A byte array containing the decerypted data.

Throws:

KeyStoreCancelException - Thrown when the user cancels out of the simple password dialog since they appear to not want to enter their password.

KeyStoreDecodeException - if the keystore was unable to decrypt the ciphertext given that the security level was incorrect or the password was somehow incorrect.

Since:

JDE 3.7.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

decrypt

public byte[] decrypt(int securityLevel,
                      long salt,
                      byte[] input,
                      int offset,
                      int length,
                      String label,
                      KeyStorePasswordTicket ticket)
               throws KeyStoreCancelException,
                      KeyStoreDecodeException

Returns the byte array that is decrypted with the password.

Parameters:

securityLevel - The security level.

salt - The salt that is used to decrypt the password. This should be random.

input - The input byte array that is to be decrypted.

offset - The offset into the byte array to be decrypted.

length - The number of bytes to be decrypted.

label - A string that will be shown to the user when prompting for a passphrase if necessary.

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 password from the user automatically (essentially calls getTicket for you).

Returns:

A byte array containing the decrypted input

Throws:

KeyStoreCancelException - Thrown when the user cancels out of the simple password dialog since they appear to not want to enter their password.

KeyStoreDecodeException - if the keystore was unable to decrypt the ciphertext given that the security level was incorrect or the password was somehow incorrect.

Since:

JDE 3.7.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

changePassword

public void changePassword()
                    throws KeyStoreCancelException

This function is called to change the KeyStore password on the device.

This function prompts for the old password and the new password. It ensures that the old password is correct and then proceeds. If the old password is incorrect it continues to prompt until the maximum number of attempts is reached.

Throws:

KeyStoreCancelException - Thrown when the user cancels out of the simple password dialog since they appear to not want to enter their password.

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

decryptReEncrypt

public byte[] decryptReEncrypt(int securityLevel,
                               long salt,
                               byte[] ciphertext)
                        throws KeyStoreDecodeException

During a change password operation this helper function allows an easy way to change the encryption of an object from the old password to the new password.

It is important to note that this will take in a byte array that is encrypted with the old password and return a new byte array that is encrypted with the new password. Everything is seamless to the user.

Parameters:

securityLevel - An integer representing the security level.

salt - The salt used to encrypt the data. Must be random. Note that the salt is going to be the same for the old ciphertext and the new ciphertext.

ciphertext - A byte array containing the ciphertext.

Returns:

A byte array containing the decrypted data.

Throws:

InvalidKeyEncodingException - Thrown if the key is improperly encoded.

KeyStoreDecodeException - if the keystore was unable to decrypt the ciphertext given that the security level was incorrect or the password was somehow incorrect.

Since:

JDE 3.7.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getTicket

public KeyStorePasswordTicket getTicket()
                                 throws KeyStoreCancelException

Returns a ticket if the operation to retrieve one was successful.

This will typically prompt for a password and will return a key store ticket if successful. If not this method can return null.

Returns:

The key store ticket that can be used to access the KeyStoreManager.

Throws:

KeyStoreCancelException - Thrown when the user cancels out of the simple password dialog since they appear to not want to enter their password.

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getTicket

public KeyStorePasswordTicket getTicket(String prompt)
                                 throws KeyStoreCancelException

Returns a ticket if the operation to retrieve one was successful.

This will typically prompt for a password and will return a key store ticket if successful. If not this method can return null.

Parameters:

prompt - a string that is appended to the dialog for clarifying what exactly this ticket will be used for.

Returns:

The key store ticket that can be used to access the KeyStoreManager.

Throws:

KeyStoreCancelException - Thrown when the user cancels out of the simple password dialog since they appear to not want to enter their password.

Since:

JDE 3.7.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

checkTicket

public boolean checkTicket(KeyStorePasswordTicket ticket)

Checks to make sure that the ticket is valid and that it is of the appropriate type.

Parameters:

ticket - The specified ticket.

Returns:

Returns true if these conditions are satisfied.

Since:

JDE 3.7.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setPassword

public byte[] setPassword()
                   throws KeyStoreCancelException

Sets the password by prompting the user for it and then asking for its confirmation.

Returns:

A byte[] containing the password if this method did not have the password set already. If the password is already set, then it returns null.

Throws:

KeyStoreCancelException - Thrown when the user cancels out of the simple password dialog since they appear to not want to enter their password.

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

clean

public boolean clean()

This method is called when the user wants to clean out the keystore information requiring the entry of the password the next time they try to access anything in the keystore.

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.