iaik.security.dh

Class DHKeyPairGenerator

java.lang.Object

java.security.KeyPairGeneratorSpi

java.security.KeyPairGenerator

iaik.security.dh.DHKeyPairGenerator

public class DHKeyPairGenerator
extends java.security.KeyPairGenerator

Key pair generator for DH keys to be used for Diffie Hellman key agreement.

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 (or more) 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 an entity itself), to create a shared secret, only known by them.

For creating a DH key pair necessary for performing a Diffie Hellman key agreement, a KeyPairGenerator has to be instantiated, properly initialized and directed to actually generate the keys by calling the generateKeyPair method. If the generator is not initialized by explicitly calling an initialize method, the modulus length per default is set to 1024 bits.

Generating DH keys using a modulus length of, e.g. 1024 bits (explicitly initialized), may be done by:

KeyPairGenerator key_gen = KeyPairGenerator.getIntance("DH");
 key_gen.initialize(1024, sec_random);
 KeyPair key_pair = key_gen.generateKeyPair();
 

The example above initializes the key pair generator algorithm-independently by only specifying the length of the modulus. For performing an algorithm-specific initialization, an explicit cast to DHKeyPairGenerator would be necessary, e.g.:

 DHKeyPairGenerator dh_key_gen = (DHKeyPairGenerator)key_gen;
 dh_key_gen.initialize(dh_param_spec, sec_random);

Guidelines on how to create key pairs using a KeyPairGenerator can be found in http://java.sun.com/products/JDK/1.1/docs/guide/security/CryptoSpec.html.

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:

KeyPairGenerator, KeyPair, DHPublicKey, DHPrivateKey, DHKeyFactory, DHKeyAgreement, DHParameterSpec

Constructor Summary

Constructors

Constructor and Description
DHKeyPairGenerator() The constructor; creates a new instance of the DH key pair generation algorithm.

Method Summary

Modifier and Type	Method and Description
java.security.KeyPair	generateKeyPair() Generates a key pair.
void	initialize(java.security.spec.AlgorithmParameterSpec param, java.security.SecureRandom random) Initializes the key pair generator using the specified parameter set and user-provided source of randomness.
void	initialize(int keysize) Initializes the key pair generator for a certain keysize, using the default parameter set.
void	initialize(int keysize, java.security.SecureRandom random) Initializes the key pair generator for a certain keysize, using the default parameter set and user-provided source of randomness.

Methods inherited from class java.security.KeyPairGenerator

genKeyPair, getAlgorithm, getInstance, getInstance, getInstance, getProvider, initialize

Methods inherited from class java.lang.Object

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

Constructor Detail

DHKeyPairGenerator

public DHKeyPairGenerator()

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

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

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)
• status output interface (exceptions)

Method Detail

initialize

public void initialize(int keysize)

Initializes the key pair generator for a certain keysize, using the default parameter set.

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)
• data input interface (parameters)
• status output interface (exceptions)

Overrides:

initialize in class java.security.KeyPairGenerator

Parameters:

keysize - [FIPS 140-2 data input] the keysize. This is an algorithm-specific metric, such as modulus length, specified in number of bits.

Throws:

java.security.InvalidParameterException - [FIPS 140-2 status output] if the keysize is not supported

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

initialize

public void initialize(int keysize,
                       java.security.SecureRandom random)

Initializes the key pair generator for a certain keysize, using the default parameter set and user-provided 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)

Overrides:

initialize in class java.security.KeyPairGenerator

Parameters:

keysize - [FIPS 140-2 data input] the keysize. This is an algorithm-specific metric, such as modulus length, specified in number of bits.

random - [FIPS 140-2 control input] the source of randomness for this generator.

Throws:

java.security.InvalidParameterException - [FIPS 140-2 status output] if the keysize is not supported

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

initialize

public void initialize(java.security.spec.AlgorithmParameterSpec param,
                       java.security.SecureRandom random)
                throws java.security.InvalidAlgorithmParameterException

Initializes the key pair generator using the specified parameter set and user-provided 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)

Overrides:

initialize in class java.security.KeyPairGenerator

Parameters:

param - [FIPS 140-2 data input] the parameter set used to generate the keys.

random - [FIPS 140-2 control input] the source of randomness for this generator.

Throws:

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

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

generateKeyPair

public java.security.KeyPair generateKeyPair()

Generates a key pair.

Unless an initialization method is called using a KeyPairGenerator interface, algorithm-specific defaults will be used. This will generate a new key pair every time it is called.

FIPS 140-2:

FIPS Service: Key Generation

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 crypto officer role and accesses the following FIPS 140-2 logical interfaces:

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

Overrides:

generateKeyPair in class java.security.KeyPairGenerator

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the newly generated KeyPair

Throws:

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