iaik.security.dsa

Class DSAPublicKey

java.lang.Object

iaik.x509.PublicKeyInfo

iaik.security.dsa.DSAPublicKey

All Implemented Interfaces:

ASN1Type, java.io.Serializable, java.lang.Cloneable, java.security.interfaces.DSAKey, java.security.interfaces.DSAPublicKey, java.security.Key, java.security.PublicKey

public class DSAPublicKey
extends PublicKeyInfo
implements java.security.interfaces.DSAPublicKey

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

This class extends iaik.x509.PublicKeyInfo for supporting DSA public keys to be used within X.509 certificates . This class implements the java.security.interfaces.DSAPublicKey interface for providing the functionality of a public key used for verifying some signature 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 DSAPublicKey to be used for signature verifying 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 DSAPublicKey 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 public key, it has to be obtained from the key pair just created:
  

   DSAPublicKey dsa_pub_key = (DSAPublicKey)key_pair.getPublic();
   

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.

Version:

File Revision 23

See Also:

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

Field Summary

Fields inherited from class iaik.x509.PublicKeyInfo

public_key_algorithm

Constructor Summary

Constructors

Constructor and Description
DSAPublicKey(ASN1Object obj) Creates a new DSAPublicKey from the given ASN.1 object.
DSAPublicKey(java.math.BigInteger y, java.math.BigInteger p, java.math.BigInteger q, java.math.BigInteger g) Creates a new DSAPublicKey from the given BigInteger values.
DSAPublicKey(java.math.BigInteger y, java.security.interfaces.DSAParams dsaParams) Creates a new DSAPublicKey from given public key value y and DSA parameters
DSAPublicKey(byte[] key) Creates a new DSAPublicKey from the given DER encoded ASN.1 data structure.
DSAPublicKey(java.security.interfaces.DSAPublicKey pubKey) Creates a new DSAPublicKey from the given DSAPublicKey.
DSAPublicKey(java.security.spec.DSAPublicKeySpec keySpec) Creates a new DSAPublicKey from the given DSAPublicKeySpec representing the DSA public key value y, and the public values p, q and g.
DSAPublicKey(java.io.InputStream is) Creates a new DSAPublicKey from an InputStream.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	decode(byte[] publicKey) Decodes a DSAPublicKey, encoded in DER format.
byte[]	encode() Returns the raw DSA public key (not wrapped by a X.509 PublicKeyInfo) as DER encoded ASN.1 object.
boolean	equals(java.lang.Object obj) Compares this DSAPublicKey with the given DSAPublicKey.
java.lang.String	getAlgorithm() Returns the String "DSA"
java.security.interfaces.DSAParams	getParams() Returns the DSA parameters prime p, sub-prime q and base g as DSAParams.
java.math.BigInteger	getY() Returns the public key value y.
int	hashCode() Returns a hash code for this DSAPublicKey object.
boolean	isValidSP80089SignatureVerificationKey() Determines whether this public key is valid for signature verification according to NIST SP 800-89.
java.lang.String	toString() Returns a string that represents the contents of this private key.

Methods inherited from class iaik.x509.PublicKeyInfo

clone, createPublicKeyInfo, decode, getAlgorithmID, getEncoded, getFingerprint, getFormat, getPublicKey, getPublicKey, getPublicKey, getPublicKey, getPublicKey, getPublicKey, toASN1Object, writeTo

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.security.Key

getEncoded, getFormat

Constructor Detail

DSAPublicKey

public DSAPublicKey(java.math.BigInteger y,
            java.security.interfaces.DSAParams dsaParams)

Creates a new DSAPublicKey from given public key value y and DSA parameters

Parameters:

y - the BigInteger value representing the DSA public key value

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

See Also:

DSAParams

DSAPublicKey

public DSAPublicKey(java.math.BigInteger y,
            java.math.BigInteger p,
            java.math.BigInteger q,
            java.math.BigInteger g)

Creates a new DSAPublicKey from the given BigInteger values.

Parameters:

y - the BigInteger value representing the DSA public 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)

DSAPublicKey

public DSAPublicKey(java.security.spec.DSAPublicKeySpec keySpec)

Creates a new DSAPublicKey from the given DSAPublicKeySpec representing the DSA public key value y, and the public values p, q and g.

Parameters:

keySpec - the DSAPublicKeySpec representing the public key value y, the prime p, the sub-prime q, and the base g

See Also:

DSAPublicKeySpec

DSAPublicKey

public DSAPublicKey(java.security.interfaces.DSAPublicKey pubKey)

Creates a new DSAPublicKey from the given DSAPublicKey.

Parameters:

pubKey - the DSAPublicKey

DSAPublicKey

public DSAPublicKey(byte[] key)
             throws java.security.InvalidKeyException

Creates a new DSAPublicKey from the given DER encoded ASN.1 data structure.

This constructor may be used for parsing an already existing DSA public key, wrapped into a X.509 PublicKeyInfo that is supplied as DER encoded byte array.

Parameters:

key - the byte array holding the DER encoded public key info

Throws:

java.security.InvalidKeyException - if something is wrong with the key encoding

DSAPublicKey

public DSAPublicKey(ASN1Object obj)
             throws java.security.InvalidKeyException

Creates a new DSAPublicKey from the given ASN.1 object. The supplied ASN1Object represents a X.509 PublicKeyInfo holding the DSA public key.

Parameters:

obj - the public key ASN.1 data structure

Throws:

java.security.InvalidKeyException - if something is wrong with the key encoding

DSAPublicKey

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

Creates a new DSAPublicKey from an InputStream.

This constructor may be used for parsing an already existing DH public key, wrapped into a X.509 PublicKeyInfo that is supplied as DER encoded byte array.

Parameters:

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

Throws:

java.security.InvalidKeyException - if something is wrong with the key encoding

java.io.IOException - if something is wrong with the file

Method Detail

getY

public java.math.BigInteger getY()

Returns the public key value y.

Specified by:

getY in interface java.security.interfaces.DSAPublicKey

Returns:

the public key value y

getParams

public java.security.interfaces.DSAParams getParams()

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

Specified by:

getParams in interface java.security.interfaces.DSAKey

Returns:

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

getAlgorithm

public java.lang.String getAlgorithm()

Returns the String "DSA"

Specified by:

getAlgorithm in interface java.security.Key

Specified by:

getAlgorithm in class PublicKeyInfo

Returns:

the name of the key algorithm

decode

protected void decode(byte[] publicKey)
               throws java.security.InvalidKeyException

Decodes a DSAPublicKey, encoded in DER format.

This method is protected and typically will not be used by an application. Rather it is used by the parent X.509 PublicKeyInfo class for decoding the inherent DSA public key.

Specified by:

decode in class PublicKeyInfo

Parameters:

publicKey - the public key as DER encoded ASN.1 object

Throws:

java.security.InvalidKeyException - if the given key is not a DSA public key

encode

public byte[] encode()

Returns the raw DSA public key (not wrapped by a X.509 PublicKeyInfo) as DER encoded ASN.1 object.

This method typically may not be used by an application. Rather it is used by the parent X.509 PublicKeyInfo class for encoding the inherent DSA public key.

Specified by:

encode in class PublicKeyInfo

Returns:

this DSAPublicKey as DER encoded ASN.1 data structure

hashCode

public int hashCode()

Returns a hash code for this DSAPublicKey object.

Overrides:

hashCode in class PublicKeyInfo

Returns:

the hash code

equals

public boolean equals(java.lang.Object obj)

Compares this DSAPublicKey with the given DSAPublicKey.

Overrides:

equals in class PublicKeyInfo

Parameters:

obj - the other DSAPublicKey

Returns:

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

isValidSP80089SignatureVerificationKey

public boolean isValidSP80089SignatureVerificationKey()
                                               throws java.security.InvalidAlgorithmParameterException

Determines whether this public key is valid for signature verification according to NIST SP 800-89.

According to NIST SP 800-89 a DSA public key that is used for signature verification shall be validated by (see section 5.3.1 of NIST SP 800-89):

1. Verify that 2 <= y <= p-2. Comment: Ensure that the key has the unique correct representation and range in the field.
2. Verify that y^q ≡ 1 mod p. Comment: Ensure that the key has the correct order in the subgroup.

Returns:

true, if the public key could be successfully validated false otherwise

Throws:

java.security.InvalidAlgorithmParameterException - if the key cannot be verified because no DSA parameters are included

toString

public java.lang.String toString()

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

Overrides:

toString in class PublicKeyInfo

Returns:

the string representation