iaik.security.dsa
Class RawDSA

java.lang.Object
  |
  +--java.security.SignatureSpi
        |
        +--java.security.Signature
              |
              +--iaik.security.dsa.RawDSA

public final class RawDSA

extends Signature

This class implements the "Raw" DSA signature algorithm. That is, it expects its input to be already hashed with SHA-1.

Use it like any other signature algorithm, but supply the hashed data to the update() methods instead of the original data to be signed. You can call all of the update methods in any combination, but when you call sign() or verify() exactly 20 bytes must have been passed during the updates. This is necessary because DSA was spefically designed for the 160 bit hashes of SHA-1.

If you are going to sign some yet not hashed data (respectively verify the corresponding signature), you can use the DSA implemetation which automatically hashes the supplied data according the SHA algorithm before processing it with the RawDSA algorithm.

The Digital Signature Algorithm (DSA) only can be used for digital signing (respectively signature verifying). It cannot be used for data encryption.

The DSA algorithm uses a certain number of parameters:

• a prime number p, which length is a multiple of 64 bits lying between 512 and 1024 bits
• a 160-bit prime factor (q) of p-1
• a number h less than p-1 fulfilling (h(p-1)/q)(mod p) > 1
• a number g calculated from g = (h(p-1)/q)(mod p)
• a number x less than q
• a number y calculated from y = (gx)(mod p)

p, q, g and y form the public key; x represents the private key. The procedures of signing some message with one entity´s private key, and verifying a signature using the signer´s public key may be read up in "Applied Cryptography", Bruce Schneier, ISBN 0-471-59756-2). For creating a signature an entity performs some computations on a randomly chosen number k, which has to be shorter than q. These computations are done using the entities private key and result in two BigInteger values r and s representing the signature. For verifying a given signature, the signing entity´s public key has to be used for performing computations on the signature consisting of the two BigIntegers r and s. Beside the common way of signing messages and verifying signatures (see below) by using the corresponding sign and verify methods, this class is equipped with a set of alternative signing and verifying methods allowing to handle DSA signatures immediately by their inherent BigInteger values r and s.

For signing some message or verifying a signature using RawDSA, generally an application will have to perform three steps:

• First an instance of the desired signature algorithm has to be created by using a proper getInstance method, e.g.:

   Signature dsa = Signature.getInstance("RawDSA");
   

• Second, the Signature object just created has to be properly initialized for signing a message respectively verifying a signature using a DSA private respectively DSA public key, e.g.:
  • Initialize for Signing: dsa.initSign(dsaPrivateKey);
  • Initialize for Verifying: dsa.initVerify(dsaPublicKey);

• Finally, if the Signature object has been initialized for signing, the already hashed (!) data to be signed is supplied to it and subsequently the signature is created by calling the sign method returning the signature as DER encoded byte array. Otherwise, if the Signature object has been initialized for verifying, first the already hashed data to be verified is supplied to the Signature object, and subsequently the signature is verified by calling the verify method, supplied with the DER encoded byte array holding the corresponding signature:
  • Supply alreay hashed data to be signed, and subsequently sign it:

        dsa.update(hashedData);
        byte[] signature = dsa.sign();
        

  • Supply already hashed data to be verified, and verify the signature:

        dsa.update(hashedData);
        System.out.println("Signature " + (dsa.verify(signature) ? "correct!" : "not correct!"));
        

Version:

File Revision 24

See Also:

DSA, SHA, Signature

Fields inherited from class java.security.Signature

SIGN, state, UNINITIALIZED, VERIFY

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

RawDSA()
The default constructor.

Method Summary

BigInteger[]	dsaSignRS() Sign method that returns the signature as two BigIntegers.
boolean	dsaVerifyRS(BigInteger[] rs) Verify method that accepts the signature as an array of two BigIntegers.
boolean	dsaVerifyRS(BigInteger r, BigInteger s) Verify method that accepts the signature as two BigIntegers.
protected Object	engineGetParameter(String param) Returns a previously set KSEED parameter as a byte array.
protected void	engineInitSign(PrivateKey privateKey) SPI: Initializes this DSA Signature object with the given DSA private key for going to sign some data.
protected void	engineInitVerify(PublicKey publicKey) SPI: Initializes this RawDSA signature object with the given DSA public key for performing a signature verification.
protected void	engineSetParameter(AlgorithmParameterSpec params) Initializes this DSA signature engine with the given parameter set.
protected void	engineSetParameter(String param, Object value) Set the KSEED parameter for DSA signing.
protected byte[]	engineSign() SPI: Returns the signature bytes of all the data updated so far.
protected void	engineUpdate(byte b) SPI: Updates the data to be signed or verified with the specified byte.
protected void	engineUpdate(byte[] b, int off, int len) SPI: Updates the data to be signed or verified with the specified number of hashed bytes, beginning at the specified offset within the given byte array.
protected boolean	engineVerify(byte[] sigBytes) SPI: Verifies the passed-in signature.

Methods inherited from class java.security.Signature

clone, getAlgorithm, getInstance, getInstance, getParameter, getProvider, initSign, initSign, initVerify, initVerify, setParameter, setParameter, sign, sign, toString, update, update, update, verify

Methods inherited from class java.security.SignatureSpi

engineInitSign, engineSign

Methods inherited from class java.lang.Object

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

Constructor Detail

RawDSA

public RawDSA()

The default constructor. Creates a new RawDSA signature object.

Applications use Signature.getInstance("RawDSA"); for creating a RawDSA Signature object.

See Also:

Signature.getInstance(java.lang.String)

Method Detail

engineInitVerify

protected void engineInitVerify(PublicKey publicKey)
                         throws InvalidKeyException

SPI: Initializes this RawDSA signature object with the given DSA public key for performing a signature verification.

Overrides:

engineInitVerify in class SignatureSpi

Parameters:

publicKey - the DSA public key belonging to the DSA private key that has been used for signing

Throws:

InvalidKeyException - if a key encoding error occurs

engineInitSign

protected void engineInitSign(PrivateKey privateKey)
                       throws InvalidKeyException

SPI: Initializes this DSA Signature object with the given DSA private key for going to sign some data.

Overrides:

engineInitSign in class SignatureSpi

Parameters:

privateKey - the DSA private key to be used for signing.

Throws:

InvalidKeyException - if the key is improperly encoded, parameters are missing, and so on.

engineUpdate

protected void engineUpdate(byte b)
                     throws SignatureException

SPI: Updates the data to be signed or verified with the specified byte.

Overrides:

engineUpdate in class SignatureSpi

Parameters:

b - the hash byte to be used for updating.

Throws:

SignatureException - if the engine has not been properly initialized

engineUpdate

protected void engineUpdate(byte[] b,
                            int off,
                            int len)
                     throws SignatureException

SPI: Updates the data to be signed or verified with the specified number of hashed bytes, beginning at the specified offset within the given byte array.

Overrides:

engineUpdate in class SignatureSpi

Parameters:

b - the byte array holding the already hashed data to be used for this update operation.

off - the offset, indicating the start position within the given byte array.

len - the number of bytes to be obtained from the given byte array, starting at the given position.

Throws:

SignatureException - if the engine has not been properly initialized.

engineSign

protected byte[] engineSign()
                     throws SignatureException

SPI: Returns the signature bytes of all the data updated so far. The signature returned is X.509 (DER)-encoded.

Overrides:

engineSign in class SignatureSpi

Returns:

the signature bytes of the signing operation's result.

Throws:

SignatureException - if the engine has not been properly initialized.

dsaSignRS

public BigInteger[] dsaSignRS()

Sign method that returns the signature as two BigIntegers.

This method works exactly like engineSign(), but it returns the signature as the two BigIntegers r and s instead of their ASN.1 encoding.

Returns:

an array containing two BigInterges (r at index 0, and s at index 1) representing the signature

engineVerify

protected boolean engineVerify(byte[] sigBytes)
                        throws SignatureException

SPI: Verifies the passed-in signature. The signature bytes are expected to be X.509 (DER)-encoded.

Overrides:

engineVerify in class SignatureSpi

Parameters:

sigBytes - the signature bytes to be verified.

Returns:

true if the signature is o.k., false if not.

Throws:

SignatureException - if the engine is not initialized properly, or the passed-in signature is improperly encoded or of the wrong type, etc.

dsaVerifyRS

public boolean dsaVerifyRS(BigInteger[] rs)

Verify method that accepts the signature as an array of two BigIntegers.

Index 0 of the array must hold r, index 1 s.

Parameters:

rs - the BigInteger array holding r at index 0 and s at index 1

Returns:

true if the signature is o.k., false if not.

dsaVerifyRS

public boolean dsaVerifyRS(BigInteger r,
                           BigInteger s)

Verify method that accepts the signature as two BigIntegers.

Parameters:

r - the first BigInteger

s - the second BigInteger

Returns:

true if the signature is o.k., false if not.

engineSetParameter

protected void engineSetParameter(String param,
                                  Object value)
                           throws InvalidParameterException

Set the KSEED parameter for DSA signing.

The generation of a DSA signature involves a random, secret number k that is usually newly generated for each signature. This method allows you to set this number to a specified value. Use "KSEED" as the name and a byte array or a BigInteger as parameter. Use a null value to unset a previously set seed.

CAUTION: Use of this feature is recommended for testing purposes only.

Overrides:

engineSetParameter in class SignatureSpi

Parameters:

param - the name of the parameter ("KSEED")

value - the value of the parameter to be set

Throws:

InvalidParameterException - if the given parameter name is not "KSEED" or the given parameter value is not specified as byte array or BigInteger

See Also:

Signature.setParameter(java.lang.String, java.lang.Object)

engineSetParameter

protected void engineSetParameter(AlgorithmParameterSpec params)
                           throws InvalidAlgorithmParameterException

Initializes this DSA signature engine with the given parameter set. The supplied parameter set must be an instance of java.security.spec.DSAParameterSpec. This method only can be used with JDK1.2.x. For JDK1.1.x you may use method engineSetParameter(String param, Object value) with "DSAParameterSpec" as name indicating that the supplied value is an instance of DSAParameterSpec}. This method may be useful for initializing the signature verification in situations where there are no parameters are included in the subjectPublicKeyInfo field of a X.509 certificate and therefore have to be supplied by other means.

Overrides:

engineSetParameter in class SignatureSpi

Parameters:

params - the parameters as instance of java.security.spec.DSAParameterSpec

Throws:

InvalidAlgorithmParameterException - if the given parameters are not supplied as java.security.spec.DSAParameterSpec

engineGetParameter

protected Object engineGetParameter(String param)
                             throws InvalidParameterException

Returns a previously set KSEED parameter as a byte array.

For security reasons this method will only return a KSEED that was previously set using engineSetParameter(), not an internally generated one while signing.

Overrides:

engineGetParameter in class SignatureSpi

Parameters:

param - the name of the parameter which value is to be obtained ("KSEED")

Returns:

the kseed value previously set with setParameter

Throws:

InvalidParameterException - if the given parameter name is not "KSEED"

See Also:

Signature.getParameter(java.lang.String), Signature.setParameter(java.lang.String, java.lang.Object)