iaik.security.dsa

Class DSA

java.lang.Object

java.security.SignatureSpi

iaik.security.dsa.DSA

Direct Known Subclasses:

SHA224withDSA, SHA256withDSA, SHA3_224withDSA, SHA3_256withDSA, SHA3_384withDSA, SHA3_512withDSA, SHA384withDSA, SHA512withDSA

public class DSA
extends java.security.SignatureSpi

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 (SHA-1) is proposed to be used along with the DSA algorithm. FIPS 186-3 (June 2009) adapted the Digital Signature Algorithm for use with the SHA-2 hash algorithm suite.

This class only adds the functionality of the SHA hash algorithm to the pure DSA algorithm, which is implemented by the RawDSA class. An application wishing to let the Signature engine hash the message before signing it, shall specify the hash algorithm name (SHA1, SHA224, SHA256) when creating the Signature engine, e.g.:

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

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("SHA1withDSA");
   

• 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 20

See Also:

RawDSA, SHA, Signature

Field Summary

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

Constructors

Constructor and Description
DSA() The default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected java.lang.Object	engineGetParameter(java.lang.String param) Returns a previously set KSEED parameter as a byte array.
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 DSA 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) 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.
static void	setCheckSigValueForDERCompliance(boolean checkForDER) Decides whether to check if the encoding of the DSA signature complies with the Distinguished Encoding Rules (DER).
static void	setDoVerifySignature(boolean doVerify) Decides whether to verify a DSA signature immediately after having been created.
static void	setUseBachwardsCompatibilityMode(boolean enableBackwardsCompatibility) Decides whether to use DSA in backwards compatibility mode.
static void	setUseBlinding(boolean useBlinding) Decides whether to use blinding for signature generation as countermeasure against timing attacks.

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

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

setUseBlinding

public static void setUseBlinding(boolean useBlinding)

Decides whether to use blinding for signature generation as countermeasure against timing attacks.

Parameters:

useBlinding - whether to use blinding (default: true)

setUseBachwardsCompatibilityMode

public static void setUseBachwardsCompatibilityMode(boolean enableBackwardsCompatibility)

Decides whether to use DSA in backwards compatibility mode.
By default (if no key size is specified) the DSA KeyPairGenerator generates 2048 bit keys and the DSA Signature engine checks if the security strength of the hash algorithm complies with the key size in use. This means that when generating a default key pair (of 2048 bits) and trying to use it with a "SHA1withDSA" Signature engine the Signature engine will reject the signature generation because SHA-1 is not appropriate for use with 2048 DSA keys. When setting

 DSA.setUseBackwardsCompatibilityMode(true);
 

the default key length used by the DSAKeyPairGenerator is set to 1024 and the DSA signature engine does not check for the security strength of the hash algorithm. Enabling the backwards compatibility mode is not recommended. More appropriate you should use a SHA224withDSA or SHA256withDSA Signature engine and KeyPairGenerator. Even better you should switch to the elliptic curve variant ECDSA since the usage of DSA is deprecated by security protocols like, for instance, TLS.

Note that this parameter only affects the key pair and signature generation not the signature verification and not the compatibility with other applications.

Parameters:

enableBackwardsCompatibility - whether to enable backwards compatibility (default: false)

setCheckSigValueForDERCompliance

public static void setCheckSigValueForDERCompliance(boolean checkForDER)

Decides whether to check if the encoding of the DSA signature complies with the Distinguished Encoding Rules (DER).
If set to true a SignatureException is thrown when calling signature.verify(sigValue) and the signature value is not not properly DER encoded (for instance, if the length has not been encoded in the minimum number of octets).

Parameters:

checkForDER - whether to check if the encoding of the DSA signature complies with the Distinguished Encoding Rules (DER) (default: true the signature value is checked)

setDoVerifySignature

public static void setDoVerifySignature(boolean doVerify)

Decides whether to verify a DSA signature immediately after having been created.

Verification of an DSA signature maybe appropriate as countermeasure against fault attacks on signatures (one that is correct and a second that has a fault) that are produced with the same nonce value. Verifying a signature immediately after creation may be appropriate escpecially when DSA is used in deterministic mode. For that reason this implementation by default verifies deterministic DSA signatures immediately after creation and (for performance reasons) does not verify non-deterministic DSA signatures.

An application can change the default behavior by either enabling automatic DSA signature verification for all (deterministic and non-deterministic) signatures (for the sake of security):

 DSA.setDoVerifySignature(true);
 

or by disabling it for all (deterministic and non-deterministic) signatures (for the sake of performance):

 DSA.setDoVerifySignature(false);
 

Parameters:

doVerify - true to verify any DSA signature immediately after creation, false to not verify any DSA signature immediately after creation

engineInitVerify

protected void engineInitVerify(java.security.PublicKey publicKey)
                         throws java.security.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.

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

Specified by:

engineInitSign in class java.security.SignatureSpi

Parameters:

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

Throws:

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

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. This method actually updates the data to be hashed using the SHA algorithm.

Specified by:

engineUpdate in class java.security.SignatureSpi

Parameters:

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

Specified by:

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

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.

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

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.

See Also:

RawDSA.engineSign()

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.

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

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.

See Also:

RawDSA.engineVerify(byte[])

engineSetParameter

protected void engineSetParameter(java.lang.String param,
                      java.lang.Object value)
                           throws java.security.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.

Specified by:

engineSetParameter in class java.security.SignatureSpi

Parameters:

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

value - the value of the parameter to be set

Throws:

java.security.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(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. 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.

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

Throws:

java.security.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)

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