iaik.security.dsa
Class DSA

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

public final class DSA

extends Signature

This class implements the DSS (DSA with SHA-1) signature algorithm as specified in FIPS PUB 186. The Digital Signature Algorithm (DSA) only can be used for digital signing (respectively signature verifying). It cannot be used for data encryption.

NIST´s Digital Signature Standard (DSS) specifies the DSA algorithm as public-key algorithm for being used for digital signing applications. For first calculating a hash value of any data to be signed, the Secure Hash Algorithm is proposed to be used along with the DSA algorithm.

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 are made public, y forms the public key, and 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).

This class only adds the functionality of the SHA hash algorithm to the pure DSA algorithm, which is implemented by the RawDSA sub-class. An application wishing to hash the message with the SHA function before signing it, shall use this class:

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

An application that already has hashed the data to be signed, may use the raw DSA implementation:

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

Generally an application intending to sign some message respectively to verify a signature, has to perform three steps:

• The first step already has been described: create an instance of the desired signature algorithm by using a proper getInstance method, e.g.:

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

• 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 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 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 the data to be signed, and subsequently sign it:

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

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

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

Version:

File Revision 18

See Also:

RawDSA, SHA, Signature

Fields inherited from class java.security.Signature

SIGN, state, UNINITIALIZED, VERIFY

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

DSA()
The default constructor.

Method Summary

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 DSA 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) Sets 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 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

DSA

public DSA()

The default constructor. Creates a new DSA signature object by instantiating RawDSA and SHA.

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

See Also:

RawDSA, SHA, Signature.getInstance(java.lang.String)

Method Detail

engineInitVerify

protected void engineInitVerify(PublicKey publicKey)
                         throws InvalidKeyException

SPI: Initializes this DSA Signature object with the given DSA public key for performing a signature verification. This method only initializes the underlying RawDSA.

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. This method only initializes the underlying RawDSA.

Overrides:

engineInitSign in class SignatureSpi

Parameters:

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

Throws:

InvalidKeyException - if a key encoding error occurs

engineUpdate

protected void engineUpdate(byte b)
                     throws SignatureException

SPI: Updates the data to be signed or verified with the specified byte. This method actually updates the data to be hashed using the SHA algorithm.

Overrides:

engineUpdate in class SignatureSpi

Parameters:

b - the 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 bytes, beginning at the specified offset within the given byte array. This method actually updates the data to be hashed using the SHA algorithm.

Overrides:

engineUpdate in class SignatureSpi

Parameters:

b - the byte array holding the 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.

This method updates the underlying RawDSA with the hashed data and signs it using the RawDSA engineSign implementation.

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.

See Also:

RawDSA.engineSign()

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.

This method updates the underlying RawDSA with the hashed data and verifies the given signature using the RawDSA engineVerify implemetation.

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.

See Also:

RawDSA.engineVerify(byte[])

engineSetParameter

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

Sets 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.

This method only delegates the given parameter to the underlying RawDSA.

You alternatively may supply a java.security.spec.DSAParameterSpec parameter identified by name "DSAParameterSpec". This 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:

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

value - the value of the parameter to be set

Throws:

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

See Also:

RawDSA.engineSetParameter(java.lang.String, java.lang.Object), 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 setParameter(), not an internally generated one while signing. This method only asks the underlying RawDSA for the requested parameter value.

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), RawDSA.engineGetParameter(java.lang.String)