iaik.security.dh

Class DHKeyAgreement

java.lang.Object

javax.crypto.KeyAgreementSpi

iaik.security.dh.DHKeyAgreement

public class DHKeyAgreement
extends javax.crypto.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 23

See Also:

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

Constructor Summary

Constructors

Constructor and Description
DHKeyAgreement() Empty default Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected java.security.Key	engineDoPhase(java.security.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 javax.crypto.SecretKey	engineGenerateSecret(java.lang.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(java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this Diffie Helman KeyAgreement with the given key, algorithm parameters, and random seed.
protected void	engineInit(java.security.Key key, java.security.SecureRandom random) Initializes this Diffie-Hellman 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(java.security.Key key,
              java.security.spec.AlgorithmParameterSpec params,
              java.security.SecureRandom random)
                   throws java.security.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).

Specified by:

engineInit in class javax.crypto.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 (unused)

Throws:

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

engineInit

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

Initializes this Diffie-Hellman 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).

Specified by:

engineInit in class javax.crypto.KeyAgreementSpi

Parameters:

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

random - the random seed

Throws:

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

engineDoPhase

protected java.security.Key engineDoPhase(java.security.Key key,
                              boolean lastPhase)
                                   throws java.security.InvalidKeyException,
                                          java.lang.IllegalStateException

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

Specified by:

engineDoPhase in class javax.crypto.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 agreement, false if not

Returns:

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

Throws:

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

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

engineGenerateSecret

protected javax.crypto.SecretKey engineGenerateSecret(java.lang.String algorithm)
                                               throws java.lang.IllegalStateException,
                                                      java.security.NoSuchAlgorithmException,
                                                      java.security.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

Specified by:

engineGenerateSecret in class javax.crypto.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:

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

java.security.NoSuchAlgorithmException - if the given secret key algorithm is not supported

java.security.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 java.lang.IllegalStateException,
                                   javax.crypto.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.

Specified by:

engineGenerateSecret in class javax.crypto.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:

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

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

engineGenerateSecret

protected byte[] engineGenerateSecret()
                               throws java.lang.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.

Specified by:

engineGenerateSecret in class javax.crypto.KeyAgreementSpi

Returns:

the generated shared secret within a byte array

Throws:

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