SHOW Signed SHOW CryptoExtensionAPI
 

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

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

public abstract class SignatureEncoder
extends Object

Defines encode signatures produced by the SignatureSigner classes. The details of creating and using the appropriate encoding algorithm are left to SignatureEncoder and are completely transparent to the developer.

Encoding Signatures

Encoding a signature simply involves calling the public static encode() method with a SignatureSigner object and a string that contains the requested encoding algorithm. For example, to encode an ECDSASignatureSigner using X509 encoding, code similar to the following would be used:

                    
      PrivateKey privateKey = ...; 
      SignatureSigner signer = new ECDSASignatureSigner( privateKey );
      String message = "Buy 10000 shares of Jabroni Jeans";
      signer.update( message );
      EncodedSignature encodedSignature = SignatureEncoder.encode( signer, "X509" );
 
where signer is a valid ECDSASignatureSigner object that has been created with the appropriate parameters.

Note that the encode call will call the appropriate SignatureSigner.sign call.

Decoding Signatures

Decoding a signature involves calling the public static decode() method in this class with an EncodedSignature object and the public key to use for verification. Decoding an ECDSA signature using the X509 encoding algorithm can be accomplished by using code similar to the following:

      PublicKey publicKey = ...;
      byte[] encodedSignatureData = ...;
      SignatureDecoder decoder = SignatureDecoder.decode( encodedSignatureData, "X509" );
      SignatureVerifier verifier = decoder.getVerifier( publicKey );
 
Only the encoded signature and encoding algorithm into decode. The user gets back a SignatureDecoder object which they can then pass a public key into to create a signature verifier. The user can also call the initialize function of the decoder in order to change the digest used by the signature verifier.

Supported Encoding Algorithms

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

X509 encoding use the encoding string "X509"
CMS encoding use the encoding string "CMS"

The X509 encoding is defined in RFC 2459. The CMS encoding is defined in RFC 2630.

For algorithms not found in this list, a developer can implement additional signature encoding algorithms that can be integrated into the Crypto API.

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
See Also:
EncodedSignature, SignatureDecoder, DecodedSignature

Constructor Summary
 Category: CryptoExtensionAPI Category: Signed protected SignatureEncoder()
          Creates a new SignatureEncoder object.
 
Method Summary
 Category: Signed static EncodedSignature encode(SignatureSigner signer, String encodingAlgorithm)
          Takes in the provided signature signer and returns an encoded signature using the specified encoding algorithm.
 Category: CryptoExtensionAPI Category: Signed protected abstract  EncodedSignature encodeSignature(SignatureSigner signer)
          An abstract function that will do the work of returning an encoded signature from a signature signer.
 Category: CryptoExtensionAPI Category: Signed protected static SignatureEncoder getEncoder(String encodingAlgorithm, String signatureAlgorithm)
          Returns the class associated with the encoding algorithm and the signature algorithm.
 Category: CryptoExtensionAPI Category: Signed protected abstract  String getEncodingAlgorithm()
          Returns the encoding algorithm used, such as "X509".
 Category: CryptoExtensionAPI Category: Signed protected abstract  String[] getSignatureAlgorithms()
          Returns the signature algorithm used, such as ("DSA", "RSA_PKCS1_SHA1").
 Category: CryptoExtensionAPI Category: Signed static boolean register(SignatureEncoder encoder)
          Registers the class given the name.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SignatureEncoder

protected SignatureEncoder()
Creates a new SignatureEncoder 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 EncodedSignature encode(SignatureSigner signer,
                                      String encodingAlgorithm)
                               throws NoSuchAlgorithmException,
                                      CryptoTokenException,
                                      CryptoUnsupportedOperationException
Takes in the provided signature signer and returns an encoded signature using the specified encoding algorithm.

Note that the encode call will call the appropriate SignatureSigner.sign call.

Parameters:
signer - The signature signer to use for signing.
encodingAlgorithm - A String representing the encoding algorithm to use such as "X509".
Returns:
An encoded signature.
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.

encodeSignature

protected abstract EncodedSignature encodeSignature(SignatureSigner signer)
                                             throws NoSuchAlgorithmException,
                                                    CryptoTokenException,
                                                    CryptoUnsupportedOperationException
An abstract function that will do the work of returning an encoded signature from a signature signer.

Note that the encode call will call the appropriate SignatureSigner.sign call.

Parameters:
signer - A signature signer.
Returns:
An encoded signature.
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 SignatureEncoder getEncoder(String encodingAlgorithm,
                                             String signatureAlgorithm)
                                      throws NoSuchAlgorithmException
Returns the class associated with the encoding algorithm and the signature algorithm.

Parameters:
encodingAlgorithm - The encoding algorithm such as "X509".
signatureAlgorithm - The signature type that was encoded, such as "EC".
Returns:
An instance of a signature encoder.
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.

getEncodingAlgorithm

protected abstract String getEncodingAlgorithm()
Returns the encoding algorithm used, such as "X509".

Returns:
A String representing the name of the encoding 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.

getSignatureAlgorithms

protected abstract String[] getSignatureAlgorithms()
Returns the signature algorithm used, such as ("DSA", "RSA_PKCS1_SHA1").

Returns:
An array of Strings representing the name of the signature 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(SignatureEncoder encoder)
                        throws NoSuchAlgorithmException
Registers the class given the name.

Parameters:
encoder - The signature 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.
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.