iaik.security.dh
Class DHKeyAgreement

java.lang.Object
  |
  +--javax.crypto.KeyAgreementSpi
        |
        +--iaik.security.dh.DHKeyAgreement

public class DHKeyAgreement

extends KeyAgreementSpi

This class extends javax.crypto.KeyAgreementSpi for providing the functionality of a Diffie Hellman key agreement as specified by PKCS#3.

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 21

See Also:

KeyAgreement, DHGenParameterSpec, DHParameterSpec, DHPrivateKeySpec, DHPublicKeySpec, KeyPairGenerator, KeyPair, DHPublicKey, DHPrivateKey, DHKeyPairGenerator, DHKeyFactory, DHParameters, DHParameterGenerator

Constructor Summary

DHKeyAgreement()
Empty default Constructor.

Method Summary

protected Key	engineDoPhase(Key key, boolean lastPhase) Returns the key resulting from the next phase of this DH key agreement.
protected byte[]	engineGenerateSecret() Returns the shared secret finally generated by this DH key agreement.
protected int	engineGenerateSecret(byte[] sharedSecret, int offset) Generates the shared secret finishing this DH key agreement procedure and writes it into the given byte array, beginning at the given offset position.
protected SecretKey	engineGenerateSecret(String algorithm) Returns the shared secret finally generated by this DH key agreement as SecretKey to be used for the specified secret key algorithm.
protected void	engineInit(Key key, AlgorithmParameterSpec params, SecureRandom random) Initializes this Diffie Helman KeyAgreement with the given key, algorithm parameters, and random seed.
protected void	engineInit(Key key, SecureRandom random) Initializes this Diffie Hallman KeyAgreement with the given key and random seed, where the given key constitutes the private DH key (including all required algorithm parameters) of some entity being involved in this key agreement procedure.

Methods inherited from class java.lang.Object

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

Constructor Detail

DHKeyAgreement

public DHKeyAgreement()

Empty default Constructor. Only for internal use. An application shall call

 KeyAgreement.getInstance("DH");
 

for generating an DHKeyAgreement object.

Method Detail

engineInit

protected void engineInit(Key key,
                          AlgorithmParameterSpec params,
                          SecureRandom random)
                   throws InvalidKeyException

Initializes this Diffie Helman KeyAgreement with the given key, algorithm parameters, and random seed.

The given key constitutes the private DH key of some entity being involved in this DH key agreement procedure. Each entity being involved in a DH key agreement process has to create a KeyAgreement object by using a proper getInstance factory method (e.g. KeyAgreement.getInstance("DH");) and subsequently initialize it with the entity´s private DH key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doPhase methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement).

Overrides:

engineInit in class KeyAgreementSpi

Parameters:

key - the private DH key information of the entity involved in the key agreement

params - the algorithm parameter specification used for this key agreement algorithm

random - the random seed

Throws:

InvalidKeyException - if the given key cannot be used for this key agreement

engineInit

protected void engineInit(Key key,
                          SecureRandom random)
                   throws InvalidKeyException

Initializes this Diffie Hallman KeyAgreement with the given key and random seed, where the given key constitutes the private DH key (including all required algorithm parameters) of some entity being involved in this key agreement procedure.

Each entity being involved in a DH key agreement process has to create a KeyAgreement object by using a proper getInstance factory method (e.g. KeyAgreement.getInstance("DH");) and subsequently initialize it with the entity´s private DH key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doPhase methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement).

Overrides:

engineInit in class KeyAgreementSpi

Parameters:

key - the private DH key information of the entity involved in the key agreement

random - the random seed

Throws:

InvalidKeyException - if the given key cannot be used for this key agreement

engineDoPhase

protected Key engineDoPhase(Key key,
                            boolean lastPhase)
                     throws InvalidKeyException,
                            IllegalStateException

Returns the key resulting from the next phase of this DH key agreement.

Overrides:

engineDoPhase in class KeyAgreementSpi

Parameters:

key - the required key for this phase, supplied by some other entity involved in this key agreement

lastPhase - true if this is the last phase of this key agreemant, false if not

Returns:

the key resulting from this phase, or null if no key is returned by this phase

Throws:

InvalidKeyException - if the given key cannot be used for this key agreement algorithm / phase

IllegalStateException - if the given phase cannot be performed in this state of the key agreement procedure

engineGenerateSecret

protected SecretKey engineGenerateSecret(String algorithm)
                                  throws IllegalStateException,
                                         NoSuchAlgorithmException,
                                         InvalidKeyException

Returns the shared secret finally generated by this DH key agreement as SecretKey to be used for the specified secret key algorithm.

After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

At this time the following algorithms are supported:

• DES
• 3DES
• IDEA
• GOST
• CAST128

Overrides:

engineGenerateSecret in class KeyAgreementSpi

Parameters:

algorithm - the name of the secret key algorithm for which the generated secret key shall be used

Returns:

the generated shared secret as SecretKey

Throws:

IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

NoSuchAlgorithmException - if the given secret key algorithm is not supported

InvalidKeyException - if the generated shared secret cannot be returned as SecretKey matching to the given algorithm

engineGenerateSecret

protected int engineGenerateSecret(byte[] sharedSecret,
                                   int offset)
                            throws IllegalStateException,
                                   ShortBufferException

Generates the shared secret finishing this DH key agreement procedure and writes it into the given byte array, beginning at the given offset position.

After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

Overrides:

engineGenerateSecret in class KeyAgreementSpi

Parameters:

sharedSecret - the byte array to which the generated secret has to be written

offset - the offset indicating the start position within the output byte array to which to write the generated shared secret

Returns:

the number of bytes that are stored in the output byte array

Throws:

IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

ShortBufferException - if the given output buffer is too small for holding the secret

engineGenerateSecret

protected byte[] engineGenerateSecret()
                               throws IllegalStateException

Returns the shared secret finally generated by this DH key agreement.

After creating the shared secret, this DHKeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

Overrides:

engineGenerateSecret in class KeyAgreementSpi

Returns:

the generated shared secret within a byte array

Throws:

IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret