SHOW Signed SHOW CryptoExtensionAPI
 

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

java.lang.Object
  |
  +--net.rim.device.api.crypto.encoder.PrivateKeyEncoder

public abstract class PrivateKeyEncoder
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:
JDE 3.6.0

Constructor Summary
 Category: CryptoExtensionAPI Category: Signed protected PrivateKeyEncoder()
          Creates a new PrivateKeyEncoder object.
 
Method Summary
 Category: Signed static EncodedKey encode(PrivateKey key)
          Encodes a given key using the default PKCS8 encoding scheme.
 Category: Signed static EncodedKey encode(PrivateKey key, String encodingAlgorithm)
          Encodes a given key using the specified encoding scheme.
 Category: CryptoExtensionAPI Category: Signed protected abstract  EncodedKey encodeKey(PrivateKey key)
          Encodes the passed in key in the proper format.
 Category: CryptoExtensionAPI Category: Signed protected static PrivateKeyEncoder getEncoder(String encodingAlgorithm, String keyAlgorithm)
          Returns the class associated with the encoding algorithm and the key algorithm.
 Category: CryptoExtensionAPI Category: Signed protected abstract  String getEncodingAlgorithm()
          Returns the name of the encoding used, such as "PKCS8".
 Category: CryptoExtensionAPI Category: Signed protected abstract  String[] getKeyAlgorithms()
          Returns the name of the key that was encoded, such as ("EC","DSA").
 Category: CryptoExtensionAPI Category: Signed static boolean register(PrivateKeyEncoder 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

PrivateKeyEncoder

protected PrivateKeyEncoder()
Creates a new PrivateKeyEncoder object.

This is the default constructor.

Since:
JDE 3.6.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.
Method Detail

encode

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

The crypto system parameters are encoded.

Parameters:
key - The private key to encode.
Returns:
An EncodedKey object containing the encoded key.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
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.
Since:
JDE 3.6.0
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.

encode

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

Parameters:
key - The private key to encode.
encodingAlgorithm - A string representing the encoding Algorithm to use, eg "PKCS8".
Returns:
An EncodedKey object containing the encoded key.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
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.
Since:
JDE 3.6.0
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.

encodeKey

protected abstract EncodedKey encodeKey(PrivateKey key)
                                 throws NoSuchAlgorithmException,
                                        CryptoTokenException,
                                        CryptoUnsupportedOperationException
Encodes the passed in key in the proper format.

Parameters:
key - The private key to encode.
Returns:
The EncodedKey object.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
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.
Since:
JDE 3.6.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.

getEncoder

protected static PrivateKeyEncoder 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 "PKCS8".
keyAlgorithm - The key type that was encoded, such as "EC".
Returns:
An instance of a private key encoder.
Throws:
NoSuchAlgorithmException - Thrown if the specified encoding algorithm cannot be found.
Since:
JDE 3.6.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.

getEncodingAlgorithm

protected abstract String getEncodingAlgorithm()
Returns the name of the encoding used, such as "PKCS8".

Returns:
A String representing the name of the algorithm.
Since:
JDE 3.6.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.

getKeyAlgorithms

protected abstract String[] getKeyAlgorithms()
Returns the name of the key that was encoded, such as ("EC","DSA").

Returns:
An array of Strings representing the key algorithms.
Since:
JDE 3.6.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.

register

public static boolean register(PrivateKeyEncoder encoder)
                        throws NoSuchAlgorithmException
Registers the given encoder class with the API.

Parameters:
encoder - The private key encoder to register.
Returns:
Returns true if the class was added by the user, false if it already existed in the hash table.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
Since:
JDE 3.6.0
Category:
CryptoExtensionAPI: This element is part of the Crypto Extension API. These APIs are intended for parties interested in extending the security provider frameworks, such as integrating a new security medium.
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.



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.