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

java.lang.Object
  extended by net.rim.device.api.crypto.encoder.PublicKeyEncoder

public abstract class PublicKeyEncoder
extends Object

Allows the developer to encode public keys using a variety of supported encoding algorithms. Once again, the details of creating and using the appropriate algorithm are managed by PublicKeyEncoder 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.

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

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.

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
Category: Signed protected PublicKeyEncoder()
          Creates a new PublicKeyEncoder object.
 
Method Summary
Category: Signed static EncodedKey encode(PublicKey key)
          Encodes a given key using the default X509 encoding scheme.
Category: Signed static EncodedKey encode(PublicKey key, String encodingAlgorithm)
          Encodes a given key using the specified encoding scheme.
Category: Signed static EncodedKey encode(PublicKey key, String encodingAlgorithm, long flags)
          Encodes a given key using the specified encoding scheme.
Category: Signed protected abstract  EncodedKey encodeKey(PublicKey key, long flags)
          Encodes the passed in key in the proper format.
Category: Signed protected static PublicKeyEncoder getEncoder(String encodingAlgorithm, String keyAlgorithm)
          Returns the class associated with the encoding algorithm and the key algorithm.
Category: Signed protected abstract  String getEncodingAlgorithm()
          Returns the name of the encoding used, such as "X509".
Category: Signed protected abstract  String[] getKeyAlgorithms()
          Returns the name of the keys that can be encoded, such as ("EC", "DH").
Category: Signed static boolean register(PublicKeyEncoder encoder)
          Registers the given encoder class with the API.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

PublicKeyEncoder

protected PublicKeyEncoder()
Creates a new PublicKeyEncoder 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

encode

public static EncodedKey encode(PublicKey key)
                         throws NoSuchAlgorithmException,
                                InvalidKeyEncodingException,
                                CryptoTokenException,
                                CryptoUnsupportedOperationException
Encodes a given key using the default X509 encoding scheme.

The crypto system parameters are encoded.

Parameters:
key - The public key to encode.
Returns:
An EncodedKey object containing the encoded key.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
InvalidKeyEncodingException - Thrown if the key is improperly formatted.
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

encode

public static EncodedKey encode(PublicKey key,
                                String encodingAlgorithm)
                         throws NoSuchAlgorithmException,
                                InvalidKeyEncodingException,
                                CryptoTokenException,
                                CryptoUnsupportedOperationException
Encodes a given key using the specified encoding scheme.

Parameters:
key - The public key to encode.
encodingAlgorithm - A string representing the encoding Algorithm to use, eg "X509".
Returns:
An EncodedKey object containing the encoded key.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
InvalidKeyEncodingException - Thrown if the key is improperly formatted.
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

encode

public static EncodedKey encode(PublicKey key,
                                String encodingAlgorithm,
                                long flags)
                         throws NoSuchAlgorithmException,
                                InvalidKeyEncodingException,
                                CryptoTokenException,
                                CryptoUnsupportedOperationException
Encodes a given key using the specified encoding scheme.

Parameters:
key - The public key to encode.
encodingAlgorithm - A string representing the encoding Algorithm to use, eg "X509".
flags - Flags passed to the encoder. See PublicKeyEncoderFlags.
Returns:
An EncodedKey object containing the encoded key.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
InvalidKeyEncodingException - Thrown if the key is improperly formatted.
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

encodeKey

protected abstract EncodedKey encodeKey(PublicKey key,
                                        long flags)
                                 throws NoSuchAlgorithmException,
                                        InvalidKeyEncodingException,
                                        CryptoTokenException,
                                        CryptoUnsupportedOperationException
Encodes the passed in key in the proper format.

Parameters:
key - A public key to encode.
flags - Flags passed to the encoder. See PublicKeyEncoderFlags.
Returns:
The encoding of the key.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
InvalidKeyEncodingException - Thrown if the key is improperly formatted.
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(PublicKeyEncoder encoder)
                        throws NoSuchAlgorithmException
Registers the given encoder class with the API.

Parameters:
encoder - The public key encoder to register.
Returns:
Returns true if the class was added by the user, false if it was already in the hash table.
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

getEncoder

protected static PublicKeyEncoder getEncoder(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 encoder.
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 the encoding used, 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 keys that can be encoded, such as ("EC", "DH").

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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal