com.entrust.toolkit.security.provider

Class EntrustDSA

java.lang.Object

java.security.SignatureSpi

java.security.Signature

com.entrust.toolkit.security.provider.EntrustDSA

All Implemented Interfaces:

ExtendedSignature

Direct Known Subclasses:

DsaCapi, EntrustDSA.Raw, EntrustDSAImpl, EntrustDSAPKCS11, EntrustRawDSAPKCS11

Deprecated.

since 8.0; use DsaWithSha1Signature instead

public class EntrustDSA
extends java.security.Signature
implements ExtendedSignature

Implements the Digital Signature Standard (DSA with SHA-1) signature algorithm as specified in FIPS PUB 186.

The Digital Signature Algorithm (DSA) can be used only for signing and verifying digital signatures — it cannot be used for data encryption.

NIST's Digital Signature Standard (DSS) specifies the DSA algorithm as a public-key algorithm for use by digital signing applications. To calculate a hash value of the data to be signed, DSS uses the Secure Hash Algorithm (SHA) with the DSA algorithm. This EntrustDSA class adds the capability of the SHA hash algorithm to the pure DSA algorithm, which is implemented by a raw DSA implementation class. Internally, the EntrustDSA class creates a SHA hash of your data before signing it.

Generally, an application intending to sign data and to verify signatures has to perform three steps:

1. Create an instance of the desired signature algorithm by using a proper getInstance method. For example:

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

2. The Signature object, just created, has to be properly initialized for signing a data and verifying a signature using DSA private and public keys. For example:
   • Initialize for Signing — dsa.initSign(dsaPrivateKey);
   • Initialize for Verifying — dsa.initVerify(dsaPublicKey);
3. If the Signature object has been initialized for signing, the data to be signed is supplied to it and the signature is created by calling the sign method. This method returns the signature as a DER-encoded byte array. If the Signature object has been initialized for verifying, the data to be verified is supplied to the Signature object, and the signature is verified by calling the verify method. This method takes the DER-encoded byte array representing the signature as an argument.
• Supply the data to be signed, and 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!"));
   

Internally, the DSA algorithm uses the following parameters:

• A prime number p, whose 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 such that (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 following key types are currently supported:

• Standard DSA public/private keys (software keys); instances of java.security.interfaces.DSAPublicKey or java.security.interfaces.DSAPrivateKey.
• Entrust confined DSA private keys (secure software keys); instances of DsaConfinedPrivateKey.
• DSA private keys that reside on smart cards and are accessible via PKCS #11 (token keys); instances of TokenDSAPrivateKey .

See Also:

SHA1, Signature

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EntrustDSA.Raw Deprecated. since 8.0; use DsaWithNoneSignature instead

Field Summary

Fields inherited from class java.security.Signature

SIGN, state, UNINITIALIZED, VERIFY

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

Constructors

Constructor and Description
EntrustDSA() Deprecated. Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected java.lang.Object	engineGetParameter(java.lang.String param) Deprecated. Returns an object for a parameter previously set, given a proper String parameter.
protected void	engineInitSign(java.security.PrivateKey privateKey) Deprecated. SPI: Initializes this DSA Signature object with the given DSA private key in preparation for signing data.
protected void	engineInitVerify(java.security.PublicKey publicKey) Deprecated. 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) Deprecated. Initializes this DSA signature engine with the given parameter set.
protected void	engineSetParameter(java.lang.String param, java.lang.Object value) Deprecated. SPI: Sets the specified algorithm parameter to the specified value.
protected byte[]	engineSign() Deprecated. SPI: Returns the signature bytes of all the data updated so far.
protected void	engineUpdate(byte b) Deprecated. SPI: Updates the data to be signed or verified with the specified byte.
protected void	engineUpdate(byte[] b, int off, int len) Deprecated. 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) Deprecated. SPI: Verifies the given signature.
byte[]	getDigest() Deprecated. Returns the digest that was calculated during signature generation or verification.
protected static byte[]	RStoASN1(java.math.BigInteger[] rs) Deprecated. Converts the (r,s) signature pair to ASN1.
protected static byte[]	RStoASN1(java.math.BigInteger r, java.math.BigInteger s) Deprecated. Converts the (r,s) signature pair to ASN1.

Methods inherited from class java.security.Signature

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

Methods inherited from class java.security.SignatureSpi

engineGetParameters, engineInitSign, engineSign, engineUpdate, engineVerify

Methods inherited from class java.lang.Object

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

Constructor Detail

EntrustDSA

public EntrustDSA()

Deprecated.

Default constructor.

Creates a new DSA Signature object.

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

See Also:

SHA1, Signature.getInstance(java.lang.String)

Method Detail

RStoASN1

protected static byte[] RStoASN1(java.math.BigInteger[] rs)
                          throws java.security.SignatureException

Deprecated.

Converts the (r,s) signature pair to ASN1.

Parameters:

rs - an array of two BigInteger objects, with rs[0] = r and rs[1] = s.

Returns:

the ASN.1 encoding of the signature as required by DSS.

Throws:

java.security.SignatureException - if there is an error converting the integers to ASN.1.

Since:

7.0

RStoASN1

protected static byte[] RStoASN1(java.math.BigInteger r,
              java.math.BigInteger s)
                          throws java.security.SignatureException

Deprecated.

Converts the (r,s) signature pair to ASN1.

Parameters:

r - The first component of the signature.

s - The second component of the signature.

Returns:

the ASN.1 encoding of the signature as required by DSS.

Throws:

java.security.SignatureException - if there is an error converting the integers to ASN.1.

Since:

7.0

engineInitVerify

protected void engineInitVerify(java.security.PublicKey publicKey)
                         throws java.security.InvalidKeyException

Deprecated.

SPI: Initializes this DSA 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 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

Deprecated.

SPI: Initializes this DSA Signature object with the given DSA private key in preparation for signing 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 a key encoding error occurs

engineUpdate

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

Deprecated.

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

Deprecated.

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 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 specified position

Throws:

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

engineSign

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

Deprecated.

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.

engineVerify

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

Deprecated.

SPI: Verifies the given signature.

The signature bytes are expected to be X.509 (DER)-encoded. The method updates the underlying DSA implementation class with the hashed data and verifies the given signature using the its engineVerify implemetation.

Specified by:

engineVerify in class java.security.SignatureSpi

Parameters:

sigBytes - the signature bytes to be verified

Returns:

true if the signature is valid, 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:

engineVerify(byte[])

engineSetParameter

protected void engineSetParameter(java.lang.String param,
                      java.lang.Object value)
                           throws java.security.InvalidParameterException

Deprecated.

SPI: Sets the specified algorithm parameter to the specified value.

This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as a parameter size, or a source of random bits for signature generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

Specified by:

engineSetParameter in class java.security.SignatureSpi

Parameters:

param - the string identifier of the parameter

value - the parameter value

Throws:

java.security.InvalidParameterException - if param is an invalid parameter for this signature algorithm engine, the parameter is already set and cannot be set again, a security exception occurs, and so on.

engineSetParameter

protected void engineSetParameter(java.security.spec.AlgorithmParameterSpec params)
                           throws java.security.InvalidAlgorithmParameterException

Deprecated.

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 can be used only with J2SDK1.2 and later. This method may be useful for initializing the signature verification in situations where there are no parameters included in the subjectPublicKeyInfo field of an 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

Deprecated.

Returns an object for a parameter previously set, given a proper String parameter.

Specified by:

engineGetParameter in class java.security.SignatureSpi

Parameters:

param - the String that identifies the particular parameter

Returns:

The object that is related to the given input String .

Throws:

java.security.InvalidParameterException - if the given parameter is not suitable

getDigest

public byte[] getDigest()

Deprecated.

Description copied from interface: ExtendedSignature

Returns the digest that was calculated during signature generation or verification.

During both a signature generation and verification operation a digest is calculated over the message; this digest is then used as an input to the signature generation or verification process. This API simply provides access to the digest once it has been calculated; it always returns the digest from the last operation. If a signature generation or verification operation has not yet been executed or is in the process of being executed, null is returned.

To ensure a non-null result, this method should only be called after Signature.sign() or Signature.verify() has called.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

getDigest in interface ExtendedSignature

Returns:

[FIPS 140-2 data output] the digest that was calculated during signature generation or verification