iaik.security.dh
Class DHPrivateKey

java.lang.Object
  |
  +--iaik.pkcs.pkcs8.PrivateKeyInfo
        |
        +--iaik.security.dh.DHPrivateKey

All Implemented Interfaces:

ASN1Type, Cloneable, DHKey, DHPrivateKey, Key, PrivateKey, Serializable

public class DHPrivateKey

extends PrivateKeyInfo

implements DHPrivateKey, Serializable

This class implements a Diffie Hellman private key and supports ASN.1 encoding.

This class extends iaik.pkcs.pkcs8.PrivateKeyInfo for supporting the PKCS#8 Private Key Information Standard for DH private keys. This class implements the javax.crypto.interfaces.DHPrivateKey interface for providing the functionality of a private key used for the DH key-exchange algorithm.

The Diffie Hellman algorithm constitutes a key-exchange (or key-agreement) algorithm where some entities communicate according to a predescribed protocol for generating a shared secret only known by them.

The Diffie Hellman algorithm has been the first public-key algorithm. It only can be used for key-agreement, but not for data encrypting and decrypting.

PKCS#3 describes a method for implementing the Diffie Hellman key agreement where two entities use general Diffie Hellman parameters (an odd prime p, an integer base g satisfying 0 < g < p, and optionally an integer l prescribing the length of the private value), generated from some central authority (which may be an entity itself), to perform two phases of the key agreement protocol:

• The first phase is performed independently by the two entities involved in the key agreement and uses the Diffie Hellman parameters derived from the central authority to randomly generate a private integer value x satisfying 0 < x < p-1. If the central authority has prescribed the length l of the private value x, it has to fulfill 2(l-1) <= x < 2l. From the private value, the public value y is created by doing y = (gx)(mod p) with 0 < y < p. Subsequently each entity sends the public value just created to the other entity involved in the key agreement.

• The second phase again is performed independently by the two entities involved in the key agreement and uses the Diffie Hellman parameters derived from the central authority and the public value y' received from the other entity to finally create the shared secret z from the own private value x: z = (y'x)(mod p) with 0 < z < p.

There may be more than only two entities involved into a Diffie Hellman key agreement.

Any application wishing to be participated into a Diffie Hellman key agreement has to instantiate the javax.crypto.KeyAgreement class and initialize it with its DHPrivateKey for bringing in the required private information. A DH Hellman private key maybe generated using a proper key pair generator, e.g.:

 KeyPairGnerator dh_key_gen = KeyPairGenerator.getInstance("DH");
 dh_key_gen.initialize(1024);
 KeyPair dh_key_pair = dh_key_gen.generateKeyPair();
 DHPrivateKey dh_priv_key = (DHPrivateKey)dh_key_pair.getPrivate();
 KeyAgreement dh_key_agreement = KeyAgreement.getInstance("DH");
 dh_key_agreement.init(dh_priv_key);
 

Each phase of a key agreement is performed by a call to the doPhase method, supplied with some other entity´s public key or some intermediate key resulting from the last phase. When calling doPhase, it has to be specified whether to perform already the last phase of the key agreement or not by setting the lastPhase parameter to true or false:

 dh_key_agreement.doPhase(dhPubKey_from_other_entity, true);
 

Actually generating the shared secret is done by calling the generateSecret method:

 byte[] shared_secret = dh_key_agreemant.generateSecret();
 

Version:

File Revision 22

See Also:

PrivateKeyInfo, DHPrivateKey, KeyAgreement, DHGenParameterSpec, DHParameterSpec, DHPrivateKeySpec, DHPublicKeySpec, KeyPairGenerator, KeyPair, DHPublicKey, DHKeyPairGenerator, DHKeyFactory, DHParameters, DHParameterGenerator, DHKeyAgreement, Serialized Form

Fields inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

private_key_algorithm

Fields inherited from interface java.security.PrivateKey

serialVersionUID

Constructor Summary

DHPrivateKey(ASN1Object obj)
Creates a new DHPrivateKey from the given ASN.1 object.

DHPrivateKey(BigInteger x, DHParameterSpec parameters)
Creates a new DHPrivateKey from given private key value x and DH parameter specification

DHPrivateKey(byte[] pk)
Creates a new DHPrivateKey from the given DER encoded byte array.

DHPrivateKey(DHPrivateKeySpec keySpec)
Creates a new DHPrivateKey from the given DHPrivateKeySpec representing the DH private key value x, and the public values p, g and l.

DHPrivateKey(InputStream is)
Creates a new DHPrivateKey from an InputStream.

Method Summary

protected void	decode(byte[] privateKey) Decodes a DER encoded DH private key.
byte[]	encode() Returns this DH private key as DER encoded ASN.1 object.
String	getAlgorithm() Returns the name of the appertaining algorithm.
DHParameterSpec	getParams() Returns the key parameters.
BigInteger	getX() Returns the private value x as BigInteger.
int	hashCode() Returns a hash code for this object.
String	toString() Returns a string that represents the contents of this private key.

Methods inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

clone, createPrivateKeyInfo, decode, equals, getEncoded, getFormat, getPrivateKey, getPrivateKey, 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

DHPrivateKey

public DHPrivateKey(BigInteger x,
                    DHParameterSpec parameters)

Creates a new DHPrivateKey from given private key value x and DH parameter specification

Parameters:

x - the BigInteger value representing the DH private key value

parameters - the DH parameters p (prime modulus), g (base generator) and l (length of the private value x) as DHParameterSpec

See Also:

DHParameterSpec

DHPrivateKey

public DHPrivateKey(DHPrivateKeySpec keySpec)

Creates a new DHPrivateKey from the given DHPrivateKeySpec representing the DH private key value x, and the public values p, g and l.

Parameters:

keySpec - the DHPrivateKeySpec representing the private key value x, the prime modulus p, the base generator g, and the length l of the private value

See Also:

DHPrivateKeySpec

DHPrivateKey

public DHPrivateKey(byte[] pk)
             throws InvalidKeyException

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

This constructor may be used for parsing an already exisiting DH private key, wrapped into a PKCS#8 PrivateKeyInfo that is supplied as DER encoded byte array.

Parameters:

the - byte array holding the DER encoded private key info

Throws:

InvalidKeyException - if something is wrong with the key encoding

DHPrivateKey

public DHPrivateKey(ASN1Object obj)
             throws InvalidKeyException

Creates a new DHPrivateKey from the given ASN.1 object. The supplied ASN1Object represents a PKCS#8 PrivateKeyInfo holding the DH private key.

Parameters:

obj - the private key ASN.1 data structure

Throws:

InvalidKeyException - if something is wrong with the key encoding

DHPrivateKey

public DHPrivateKey(InputStream is)
             throws IOException,
                    InvalidKeyException

Creates a new DHPrivateKey from an InputStream.

This constructor may be used for parsing an already exisiting DH private key, wrapped into a PKCS#8 PrivateKeyInfo that is supplied as DER encoded byte array.

Parameters:

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

Throws:

IOException - if an I/O error occurs

InvalidKeyException - if something is wrong with the key encoding

Method Detail

decode

protected void decode(byte[] privateKey)
               throws InvalidKeyException

Decodes a DER encoded DH private key.

From the given DER encoded byte array an ASN.1 object is created and parsed for the private key value x and the DH parameters prime p and base g, and - if included - the length l of the private value x.

This method is protected and typically will not be used by an application. Rather it is used by the parent PKCS#8 PrivateKeyInfo class for decoding the inherent DH private key.

Overrides:

decode in class PrivateKeyInfo

Parameters:

privateKey - the DH private key as DER encoded ASN.1 object

Throws:

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

encode

public byte[] encode()

Returns this DH private key as DER encoded ASN.1 object.

This method is protected and typically will not be used by an application. Rather it is used by the parent PKCS#8 PrivateKeyInfo class for encoding the inherent DH private key.

Overrides:

encode in class PrivateKeyInfo

Returns:

a byte array holding the DH private key as a DER encoded ASN.1 data structure

getX

public BigInteger getX()

Returns the private value x as BigInteger.

Specified by:

getX in interface DHPrivateKey

Returns:

the private value x as BigInteger

getParams

public DHParameterSpec getParams()

Returns the key parameters.

Specified by:

getParams in interface DHKey

Returns:

the key parameters as DHParameterSpec

getAlgorithm

public String getAlgorithm()

Returns the name of the appertaining algorithm.

Specified by:

getAlgorithm in interface Key

Overrides:

getAlgorithm in class PrivateKeyInfo

Returns:

the string "DH"

hashCode

public int hashCode()

Returns a hash code for this object.

Overrides:

hashCode in class PrivateKeyInfo

Returns:

the hash code

toString

public String toString()

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

Overrides:

toString in class PrivateKeyInfo

Returns:

the string representation