iaik.security.dh

Class DHKeyAgreement

java.lang.Object

javax.crypto.KeyAgreementSpi

iaik.security.dh.DHKeyAgreement

Direct Known Subclasses:

SPEKEKeyAgreement

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();
 

This class SHOULD NOT be used directly; it should only be used through the JCA/JCE.

FIPS 140-2:

This class is part of the Toolkit's FIPS 140-2 cryptographic module and contains APIs that are considered part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; refer to the API documentation for further details

See Also:

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

Constructor Summary

Constructors

Constructor and Description
DHKeyAgreement() The constructor; creates a new instance of the DH key agreement algorithm.

Method Summary

Modifier and Type	Method and Description
protected java.security.Key	engineDoPhase(java.security.Key key, boolean lastPhase) Executes the next phase of this key agreement with the given key that was received from one of the other parties involved in this key agreement.
protected byte[]	engineGenerateSecret() Generates the shared secret and returns it in a new buffer.
protected int	engineGenerateSecret(byte[] sharedSecret, int offset) Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset inclusive.
protected javax.crypto.SecretKey	engineGenerateSecret(java.lang.String algorithm) Creates the shared secret and returns it as a secret key object of the requested algorithm type.
protected void	engineInit(java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this key agreement with the given key, set of algorithm parameters, and source of randomness.
protected void	engineInit(java.security.Key key, java.security.SecureRandom random) Initializes this key agreement with the given key and source of randomness.

Methods inherited from class java.lang.Object

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

Constructor Detail

DHKeyAgreement

public DHKeyAgreement()

The constructor; creates a new instance of the DH key agreement algorithm.

Applications should never use this constructor, instead the key agreement algorithm should be requested from the appropriate JCA/JCE cryptographic service provider as follows: KeyAgreement.getInstance("DH", "IAIK").

FIPS 140-2:

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions)

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 key agreement with the given key, set of algorithm parameters, and source of randomness.

FIPS 140-2:

FIPS Service: Initialization

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• status output interface (exceptions)

Specified by:

engineInit in class javax.crypto.KeyAgreementSpi

Parameters:

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.

params - [FIPS 140-2 data input] the key agreement parameters

random - [FIPS 140-2 control input] the source of randomness

Throws:

java.security.InvalidKeyException - [FIPS 140-2 status output] if the given key is inappropriate for this key agreement, e.g., is of the wrong type or has an incompatible algorithm type.

java.security.InvalidAlgorithmParameterException - [FIPS 140-2 status output] if the given parameters are inappropriate for this key agreement.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineInit

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

Initializes this key agreement with the given key and source of randomness. The given key is required to contain all the algorithm parameters required for this key agreement.

If the key agreement algorithm requires random bytes, it gets them from the given source of randomness, random. However, if the underlying algorithm implementation does not require any random bytes, random is ignored.

FIPS 140-2:

FIPS Service: Initialization

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• status output interface (exceptions)

Specified by:

engineInit in class javax.crypto.KeyAgreementSpi

Parameters:

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.

random - [FIPS 140-2 control input] the source of randomness

Throws:

java.security.InvalidKeyException - [FIPS 140-2 status output] if the given key is inappropriate for this key agreement, e.g., is of the wrong type or has an incompatible algorithm type.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineDoPhase

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

Executes the next phase of this key agreement with the given key that was received from one of the other parties involved in this key agreement.

FIPS 140-2:

FIPS Service: Key Agreement (scheme/primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineDoPhase in class javax.crypto.KeyAgreementSpi

Parameters:

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the key for this phase. For example, in the case of Diffie-Hellman between 2 parties, this would be the other party's Diffie-Hellman public key.

lastPhase - [FIPS 140-2 control input] flag which indicates whether or not this is the last phase of this key agreement.

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the (intermediate) key resulting from this phase, or null if this phase does not yield a key

Throws:

java.security.InvalidKeyException - [FIPS 140-2 status output] if the given key is inappropriate for this phase.

java.lang.IllegalStateException - [FIPS 140-2 status output] if this key agreement has not been initialized.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineGenerateSecret

protected javax.crypto.SecretKey engineGenerateSecret(java.lang.String algorithm)
                                               throws java.lang.IllegalStateException,
                                                      java.security.NoSuchAlgorithmException,
                                                      java.security.InvalidKeyException

Creates the shared secret and returns it as a secret key object of the requested algorithm type.

This method resets this KeyAgreementSpi object, so that it can be reused for further key agreements. Unless this key agreement is reinitialized with one of the engineInit methods, the same private information and algorithm parameters will be used for subsequent key agreements.

FIPS 140-2:

FIPS Service: Key Agreement (scheme/primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineGenerateSecret in class javax.crypto.KeyAgreementSpi

Parameters:

algorithm - [FIPS 140-2 control input] the requested secret key algorithm

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the shared secret key

Throws:

java.lang.IllegalStateException - [FIPS 140-2 status output] if this key agreement has not been completed yet

java.security.NoSuchAlgorithmException - [FIPS 140-2 status output] if the requested secret key algorithm is not available

java.security.InvalidKeyException - [FIPS 140-2 status output] if the shared secret key material cannot be used to generate a secret key of the requested algorithm type (e.g., the key material is too short)

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineGenerateSecret

protected int engineGenerateSecret(byte[] sharedSecret,
                                   int offset)
                            throws java.lang.IllegalStateException,
                                   javax.crypto.ShortBufferException

Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset inclusive.

If the sharedSecret buffer is too small to hold the result, a ShortBufferException is thrown. In this case, this call should be repeated with a larger output buffer.

This method resets this KeyAgreementSpi object, so that it can be reused for further key agreements. Unless this key agreement is reinitialized with one of the engineInit methods, the same private information and algorithm parameters will be used for subsequent key agreements.

FIPS 140-2:

FIPS Service: Key Agreement (scheme/primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• data output interface (parameters, return value)
• status output interface (exceptions)

Specified by:

engineGenerateSecret in class javax.crypto.KeyAgreementSpi

Parameters:

sharedSecret - [FIPS 140-2 data output] [FIPS 140-2 CSP] the buffer for the shared secret

offset - [FIPS 140-2 data input] the offset in sharedSecret where the shared secret will be stored

Returns:

[FIPS 140-2 data output] the number of bytes placed into sharedSecret

Throws:

java.lang.IllegalStateException - [FIPS 140-2 status output] if this key agreement has not been completed yet

javax.crypto.ShortBufferException - [FIPS 140-2 status output] if the given output buffer is too small to hold the secret

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineGenerateSecret

protected byte[] engineGenerateSecret()
                               throws java.lang.IllegalStateException

Generates the shared secret and returns it in a new buffer.

This method resets this KeyAgreementSpi object, so that it can be reused for further key agreements. Unless this key agreement is reinitialized with one of the engineInit methods, the same private information and algorithm parameters will be used for subsequent key agreements.

FIPS 140-2:

FIPS Service: Key Agreement (scheme/primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineGenerateSecret in class javax.crypto.KeyAgreementSpi

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the new buffer with the shared secret

Throws:

java.lang.IllegalStateException - [FIPS 140-2 status output] if this key agreement has not been completed yet

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations