iaik.security.dsa
Class DSAPrivateKey

java.lang.Object
  |
  +--iaik.pkcs.pkcs8.PrivateKeyInfo
        |
        +--iaik.security.dsa.DSAPrivateKey

public class DSAPrivateKey

extends PrivateKeyInfo

implements DSAPrivateKey, java.io.Serializable

An implementation of a DSA private key that supports ASN.1 encoding.

This class extends iaik.pkcs.pkcs8.PrivateKeyInfo for supporting the PKCS#8 Private Key Information Standard for the DSA private keys. This class implements the java.security.interfaces.DSAPrivateKey interface for providing the functionality of a private key used for signing some data within the DSA 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 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).

An application wishing to create a DSAPrivateKey to be used for data signing with the DSA algorithm, uses a proper getInstance method of the java.security.KeyPairGenerator class, which subsequently maybe casted to DSAKeyPairGenerator for performing an algorithm-specific initialization with proper DSA parameters. If an algorithm-specific initialization is not required, the cast to DSAKeyPairGenerator can be omitted.

Generally four steps have to be performed for creating a DSAPrivateKey by using a proper KeyPairGenerator:

• First the KeyPairGenerator has to be instantiated thereby specifying the application´s intention to create keys for use within the DSA algorithm:
  

   KeyPairGenerator key_gen = KeyPairGenerator.getInstance("DSA");
   

• Second, the KeyPairGenerator just created may be initialized using a proper initialize method. For initializing the generator to create keys with a modulus length of, e.g., 1024 bits, this can be explicitly specified (1024 bits also is the default value for the modulus length when not explicitly initializing the generator):
  

   key_gen.initialize(1024);
   

• Third the key pair is created by calling generateKeyPair():
  KeyPair key_pair = key_gen.generateKeyPair();
• And finally, if there is need for the DSA private key, it has to be obtained from the key pair just created:
  

   DSAPrivateKey dsa_priv_key = (DSAPrivateKey)key_pair.getPrivate();
   

For performing an algorithm-specific initialization with particular DSA parameters (which may be an instance of DSAParams representing the public parameter values p, q and g), an explicit cast of the KeyPairGenerator will be necessary for obtaining a specific DSAKeyPairGenerator to be initialized with the desired DSA parameters:

 DSAKeyPairGenerator dsa_key_gen = (DSAKeyPairGenerator)key_gen;
 dsa_key_gen.initialize(dsa_params, random);
 

(where random denotes some random seed)

Guidelines on how to create some key using a KeyPairGenerator can be found in http://java.sun.com/products/JDK/1.1/docs/guide/security/CryptoSpec.html.

See Also:

PrivateKeyInfo, DSAPrivateKey, KeyPairGenerator, KeyPair, DSA, RawDSA, DSAPublicKey, DSAKeyPairGenerator, DSAKeyFactory, DSAParams, Serialized Form

Fields inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

private_key_algorithm, private_key_info

Fields inherited from interface java.security.interfaces.DSAPrivateKey

serialVersionUID

Fields inherited from interface java.security.PrivateKey

serialVersionUID

Fields inherited from interface java.security.Key

serialVersionUID

Constructor Summary

DSAPrivateKey(ASN1Object obj)
Creates a new DSAPrivateKey from the given ASN.1 data structure representing a DSAPrivateKey, PrivateKeyInfo or EncryptedPrivateKeyInfo.

DSAPrivateKey(java.math.BigInteger x, java.math.BigInteger p, java.math.BigInteger q, java.math.BigInteger g)
Creates a new DSAPrivateKey from the given BigInteger values.

DSAPrivateKey(java.math.BigInteger x, DSAParams dsaParams)
Creates a new DSAPrivateKey from given private key value x and DSA parameters

DSAPrivateKey(byte[] key)
Creates a new DSAPrivateKey from the given DER encoded byte array.

DSAPrivateKey(DSAPrivateKey privKey)
Creates a new DSAPrivateKey from the given DSAPrivateKey.

DSAPrivateKey(DSAPrivateKeySpec keySpec)
Creates a new DSAPrivateKey from the given DSAPrivateKeySpec representing the DSA private key value x, and the public values p, q and g.

DSAPrivateKey(java.io.InputStream is)
Creates a new DSAPrivateKey from an InputStream.

Method Summary

protected void	decode(byte[] privateKey) Decodes a DER encoded DSA private key.
protected byte[]	encode() Returns this DSA private key as DER encoded byte array.
boolean	equals(java.lang.Object obj) Compares this DSAPrivateKey with the given DSAPrivateKey.
java.lang.String	getAlgorithm() Returns the name of the appertaining algorithm.
DSAParams	getParams() Returns the DSA parameters prime p, sub-prime q and base g as DSAParams.
java.math.BigInteger	getX() Returns the private key value x.
int	hashCode() Returns a hash code for this DSAPrivateKey object.
java.lang.String	toString() Returns a string that represents the contents of this private key.

Methods inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

createPrivateKeyInfo, decode, getEncoded, getFormat, getPrivateKey, getPrivateKey, toASN1Object, writeTo

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DSAPrivateKey

public DSAPrivateKey(java.math.BigInteger x,
                     DSAParams dsaParams)

Creates a new DSAPrivateKey from given private key value x and DSA parameters

Parameters:

x - the BigInteger value representing the DSA private key value

dsaParams - the public DSA parameters p (prime), q (sub-prime) and g (base) as DSAParams

See Also:

DSAParams

DSAPrivateKey

public DSAPrivateKey(java.math.BigInteger x,
                     java.math.BigInteger p,
                     java.math.BigInteger q,
                     java.math.BigInteger g)

Creates a new DSAPrivateKey from the given BigInteger values.

Parameters:

x - the BigInteger value representing the DSA private key

p - the public prime p (of a multiple length of 64 bits between 512 and 1024 bits)

q - the public sub-prime q (a 160-bit prime factor of p-1)

g - the public base g (=(h^(p-1)/q)(mod p) > 1, with h < p-1)

DSAPrivateKey

public DSAPrivateKey(DSAPrivateKeySpec keySpec)

Creates a new DSAPrivateKey from the given DSAPrivateKeySpec representing the DSA private key value x, and the public values p, q and g.

Parameters:

keySpec - the DSAPrivateKeySpec representing the private key value x, the prime p, the sub-prime q, and the base g

See Also:

DSAPrivateKeySpec

DSAPrivateKey

public DSAPrivateKey(DSAPrivateKey privKey)

Creates a new DSAPrivateKey from the given DSAPrivateKey.

Parameters:

privKey - the DSAPrivateKey

DSAPrivateKey

public DSAPrivateKey(byte[] key)
              throws InvalidKeyException

Creates a new DSAPrivateKey from the given DER encoded byte array.

Parameters:

key - the byte array holding the DER encoded private key ASN.1 data structure

Throws:

InvalidKeyException - if something is wrong with the encoding of the key

DSAPrivateKey

public DSAPrivateKey(ASN1Object obj)
              throws InvalidKeyException

Creates a new DSAPrivateKey from the given ASN.1 data structure representing a DSAPrivateKey, PrivateKeyInfo or EncryptedPrivateKeyInfo.

Parameters:

obj - the private key ASN.1 data structure

Throws:

InvalidKeyException - if something is wrong with the key encoding

DSAPrivateKey

public DSAPrivateKey(java.io.InputStream is)
              throws InvalidKeyException,
                     java.io.IOException

Creates a new DSAPrivateKey from an InputStream.

Parameters:

is - the input stream with the data to be read to initialize the private key

Throws:

InvalidKeyException - if something is wrong with the key encoding

java.io.IOException - if an I/O error occurs

Method Detail

getX

public java.math.BigInteger getX()

Returns the private key value x.

Specified by:

getX in interface DSAPrivateKey

Returns:

the private key value x

getParams

public DSAParams getParams()

Returns the DSA parameters prime p, sub-prime q and base g as DSAParams.

Returns:

the DSAParams representing prime p, sub-prime q and base g

encode

protected byte[] encode()

Returns this DSA private key as DER encoded byte array.

Overrides:

encode in class PrivateKeyInfo

Returns:

the DSA private key as a DER encoded ASN.1 data structure

decode

protected void decode(byte[] privateKey)
               throws InvalidKeyException

Decodes a DER encoded DSA private key. From the given DER encoded byte array an ASN.1 object is created and parsed for the private key value x.

Overrides:

decode in class PrivateKeyInfo

Parameters:

privateKey - the DSA private key as DER encoded byte array

Throws:

InvalidKeyException - if the given key is not a DSA private key

getAlgorithm

public java.lang.String getAlgorithm()

Returns the name of the appertaining algorithm.

Overrides:

getAlgorithm in class PrivateKeyInfo

Returns:

the string "DSA"

hashCode

public int hashCode()

Returns a hash code for this DSAPrivateKey object.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code

equals

public boolean equals(java.lang.Object obj)

Compares this DSAPrivateKey with the given DSAPrivateKey.

Overrides:

equals in class PrivateKeyInfo

Parameters:

obj - the other DSAPrivateKey

Returns:

true, if the two private key objects are equal, false otherwise

toString

public java.lang.String toString()

Returns a string that represents the contents of this private key.

Overrides:

toString in class PrivateKeyInfo

Returns:

the string representation