iaik.me.security
Class Signature

java.lang.Object
  |
  +--iaik.me.security.Signature

Direct Known Subclasses:

DSASignature, RSASignature

public abstract class Signature

extends Object

The Signature class provides digital signature algorithms that can be used to generate and verify digital signatures. These algorithms can be, among others, the NIST standard DSA, using DSA and SHA-1. The DSA algorithm using the SHA-1 message digest algorithm can be specified as SHA1withDSA (digital signatures require a digest algorithm and an encryption algorithm, so you always specify "DigestAlgorithmwithencryptionAlgorithm"). In the case of RSA, there are multiple choices for the message digest algorithm, so the signing algorithm could be specified as, for example, MD2withRSA, MD5withRSA, or SHA1withRSA. The algorithm name must be specified, as there is no default. Security and performance strongly depend on the choosen algorithm.

There are three steps to do if you want to use the Signature object for signing data or verifying a signature:

1. Initialize the signature instance either with a

- a public key, if you want to verify a signature (see initVerify( PublicKey ))
or
- a private key (and optionally a Secure Random Number Generator), if you want to create a signature (see initSign(PrivateKey, SecureRandom)).

2. Update the instance either with

- the data that shall be signed
or
- the data that shall be verified

3. Create or verifiy a signature

The usage of this class is similar to the one of JCA`s java.security.Signature class (except that you cannot specify a provider).
If you want to create a signature, you have to do the following:

    PrivateKey rsa_priv = .... // If you want to know how you can get predefined keys from the keystore, have a look at the Keystore JavaDoc.  
    PublicKey dsa_pub = ....
    
    Signature rsa = Signature.getInstance("SHA1withRSA");
 
    // 1. initialize the signature instance with a private key      
    rsa.initSign(rsa_priv, null);  // if the random number generator is null, the random numbers are generated automatically.
    // 2. update the signature with the data to be signed
    rsa.update(data);
    // 3. create the signature
    byte[] signature = rsa.sign();
 

If you want to verify a signature, you have to do the following:

    Signature rsa = Signature.getInstance("SHA1withRSA");
 	  
    // 1. initialize the signature	
    rsa.initVerify(rsa_pub);
    // 2. update the date
    rsa.update(data);
    // 3. verifiy the signature
    boolean signatureOK = rsa.verify(signature); 
 

Supported signature algorithms are:

• MD2withRSA
• MD5withRSA
• SHA1withRSA
• SHA224withRSA
• SHA256withRSA
• SHA1withDSA
*
• DSA
• RawDSA

Since:

3.0

Version:

3.02

Field Summary

protected MessageDigest	md
protected SecureRandom	random

Constructor Summary

protected

Signature()

Method Summary

String	getAlgorithm() Returns the used signature algorithm of the instance.
static Signature	getInstance(String algorithm) Creates a Signature instance with the specified algorithm.
abstract void	initSign(PrivateKey privateKey, SecureRandom random) Initializes the signature instance for signing with a private key and a random number generator.
abstract void	initVerify(PublicKey publicKey) Initializes the signature instance for verifiying a signature.
static void	register(String name, String clazz) This method is used to register new (or self implemented) signature algorithms. For example: Signature.register("SHA1withDSA", "iaik.me.security.dsa.DSASignature"); Once registered, the algorithm can be used via the getInstance(String) method.
abstract byte[]	sign() Creates a signature with the given data and private key.
void	update(byte[] input) Updates the signature instance with the data that shall be signed or the data whose signature shall be verified.
void	update(byte[] input, int offset, int len) Updates the signature instance with the data that shall be signed or the data whose signature shall be verified.
abstract boolean	verify(byte[] signature) This method verifies a given signature.

Methods inherited from class java.lang.Object

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

Field Detail

md

protected MessageDigest md

random

protected SecureRandom random

Constructor Detail

Signature

protected Signature()

Method Detail

getAlgorithm

public final String getAlgorithm()

Returns the used signature algorithm of the instance. See Signature for the available signature algorithms.

Returns:

a String with the algorithm name

initSign

public abstract void initSign(PrivateKey privateKey,
                              SecureRandom random)
                       throws CryptoException

Initializes the signature instance for signing with a private key and a random number generator.

Parameters:

privateKey - the signer's private key

random - optional if you want to use your own random number generator (if not, set this value to null).

Throws:

CryptoException -

initVerify

public abstract void initVerify(PublicKey publicKey)
                         throws CryptoException

Initializes the signature instance for verifiying a signature.

Parameters:

publicKey - the signer's public key

Throws:

CryptoException -

Since:

3.0

update

public final void update(byte[] input)
                  throws CryptoException

Updates the signature instance with the data that shall be signed or the data whose signature shall be verified.

Parameters:

input - the data to besigned

Throws:

CryptoException -

Since:

3.0

update

public void update(byte[] input,
                   int offset,
                   int len)
            throws CryptoException

Updates the signature instance with the data that shall be signed or the data whose signature shall be verified. Use this method in case you don't want the whole byte array as input.

Parameters:

input - the input data

offset - starting index in the byte array

len - number of bytes to use as input beginnig from the starting index

Throws:

CryptoException -

Since:

3.0

verify

public abstract boolean verify(byte[] signature)
                        throws CryptoException

This method verifies a given signature. After initializing the signature instance do this:

 byte[] signature = rsa.sign();
 

to get the signature value.

Parameters:

signature - the signature to be verified

Returns:

true if the signature could be successfully verified.

Throws:

CryptoException -

Since:

3.0

sign

public abstract byte[] sign()
                     throws CryptoException

Creates a signature with the given data and private key.

Returns:

the signature as byte array

Throws:

CryptoException -

Since:

3.0

getInstance

public static Signature getInstance(String algorithm)
                             throws CryptoException

Creates a Signature instance with the specified algorithm. The instance can be created as follows:

 Signature rsaSignature = Signature.getInstance("SHA1withRSA");
 

Parameters:

algorithm - see "Supported signature algorithms" for the supported algorithms.

Returns:

the signature instance

Throws:

CryptoException - if the specified algorithm is not available

Since:

3.0

register

public static void register(String name,
                            String clazz)

This method is used to register new (or self implemented) signature algorithms.
For example:

 Signature.register("SHA1withDSA", "iaik.me.security.dsa.DSASignature");    
 

Once registered, the algorithm can be used via the getInstance(String) method.

Parameters:

name - the name of the algorithm

clazz - the name of the class which implements the algorithm (with full package name)

Since:

3.0