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

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

Direct Known Subclasses:

MSCAPI_PrivateKeyDecoder, PKCS8_PrivateKeyDecoder

public abstract class PrivateKeyDecoder
extends Object

Allows the developer to encode private keys using a variety of supported encoding algorithms. The details of creating and using the appropriate algorithm are managed by PrivateKeyEncoder and are completely transparent to the developer.

Encoding a Private Key

Encoding a private key involves calling the public static encode() method with the desired private key. As the following code illustrates, encoding an RSA private key using the X509 algorithm is straightforward:

      RSAPrivateKey key = new RSAPrivateKey( ... );
      EncodedKey encodedKey = PrivateKeyEncoder.encode( key, "PKCS8" );
 

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

Decoding a Private Key

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

      byte[] encodedKeyData = ...;
      PrivateKey decodedKey = PrivateKeyDecoder.decode( encodedKeyData, "PKCS8" );
 

This code assumes that encodedKeyData contains a properly encoded private key.

Supported Encoding Algorithms

Please see here for a list of the RIM supplied encoding algorithms. Currently, RIM provides the following private key encoding algorithms, which can be accessed with the specifed string :

Microsoft Crypto API	Use the encoding string "MSCAPI".
PKCS8 encoding	Use the encoding string "PKCS8".

The MSCAPI encoding can be found in MSDN. The PKCS8 encoding is found in the PKCS8 standard v1.2.

For algorithms not found in this list, a developer can implement additional private key encoding 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	PrivateKeyDecoder() Creates a new PrivateKeyDecoder object.

Method Summary
	static PrivateKey	decode(byte[] encodedKey, String encodingAlgorithm) Takes in an encoded key and returns the decoded private key.
	static PrivateKey	decode(byte[] encodedKey, String encodingAlgorithm, CryptoSystem cryptoSystem, String keyAlgorithm) Accepts an encoded key and returns the decoded private key.
	static PrivateKey	decode(InputStream encodedKey, String encodingAlgorithm) Takes in an encoded key and returns the decoded private key.
	static PrivateKey	decode(InputStream encodedKey, String encodingAlgorithm, CryptoSystem cryptoSystem, String keyAlgorithm) Accepts an encoded key and returns the decoded private key.
	protected abstract PrivateKey	decodeKey(InputStream encodedKey, CryptoSystem cryptoSystem, String keyAlgorithm) Decodes the specified key.
	protected static PrivateKeyDecoder	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 "PKCS8".
	protected abstract String[]	getKeyAlgorithms() Returns the names of the key algorithms that can be decoded.
	static boolean	register(PrivateKeyDecoder decoder, PrivateKeyDecoder baseDecoder) Registers a private key decoder class with the API.

Methods inherited from class java.lang.Object

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

Constructor Detail

PrivateKeyDecoder

protected PrivateKeyDecoder()

Creates a new PrivateKeyDecoder 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 PrivateKey decode(InputStream encodedKey,
                                String encodingAlgorithm,
                                CryptoSystem cryptoSystem,
                                String keyAlgorithm)
                         throws NoSuchAlgorithmException,
                                InvalidKeyEncodingException,
                                InvalidKeyException,
                                InvalidCryptoSystemException,
                                UnsupportedCryptoSystemException,
                                CryptoTokenException,
                                CryptoUnsupportedOperationException

Accepts an encoded key and returns the decoded private key.

Parameters:

encodedKey - An input stream containing the encoding of the key.

encodingAlgorithm - The encoding algorithm used for the encoded key.

cryptoSystem - The crypto system to base the decoded key upon (if no parameters were encoded with it).

keyAlgorithm - The type of key.

Returns:

The decoded private key.

Throws:

NoSuchAlgorithmException - Thrown if the specified algorithm is invalid.

InvalidKeyEncodingException - Thrown if the key is improperly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

InvalidCryptoSystemException - Thrown if the specified crypto system is invalid.

UnsupportedCryptoSystemException - Thrown if the specified crypto system is unsupported.

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 PrivateKey decode(byte[] encodedKey,
                                String encodingAlgorithm,
                                CryptoSystem cryptoSystem,
                                String keyAlgorithm)
                         throws NoSuchAlgorithmException,
                                InvalidKeyEncodingException,
                                InvalidKeyException,
                                InvalidCryptoSystemException,
                                UnsupportedCryptoSystemException,
                                CryptoTokenException,
                                CryptoUnsupportedOperationException

Accepts an encoded key and returns the decoded private key.

Parameters:

encodedKey - A byte array containing the encoding of the key.

encodingAlgorithm - The encoding algorithm used for the encoded key.

cryptoSystem - The crypto system to base the decoded key upon (if no parameters were encoded with it).

keyAlgorithm - The type of key.

Returns:

The decoded private key.

Throws:

NoSuchAlgorithmException - Thrown if the specified algorithm is invalid.

InvalidKeyEncodingException - Thrown if the key is improperly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

InvalidCryptoSystemException - Thrown if the specified crypto system is invalid.

UnsupportedCryptoSystemException - Thrown if the specified crypto system is unsupported.

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 PrivateKey decodeKey(InputStream encodedKey,
                                        CryptoSystem cryptoSystem,
                                        String keyAlgorithm)
                                 throws NoSuchAlgorithmException,
                                        InvalidKeyEncodingException,
                                        InvalidKeyException,
                                        InvalidCryptoSystemException,
                                        UnsupportedCryptoSystemException,
                                        CryptoTokenException,
                                        CryptoUnsupportedOperationException,
                                        IOException

Decodes the specified key.

This method must be implemented by subclasses.

Parameters:

encodedKey - An input stream containing the encoded key.

cryptoSystem - The crypto system to base the decoded key upon (if no parameters were encoded with it).

keyAlgorithm - The type of key.

Returns:

The decoded key.

Throws:

NoSuchAlgorithmException - Thrown if the specified algorithm is invalid.

InvalidKeyEncodingException - Thrown if the key is improperly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

InvalidCryptoSystemException - Thrown if the specified crypto system is invalid.

UnsupportedCryptoSystemException - Thrown if the specified crypto system is unsupported.

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

decode

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

Takes in an encoded key and returns the decoded private key.

Parameters:

encodedKey - An input stream containing the key encoding.

encodingAlgorithm - The encoding algorithm used for the encoded key.

Returns:

The decoded private key.

Throws:

NoSuchAlgorithmException - Thrown if the specified algorithm is invalid.

InvalidKeyEncodingException - Thrown if the key is improperly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

InvalidCryptoSystemException - Thrown if the specified crypto system is invalid.

UnsupportedCryptoSystemException - Thrown if the specified crypto system is unsupported.

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 PrivateKey decode(byte[] encodedKey,
                                String encodingAlgorithm)
                         throws NoSuchAlgorithmException,
                                InvalidKeyEncodingException,
                                InvalidKeyException,
                                InvalidCryptoSystemException,
                                UnsupportedCryptoSystemException,
                                CryptoTokenException,
                                CryptoUnsupportedOperationException

Takes in an encoded key and returns the decoded private key.

Parameters:

encodedKey - A byte array containing the key encoding.

encodingAlgorithm - The encoding algorithm used for the encoded key.

Returns:

The decoded private key.

Throws:

NoSuchAlgorithmException - Thrown if the specified key algorithm is invalid.

InvalidKeyEncodingException - Thrown if the key is improperly formatted.

InvalidKeyException - Thrown if the specified key is invalid.

InvalidCryptoSystemException - Thrown if the specified crypto system is invalid.

UnsupportedCryptoSystemException - Thrown if the specified crypto system is unsupported.

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

register

public static boolean register(PrivateKeyDecoder decoder,
                               PrivateKeyDecoder baseDecoder)

Registers a private key decoder class with the API.

Parameters:

decoder - The algorithm decoder, such as PKCS8_RSA_PrivateKeyDecoder.

baseDecoder - The encoding algorithm wrapper, such as PKCS8_PrivateKeyDecoder.

Returns:

Returns true if the class was added by the user, false if it already exists 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 PrivateKeyDecoder 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 "EC".

Returns:

An instance of a private key decoder.

Throws:

NoSuchAlgorithmException - Thrown if the encoding algorithm is invalid or 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 "PKCS8".

Returns:

A String representing 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 algorithms 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