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

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

Direct Known Subclasses:

MSCAPI_PublicKeyDecoder, WTLS_PublicKeyDecoder, X509_PublicKeyDecoder

public abstract class PublicKeyDecoder
extends Object

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

Encoding a Public Key

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

      RSAPublicKey key = new RSAPublicKey( ... );
      EncodedKey encodedKey = PublicKeyEncoder.encode( key, "X509" );
 

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

Decoding a Public Key

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

      byte[] encodedKeyData = ...;
      PublicKey decodedKey = PublicKeyDecoder.decode( encodedKeyData, "X509" );
 

This code assumes that encodedKey contains a properly encoded public key. Currently, RIM provides the following public key encoding algorithms, which can be accessed with the specifed string :

Microsoft Crypto API	Use the encoding string "MSCAPI".
X509 encoding	Use the encoding string "X509".
WTLS encoding	Use the encoding string "WTLS".

Supported Encoding Algorithms

The MSCAPI encoding can be found in MSDN. The X509 encoding is defined in RFC 2459. Finally, the WTLS encoding is found in WAP-199-WTLS from Feb 2000.

A complete list of the key encoding algorithms supported by the RIM crypto API can be found here.

If a developer wishes to implement a key encoding algorithm not found in this list, the PublicKeyEncoder class can be extended.

This information can be found here.

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

Method Summary
	static PublicKey	decode(byte[] encodedKey, String encodingAlgorithm) Takes in the given encoded key and returns the decoded public key.
	static PublicKey	decode(byte[] encodedKey, String encodingAlgorithm, CryptoSystem cryptoSystem, String keyAlgorithm) Decodes an encoded public key.
	static PublicKey	decode(InputStream encodedKey, String encodingAlgorithm) Takes in the given encoded key and returns the decoded public key.
	static PublicKey	decode(InputStream encodedKey, String encodingAlgorithm, CryptoSystem cryptoSystem, String keyAlgorithm) Decodes an encoded public key.
	protected abstract PublicKey	decodeKey(InputStream encodedKey, CryptoSystem cryptoSystem, String keyAlgorithm) Decodes the passed in key.
	protected static PublicKeyDecoder	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 name of the key algorithm that was encoded.
	static boolean	register(PublicKeyDecoder decoder, PublicKeyDecoder baseDecoder) Registers a new PublicKeyDecoder with the framework.

Methods inherited from class java.lang.Object

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

Constructor Detail

PublicKeyDecoder

protected PublicKeyDecoder()

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

Decodes an encoded public key.

Parameters:

encodedKey - An InputStream containing the key encoding.

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

cryptoSystem - The crypto system to retrieve parameter information from, if necessary.

keyAlgorithm - The type of key.

Returns:

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

Decodes an encoded public key.

Parameters:

encodedKey - A byte array containing the key encoding.

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

cryptoSystem - The crypto system to retrieve parameter information, if necessary.

keyAlgorithm - The type of key.

Returns:

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

Decodes the passed in key.

Parameters:

encodedKey - The public key to decode, passed in as an input stream.

cryptoSystem - A cryptoSystem containing the parameters to use in making this key.

keyAlgorithm - The type of key.

Returns:

The decoded public 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 PublicKey decode(InputStream encodedKey,
                               String encodingAlgorithm)
                        throws NoSuchAlgorithmException,
                               InvalidKeyEncodingException,
                               InvalidKeyException,
                               InvalidCryptoSystemException,
                               UnsupportedCryptoSystemException,
                               CryptoTokenException,
                               CryptoUnsupportedOperationException

Takes in the given encoded key and returns the decoded public key.

Parameters:

encodedKey - An input stream containing the encoding and other relevant information.

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

Returns:

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

Takes in the given encoded key and returns the decoded public key.

Parameters:

encodedKey - A byte array containing the encoding and other relevant information.

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

Returns:

The decoded public 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

register

public static boolean register(PublicKeyDecoder decoder,
                               PublicKeyDecoder baseDecoder)

Registers a new PublicKeyDecoder with the framework.

Parameters:

decoder - The algorithm decoder, such as X509_RSA_PublicKeyDecoder.

baseDecoder - The encoding algorithm wrapper, such as X509_PublicKeyDecoder.

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 PublicKeyDecoder 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 "X509".

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

Returns:

An instance of a public key decoder.

Throws:

NoSuchAlgorithmException - Thrown if the 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 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 name of the key algorithm that was encoded.

Returns:

An array of Strings that represent the names of 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