iaik.security.dsa

Class RawDSA

java.lang.Object

java.security.SignatureSpi

iaik.security.dsa.RawDSA

public final class RawDSA
extends java.security.SignatureSpi

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 specifically 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 implementation 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 31

See Also:

DSA, SHA, Signature

Field Summary

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

Constructors

Constructor and Description
RawDSA() The default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
java.math.BigInteger[]	dsaSignRS() Sign method that returns the signature as two BigIntegers.
boolean	dsaVerifyRS(java.math.BigInteger[] rs) Verify method that accepts the signature as an array of two BigIntegers.
boolean	dsaVerifyRS(java.math.BigInteger r, java.math.BigInteger s) Verify method that accepts the signature as two BigIntegers.
protected java.lang.Object	engineGetParameter(java.lang.String param) Returns a previously set KSEED parameter as a byte array, or -- if KSEED has not been set, or the supplied param String is not "KSEED" -- the DSA parameters p, q, g as DSAParameters object.
protected java.security.AlgorithmParameters	engineGetParameters() Returns the DSA parameters (p, q, g) as DSAParameters object.
protected void	engineInitSign(java.security.PrivateKey privateKey) SPI: Initializes this DSA Signature object with the given DSA private key for going to sign some data.
protected void	engineInitSign(java.security.PrivateKey privateKey, java.security.SecureRandom random) SPI: Initializes this Signature object with the given DSA private key and the given SecureRandom generator for going to sign some data.
protected void	engineInitVerify(java.security.PublicKey publicKey) SPI: Initializes this RawDSA signature object with the given DSA public key for performing a signature verification.
protected void	engineSetParameter(java.security.spec.AlgorithmParameterSpec params) Initializes this DSA signature engine with the given parameter set.
protected void	engineSetParameter(java.lang.String param, java.lang.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.SignatureSpi

clone, engineSign, engineUpdate, engineVerify

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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(java.security.PublicKey publicKey)
                         throws java.security.InvalidKeyException

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

Specified by:

engineInitVerify in class java.security.SignatureSpi

Parameters:

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

Throws:

java.security.InvalidKeyException - if a key encoding error occurs

engineInitSign

protected void engineInitSign(java.security.PrivateKey privateKey)
                       throws java.security.InvalidKeyException

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

Specified by:

engineInitSign in class java.security.SignatureSpi

Parameters:

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

Throws:

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

engineInitSign

protected void engineInitSign(java.security.PrivateKey privateKey,
                  java.security.SecureRandom random)
                       throws java.security.InvalidKeyException

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

Note that this method is not available for JDK versions prior JDK 1.2. If a SecureRandom never has been supplied by the application, the signature engine will use a default SecureRandom, if required.

Overrides:

engineInitSign in class java.security.SignatureSpi

Parameters:

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

random - the random number generator

Throws:

java.security.InvalidKeyException - if a key decoding error occurs

engineUpdate

protected void engineUpdate(byte b)
                     throws java.security.SignatureException

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

Specified by:

engineUpdate in class java.security.SignatureSpi

Parameters:

b - the hash byte to be used for updating.

Throws:

java.security.SignatureException - if the engine has not been properly initialized

engineUpdate

protected void engineUpdate(byte[] b,
                int off,
                int len)
                     throws java.security.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.

Specified by:

engineUpdate in class java.security.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:

java.security.SignatureException - if the engine has not been properly initialized.

engineSign

protected byte[] engineSign()
                     throws java.security.SignatureException

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

Specified by:

engineSign in class java.security.SignatureSpi

Returns:

the signature bytes of the signing operation's result.

Throws:

java.security.SignatureException - if the engine has not been properly initialized.

dsaSignRS

public java.math.BigInteger[] dsaSignRS()
                                 throws java.security.SignatureException

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

Throws:

java.security.SignatureException

engineVerify

protected boolean engineVerify(byte[] sigBytes)
                        throws java.security.SignatureException

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

Specified by:

engineVerify in class java.security.SignatureSpi

Parameters:

sigBytes - the signature bytes to be verified.

Returns:

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

Throws:

java.security.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(java.math.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(java.math.BigInteger r,
                  java.math.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(java.lang.String param,
                      java.lang.Object value)
                           throws java.security.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.

If "KSEED" is not supplied as param string, a SecureRandom object (for kseed generation) or a DSAParameterSpec object (for setting the p, g, g parameters) maybe supplied as param value.

Specified by:

engineSetParameter in class java.security.SignatureSpi

Parameters:

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

value - the value of the parameter to be set, either the kseed as byte array or BigInteger, or a SecureRandom object (for kseed generation) or a DSAParameterSpec object (for setting the p, g, g parameters)

Throws:

java.security.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(java.security.spec.AlgorithmParameterSpec params)
                           throws java.security.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. 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 java.security.SignatureSpi

Parameters:

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

Throws:

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

engineGetParameter

protected java.lang.Object engineGetParameter(java.lang.String param)
                                       throws java.security.InvalidParameterException

Returns a previously set KSEED parameter as a byte array, or -- if KSEED has not been set, or the supplied param String is not "KSEED" -- the DSA parameters p, q, g as DSAParameters object.

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

Specified by:

engineGetParameter in class java.security.SignatureSpi

Parameters:

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

Returns:

the kseed value previously set with setParameter, or -- if KSEED has not been set, or the supplied param String is not "KSEED" -- the DSA parameters p, q, g as DSAParameters object

Throws:

java.security.InvalidParameterException - if an error occurs when creating the parameters

engineGetParameters

protected java.security.AlgorithmParameters engineGetParameters()

Returns the DSA parameters (p, q, g) as DSAParameters object.

Overrides:

engineGetParameters in class java.security.SignatureSpi

Returns:

the DSA parameters (p, q, g) as DSAParameters