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

java.lang.Object
  extended by net.rim.device.api.crypto.encoder.SignatureDecoder
Direct Known Subclasses:
CMS_SignatureDecoder, WTLS_SignatureDecoder, X509_SignatureDecoder

public abstract class SignatureDecoder
extends Object

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

Encoding Signatures

Encoding a signature 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.

Decoding Signatures

Decoding a signature simply 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 = ...;
      DecodedSignature decoded = SignatureDecoder.decode( encodedSignatureData, "X509" );
      SignatureVerifier verifier = decoded.getVerifier( publicKey );
 
Only the encoded signature and encoding algorithm into decode. The user gets back a SignatureDecoder 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"
WTLS encoding use the encoding string "WTLS"
CMS encoding use the encoding string "CMS"

The X509 encoding is defined in RFC 2459. The WTLS encoding is found in WAP-199-WTLS from Feb 2000. Finally, 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. Please see the tutorial on Adding Encoders.

See Also:
DecodedSignature, SignatureEncoder, EncodedSignature
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 SignatureDecoder()
          Creates a new SignatureDecoder object.
 
Method Summary
Category: Signed static DecodedSignature decode(byte[] encodedSignature, int offset, String encodingAlgorithm)
          Decodes the specified encoded signature.
Category: Signed static DecodedSignature decode(byte[] encodedSignature, int offset, String encodingAlgorithm, String signatureAlgorithm)
          Decodes the specified encoded signature.
Category: Signed static DecodedSignature decode(byte[] encodedSignature, String encodingAlgorithm)
          Decodes the specified encoded signature.
Category: Signed static DecodedSignature decode(InputStream encodedSignature, String encodingAlgorithm)
          Decodes the specified encoded signature.
Category: Signed static DecodedSignature decode(InputStream encodedSignature, String encodingAlgorithm, String signatureAlgorithm)
          Decodes the specified encoded signature.
Category: Signed protected abstract  DecodedSignature decodeSignature(InputStream encodedSignature, String signatureAlgorithm, String digestAlgorithm)
          Decodes the input stream.
Category: Signed protected static SignatureDecoder getDecoder(String encodingAlgorithm, String signatureAlgorithm)
          Returns the class associated with the encoding algorithm and the key algorithm.
Category: Signed protected abstract  String getEncodingAlgorithm()
          Returns the encoding algorithm used, such as "X509".
Category: Signed protected abstract  String[] getSignatureAlgorithms()
          Returns the signature algorithm used, such as ("DSA", "RSA_PKCS1_SHA1").
Category: Signed static boolean register(SignatureDecoder decoder, SignatureDecoder baseDecoder)
          Registers the class name, given the decoder and decoder scheme.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

SignatureDecoder

protected SignatureDecoder()
Creates a new SignatureDecoder 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 DecodedSignature decode(InputStream encodedSignature,
                                      String encodingAlgorithm)
                               throws NoSuchAlgorithmException,
                                      InvalidSignatureEncodingException
Decodes the specified encoded signature.

Parameters:
encodedSignature - An input stream containing the encoded signature to verify.
encodingAlgorithm - A String representing the encoding scheme used.
Returns:
A DecodedSignature object from which a signature verifier can be obtained.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
InvalidSignatureEncodingException - Thrown if the signature is incorrectly formatted.
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 DecodedSignature decode(byte[] encodedSignature,
                                      String encodingAlgorithm)
                               throws NoSuchAlgorithmException,
                                      InvalidSignatureEncodingException
Decodes the specified encoded signature.

Parameters:
encodedSignature - A byte array containing the encoded signature to verify.
encodingAlgorithm - A string representing the encoding scheme used.
Returns:
A DecodedSignature object from which a signature verifier can be obtained.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
InvalidSignatureEncodingException - Thrown if the signature is incorrectly formatted.
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 DecodedSignature decode(byte[] encodedSignature,
                                      int offset,
                                      String encodingAlgorithm)
                               throws NoSuchAlgorithmException,
                                      InvalidSignatureEncodingException
Decodes the specified encoded signature.

Parameters:
encodedSignature - A byte array containing the encoded signature to verify.
offset - The integer position within the byte array to begin reading from.
encodingAlgorithm - A string representing the encoding scheme used.
Returns:
A DecodedSignature object from which a signature verifier can be obtained.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
InvalidSignatureEncodingException - Thrown if the signature is incorrectly formatted.
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 DecodedSignature decode(InputStream encodedSignature,
                                      String encodingAlgorithm,
                                      String signatureAlgorithm)
                               throws NoSuchAlgorithmException,
                                      InvalidSignatureEncodingException
Decodes the specified encoded signature.

Parameters:
encodedSignature - An input stream containing the encoded signature to verify.
encodingAlgorithm - A string representing the encoding scheme used.
signatureAlgorithm - The signature algorithm used.
Returns:
A DecodedSignature object from which a signature verifier can be obtained.
Throws:
NoSuchAlgorithmException - Thrown if the encoding algorithm cannot be found.
InvalidSignatureEncodingException - Thrown if the signature is incorrectly formatted.
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 DecodedSignature decode(byte[] encodedSignature,
                                      int offset,
                                      String encodingAlgorithm,
                                      String signatureAlgorithm)
                               throws NoSuchAlgorithmException,
                                      InvalidSignatureEncodingException
Decodes the specified encoded signature.

Parameters:
encodedSignature - A byte array containing the encoded signature to verify.
offset - The integer position within the byte array to begin reading from.
encodingAlgorithm - A String representing the encoding scheme used.
signatureAlgorithm - A String representing the signature algorithm used.
Returns:
A DecodedSignature object from which a signature verifier can be obtained.
Throws:
NoSuchAlgorithmException - Thrown if the specified encoding algorithm cannot be found.
InvalidSignatureEncodingException - Thrown if the signature is incorrectly formatted.
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

decodeSignature

protected abstract DecodedSignature decodeSignature(InputStream encodedSignature,
                                                    String signatureAlgorithm,
                                                    String digestAlgorithm)
                                             throws NoSuchAlgorithmException,
                                                    InvalidSignatureEncodingException
Decodes the input stream.

Parameters:
encodedSignature - An input stream containing the encoding.
signatureAlgorithm - The signature algorithm used.
Returns:
A DecodedSignature object from which a signature verifier can be obtained.
Throws:
NoSuchAlgorithmException - Thrown if the specified encoding algorithm cannot be found.
InvalidSignatureEncodingException - Thrown if the signature is incorrectly formatted.
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(SignatureDecoder decoder,
                               SignatureDecoder baseDecoder)
Registers the class name, given the decoder and decoder scheme.

Parameters:
decoder - The algorithm decoder, such as X509_RSA_SignatureDecoder.
baseDecoder - The encoding algorithm wrapper, such as X509_SignatureDecoder.
Returns:
Returns true if we added the class, false if it was already 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 SignatureDecoder getDecoder(String encodingAlgorithm,
                                             String signatureAlgorithm)
                                      throws NoSuchAlgorithmException
Returns the class associated with the encoding algorithm and the key algorithm.

Parameters:
encodingAlgorithm - The encoding algorithm such as "X509".
signatureAlgorithm - The key type that was encoded, such as "RSA_PKCS1/SHA1".
Returns:
An instance of a signature decoder.
Throws:
NoSuchAlgorithmException - Thrown if the specified 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 encoding algorithm 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

getSignatureAlgorithms

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

Returns:
An array of Strings representing the names of all signature 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-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.