net.rim.device.api.crypto
Class TripleDESCryptoToken

java.lang.Object
  extended by net.rim.device.api.crypto.TripleDESCryptoToken
All Implemented Interfaces:
CryptoToken, SymmetricCryptoToken, Persistable, Persistable

public abstract class TripleDESCryptoToken
extends Object
implements SymmetricCryptoToken, Persistable

Represents a Triple DES crypto token.

The TripleDES algorithm proposed by NIST utilizes the standard DES algorithm in an alternating encryption then decryption operation. That is, EDE (Encryption/Decryption/Encryption) performing three DES operations and hence its name. This cipher is also commonly referred to as the DESede cipher.

Our implementation provides two types of TripleDES. Namely, two key and three key TripleDES. That is, two key TripleDES uses two different keys -- one for the encryption operations and one for the decryption operation. Three key TripleDES uses a different key for each operation.

The key length is 128 bits or 192 bits depending on whether you are using two key or three key TripleDES. Note that the effective key length is actually 112 bits or 168 bits after removing the parity bits from the DES operations. The block size is 64 bits.

If possible, three key TripleDES should be used instead of two key TripleDES due to the larger keysize and specific attacks against two key TripleDES.

Please refer to FIPS 46-3 for more information.

Details on implementing for smart cards. Note: This class must be extended in order to override the default implementation.

Note: It is considered good practice to implement the equals and hashCode methods when extending this class. Otherwise, odd behaviour can occur.

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 3.6.0

Constructor Summary
Category: Signed protected TripleDESCryptoToken()
          Creates a new TripleDESCryptoToken object.
 
Method Summary
Category: Signed  CryptoTokenSymmetricKeyData createKey()
          Creates a new key.
Category: Signed  void decrypt(CryptoTokenCipherContext context, byte[] ciphertext, int ciphertextOffset, byte[] plaintext, int plaintextOffset)
          Decrypts data given an array of plaintext and a context.
Category: Signed  void decryptCBC(CryptoTokenCipherContext context, byte[] ciphertext, int ciphertextOffset, byte[] plaintext, int plaintextOffset, int numBlocks, byte[] iv)
          Decrypts an array of ciphertext using the crypto token applying CBC mode to the blocks.
Category: Signed  void deleteKey(CryptoTokenSymmetricKeyData data)
          Delete the specified key on the crypto token.
Category: Signed  void encrypt(CryptoTokenCipherContext context, byte[] plaintext, int plaintextOffset, byte[] ciphertext, int ciphertextOffset)
          Encrypts data given an array of plaintext and a context.
Category: Signed  void encryptCBC(CryptoTokenCipherContext context, byte[] plaintext, int plaintextOffset, byte[] ciphertext, int ciphertextOffset, int numBlocks, byte[] iv)
          Encrypts an array of plaintext using the crypto token applying CBC mode to the blocks.
Category: Signed  byte[] extractKeyData(CryptoTokenSymmetricKeyData data)
          Extracts the key data from the crypto token and returns it in a byte array.
Category: Signed  String getAlgorithm()
          Returns the algorithm supported by this token, ie "TripleDES".
Category: Signed  CryptoTokenCipherContext initializeDecrypt(CryptoTokenSymmetricKeyData data)
          Initializes the crypto token for decryption.
Category: Signed  CryptoTokenCipherContext initializeEncrypt(CryptoTokenSymmetricKeyData data)
          Initializes the token for encryption.
Category: Signed  CryptoTokenSymmetricKeyData injectKey(byte[] key, int offset)
          Inserts the specified key onto the crypto token.
Category: Signed  boolean providesUserAuthentication()
          Returns true if the token provides its own user authentication checks, eg a smartcard will prompt for a password before allowing access to the keys.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

TripleDESCryptoToken

protected TripleDESCryptoToken()
Creates a new TripleDESCryptoToken object.

This constructor is not used.

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 3.6.0


Method Detail

getAlgorithm

public final String getAlgorithm()
Returns the algorithm supported by this token, ie "TripleDES".

Specified by:
getAlgorithm in interface CryptoToken
Returns:
A String that represents the name of the algorithm.
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 3.6.0

providesUserAuthentication

public boolean providesUserAuthentication()
Returns true if the token provides its own user authentication checks, eg a smartcard will prompt for a password before allowing access to the keys. This default implementation returns false.

Specified by:
providesUserAuthentication in interface CryptoToken
Returns:
true if the user will be authenticated by the token itself.
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 3.6.0

initializeEncrypt

public CryptoTokenCipherContext initializeEncrypt(CryptoTokenSymmetricKeyData data)
                                           throws CryptoTokenException,
                                                  CryptoUnsupportedOperationException
Initializes the token for encryption.

Parameters:
data - The key data contained on the crypto token.
Returns:
A crypto token cipher context.
Throws:
CryptoTokenException - Thrown if an error occurs with a crypto token or the crypto token is invalid.
CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.
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 3.6.0

encrypt

public void encrypt(CryptoTokenCipherContext context,
                    byte[] plaintext,
                    int plaintextOffset,
                    byte[] ciphertext,
                    int ciphertextOffset)
             throws CryptoTokenException
Encrypts data given an array of plaintext and a context.

Parameters:
context - The cipher context.
plaintext - A byte array containing the plaintext.
plaintextOffset - The offset, or initial position, of the plaintext data within the array.
ciphertext - A byte array containing the ciphertext.
ciphertextOffset - The offset, or initial position, of the ciphertext within the array.
Throws:
CryptoTokenException - Thrown if an error occurs with a crypto token or the crypto token 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.
Since:
BlackBerry API 3.6.0

encryptCBC

public void encryptCBC(CryptoTokenCipherContext context,
                       byte[] plaintext,
                       int plaintextOffset,
                       byte[] ciphertext,
                       int ciphertextOffset,
                       int numBlocks,
                       byte[] iv)
                throws CryptoTokenException,
                       CryptoUnsupportedOperationException
Encrypts an array of plaintext using the crypto token applying CBC mode to the blocks.

Parameters:
context - The crypto token context.
plaintext - An array containing the plaintext to be encrypted.
plaintextOffset - The offset, or start position, of the plaintext data within the array.
ciphertext - An array to contain the ciphertext.
ciphertextOffset - The offset, or starting bit, of the new cipher text data within the array.
numBlocks - The number of blocks to encrypt.
iv - The initialization vector.
Throws:
CryptoTokenException - Thrown if an error occurs with the crypto token or the crypto token is invalid.
CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.
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 5.0.0

initializeDecrypt

public CryptoTokenCipherContext initializeDecrypt(CryptoTokenSymmetricKeyData data)
                                           throws CryptoTokenException,
                                                  CryptoUnsupportedOperationException
Initializes the crypto token for decryption.

Parameters:
data - The symmetric key data used to encrypt the plaintext.
Returns:
The crypto token cipher context.
Throws:
CryptoTokenException - Thrown if an error occurs with a crypto token or the crypto token is invalid.
CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.
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 3.6.0

decrypt

public void decrypt(CryptoTokenCipherContext context,
                    byte[] ciphertext,
                    int ciphertextOffset,
                    byte[] plaintext,
                    int plaintextOffset)
             throws CryptoTokenException
Decrypts data given an array of plaintext and a context.

Parameters:
context - The cipher context.
ciphertext - A byte array containing the ciphertext.
ciphertextOffset - The offset, or initial position, of the ciphertext within the array.
plaintext - A byte array to contain the plaintext.
plaintextOffset - The offset, or initial position, of the plaintext data within the array.
Throws:
CryptoTokenException - Thrown if an error occurs with a crypto token or the crypto token 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.
Since:
BlackBerry API 3.6.0

decryptCBC

public void decryptCBC(CryptoTokenCipherContext context,
                       byte[] ciphertext,
                       int ciphertextOffset,
                       byte[] plaintext,
                       int plaintextOffset,
                       int numBlocks,
                       byte[] iv)
                throws CryptoTokenException,
                       CryptoUnsupportedOperationException
Decrypts an array of ciphertext using the crypto token applying CBC mode to the blocks.

Parameters:
context - The crypto token context.
ciphertext - An array containing the ciphertext to decrypt.
ciphertextOffset - The offset, or starting bit, of the ciphertext data within the array.
plaintext - An array to contain the plaintext.
plaintextOffset - The offset, or start position, of the plaintext data within the array.
numBlocks - The number of blocks to decrypt.
iv - The initialization vector.
Throws:
CryptoTokenException - Thrown if an error occurs with the crypto token or the crypto token is invalid.
CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.
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 5.0.0

extractKeyData

public byte[] extractKeyData(CryptoTokenSymmetricKeyData data)
                      throws CryptoTokenException,
                             CryptoUnsupportedOperationException
Extracts the key data from the crypto token and returns it in a byte array.

Parameters:
data - The symmetric key data contained within the token.
Returns:
A byte array containing teh key data.
Throws:
CryptoTokenException - Thrown if an error occurs with a crypto token or the crypto token is invalid.
CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.
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 3.6.0

createKey

public CryptoTokenSymmetricKeyData createKey()
                                      throws CryptoTokenException,
                                             CryptoUnsupportedOperationException
Creates a new key.

Returns:
The symmetric key.
Throws:
CryptoTokenException - Thrown if an error occurs with a crypto token or the crypto token is invalid.
CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.
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 3.6.0

injectKey

public CryptoTokenSymmetricKeyData injectKey(byte[] key,
                                             int offset)
                                      throws CryptoTokenException,
                                             CryptoUnsupportedOperationException
Inserts the specified key onto the crypto token.

Parameters:
key - A byte array containing the key data to be injected.
offset - The offset, or start position, of the key data within the array.
Returns:
The symmetric key data.
Throws:
CryptoTokenException - Thrown if an error occurs with a crypto token or the crypto token is invalid.
CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.
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 3.6.0

deleteKey

public void deleteKey(CryptoTokenSymmetricKeyData data)
               throws CryptoTokenException,
                      CryptoUnsupportedOperationException
Delete the specified key on the crypto token.

Parameters:
data - The symmetric key data contained within the token.
Throws:
CryptoTokenException - Thrown if an error occurs with a crypto token or the crypto token is invalid.
CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.
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 3.6.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.