net.rim.device.api.crypto.encoder
Class SymmetricKeyDecoder

java.lang.Object
  net.rim.device.api.crypto.encoder.SymmetricKeyDecoder

Direct Known Subclasses:

PKCS8_SymmetricKeyDecoder

public abstract class SymmetricKeyDecoder
extends Object

Allows the developer to decode symmetric keys using a variety of supported encoding algorithms. Once again, the details of creating and using the appropriate algorithm are managed by SymmetricKeyDecoder and are completely transparent to the developer.

Encoding a Symmetric Key

Encoding a public key simply involves calling the public static encode() method with the desired symmetric key. As the following code illustrates, encoding a is straightforward:

      DESKey key = new DESKey( ... );
      EncodedKey encodedKey = SymmetricKeyEncoder.encode( key, "scheme" );
 

Of course, the DES key must be properly created and initialized.

Decoding a Symmetric Key

Decoding a symmetric key is similar to encoding one. Simply call the public static decode() method with the encoded key:

      byte[] encodedKeyData = ...;
      SymmetricKey decodedKey = SymmetricKeyDecoder.decode( encodedKey, "scheme" );
 

This code assumes that encodedKey contains a properly encoded symmetric key.

Supported Encoding Algorithms

A complete list of the key encoding algorithms supported by the RIM crypto API can be found here. Currently, RIM provides the following symmetric key encoding algorithms, which can be accessed with the specifed string :

A RIM variant of PKCS8

use the encoding string "PKCS8"

For algorithms not found in this list, a developer can implement additional symmetric key decoding algorithms that can be integrated into the Crypto API. Please see the tutorial on Adding Encoders.

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
	protected	SymmetricKeyDecoder() Creates a new SymmetricKeyDecoder object.

Method Summary
	static SymmetricKey	decode(byte[] encodedKey, String encodingAlgorithm) Decodes an encoded symmetric key.
	static SymmetricKey	decode(byte[] encodedKey, String encodingAlgorithm, String keyAlgorithm) Decodes an encoded symmetric key.
	static SymmetricKey	decode(InputStream encodedKey, String encodingAlgorithm) Decodes an encoded symmetric key.
	static SymmetricKey	decode(InputStream encodedKey, String encodingAlgorithm, String keyAlgorithm) Decodes an encoded symmetric key.
	protected abstract SymmetricKey	decodeKey(InputStream encodedKey, String keyAlgorithm) Decodes the passed in key.
	protected static SymmetricKeyDecoder	getDecoder(String encodingAlgorithm, String keyAlgorithm) Returns the class associated with the encoding algorithm and the key algorithm.
	protected abstract String	getEncodingAlgorithm() Returns the name of this encoding algorithm, such as "X509".
	protected abstract String[]	getKeyAlgorithms() Returns the names of the key algorithm that can be decoded.
	static boolean	register(SymmetricKeyDecoder decoder, SymmetricKeyDecoder baseDecoder) Registers a new SymmetricKeyDecoder object with the framework.

Methods inherited from class java.lang.Object

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

Constructor Detail

SymmetricKeyDecoder

protected SymmetricKeyDecoder()

Creates a new SymmetricKeyDecoder object.

This is the default constructor.

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

decode

public static SymmetricKey decode(InputStream encodedKey,
                                  String encodingAlgorithm)
                           throws NoSuchAlgorithmException,
                                  InvalidKeyEncodingException,
                                  InvalidKeyException,
                                  CryptoTokenException,
                                  CryptoUnsupportedOperationException

Decodes an encoded symmetric key.

Parameters:

encodedKey - An input stream containing the key encoding.

encodingAlgorithm - The encoding algorithm to use to decode, such as "X509".

Returns:

The decoded symmetric key.

Throws:

NoSuchAlgorithmException - Thrown if the specified encoding algorithm cannot be found.

InvalidKeyEncodingException - Thrown if the key is incorrectly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

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 3.6.0

decode

public static SymmetricKey decode(byte[] encodedKey,
                                  String encodingAlgorithm)
                           throws NoSuchAlgorithmException,
                                  InvalidKeyEncodingException,
                                  InvalidKeyException,
                                  CryptoTokenException,
                                  CryptoUnsupportedOperationException

Decodes an encoded symmetric key.

Parameters:

encodedKey - A byte array containing the key encoding.

encodingAlgorithm - The encoding algorithm to use to decode, such as "X509".

Returns:

The decoded symmetric key.

Throws:

NoSuchAlgorithmException - Thrown if the specified encoding algorithm cannot be found.

InvalidKeyEncodingException - Thrown if the key is incorrectly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

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 3.6.0

decode

public static SymmetricKey decode(InputStream encodedKey,
                                  String encodingAlgorithm,
                                  String keyAlgorithm)
                           throws NoSuchAlgorithmException,
                                  InvalidKeyEncodingException,
                                  InvalidKeyException,
                                  CryptoTokenException,
                                  CryptoUnsupportedOperationException

Decodes an encoded symmetric key.

Parameters:

encodedKey - An input stream containing the public key to decode.

encodingAlgorithm - The encoding algorithm to use to decode, such as "X509".

keyAlgorithm - The type of key.

Returns:

The decoded symmetric key.

Throws:

NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.

InvalidKeyEncodingException - Thrown if the key is imporperly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

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 3.6.0

decode

public static SymmetricKey decode(byte[] encodedKey,
                                  String encodingAlgorithm,
                                  String keyAlgorithm)
                           throws NoSuchAlgorithmException,
                                  InvalidKeyEncodingException,
                                  InvalidKeyException,
                                  CryptoTokenException,
                                  CryptoUnsupportedOperationException

Decodes an encoded symmetric key.

Parameters:

encodedKey - A byte array containing the public key to decode.

encodingAlgorithm - The encoding algorithm to use to decode, such as "X509".

keyAlgorithm - The type of key.

Returns:

The decoded symmetric key.

Throws:

NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.

InvalidKeyEncodingException - Thrown if the key is imporperly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

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 3.6.0

decodeKey

protected abstract SymmetricKey decodeKey(InputStream encodedKey,
                                          String keyAlgorithm)
                                   throws NoSuchAlgorithmException,
                                          InvalidKeyEncodingException,
                                          InvalidKeyException,
                                          CryptoTokenException,
                                          CryptoUnsupportedOperationException,
                                          IOException

Decodes the passed in key.

Parameters:

encodedKey - An input stream containing the public key to decode.

keyAlgorithm - The type of key.

Returns:

The decoded symmetric key

Throws:

NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.

InvalidKeyEncodingException - Thrown if the key is imporperly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

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.

IOException - Thrown if an I/O error occurs.

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

register

public static boolean register(SymmetricKeyDecoder decoder,
                               SymmetricKeyDecoder baseDecoder)

Registers a new SymmetricKeyDecoder object with the framework.

Parameters:

decoder - The algorithm decoder.

baseDecoder - The encoding algorithm wrapper.

Returns:

Returns true if the class was added by the user, false if it already existed in the hash table.

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

getDecoder

protected static SymmetricKeyDecoder getDecoder(String encodingAlgorithm,
                                                String keyAlgorithm)
                                         throws NoSuchAlgorithmException

Returns the class associated with the encoding algorithm and the key algorithm.

Parameters:

encodingAlgorithm - The encoding algorithm such as "PKCS8".

keyAlgorithm - The key type that was encoded, such as "DES".

Returns:

An instance of a symmetric key decoder.

Throws:

NoSuchAlgorithmException - Thrown if the specified encoding algorithm cannot be found.

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

getEncodingAlgorithm

protected abstract String getEncodingAlgorithm()

Returns the name of this encoding algorithm, such as "X509".

Returns:

A String that represents the name of the encoding 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

getKeyAlgorithms

protected abstract String[] getKeyAlgorithms()

Returns the names of the key algorithm that can be decoded.

Returns:

An array of Strings representing the key algorithms.

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