iaik.security.dsa

Class DSAKeyPairGenerator

java.lang.Object

java.security.KeyPairGeneratorSpi

java.security.KeyPairGenerator

iaik.security.dsa.DSAKeyPairGenerator

All Implemented Interfaces:

java.security.interfaces.DSAKeyPairGenerator

public class DSAKeyPairGenerator
extends java.security.KeyPairGenerator
implements java.security.interfaces.DSAKeyPairGenerator

Key pair generator for DSA keys as specified in FIPS PUB 186.

Valid length for the modulus is any multiple of 64 in the range of 512 to 1024.

This class contains precalculated public DSA parameters for modulus lengths of 512, 768, and 1024 bits. For other key lengths the parameters have to be calculated first, which is extremely slow (usually several minutes, depending on your luck and machine speed). However, when DSA parameters are available, key generation is very fast, therefore I recommend to stay with 512, 768, or 1024 bits.

To create a DSA key pair, 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 is set to 1024 bits.

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

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

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

 DSAKeyPairGenerator dsa_key_gen = (DSAKeyPairGenerator)key_gen;
 dsa_key_gen.initialize(dsa_params, sec_random);
 

Guidelines on how to create some key 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, DSAPublicKey, DSAPrivateKey, DSAKeyFactory, DSAParams

Constructor Summary

Constructors

Constructor and Description
DSAKeyPairGenerator() The constructor; creates a new instance of the DSA 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 params, java.security.SecureRandom random) Initializes this DSAKeyPairGenerator with given DSAParameterSpec and random seed.
void	initialize(java.security.interfaces.DSAParams params, java.security.SecureRandom random) Initializes this DSAKeyPairGenerator with given DSA parameters 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 modlen, boolean genParams, java.security.SecureRandom random) Initializes this DSAKeyPairGenerator for given modulus length with the user-provided source of randomness.
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

DSAKeyPairGenerator

public DSAKeyPairGenerator()

The constructor; creates a new instance of the DSA 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("DSA", "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

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

initialize

public void initialize(java.security.interfaces.DSAParams params,
                       java.security.SecureRandom random)
                throws java.security.InvalidParameterException

Initializes this DSAKeyPairGenerator with given DSA parameters 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)
• data input interface (parameters)
• status output interface (exceptions)

Specified by:

initialize in interface java.security.interfaces.DSAKeyPairGenerator

Parameters:

params - [FIPS 140-2 data input] the DSAParams representing prime p, sub-prime q, and base g

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

Throws:

java.security.InvalidParameterException - [FIPS 140-2 status output] if the given parameters to not match to DSAParams

initialize

public void initialize(int modlen,
                       boolean genParams,
                       java.security.SecureRandom random)
                throws java.security.InvalidParameterException

Initializes this DSAKeyPairGenerator for given modulus length with the user-provided source of randomness. This method initializes the generator either with precomputed DSA parameter values p, q and g (when genParams is set to false), or by generating new DSA parameter values (when genParams is set to true). Precomputed parameters are available for modulus length of either 512, 768, or 1024 bits.

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)

Specified by:

initialize in interface java.security.interfaces.DSAKeyPairGenerator

Parameters:

modlen - [FIPS 140-2 data input] the length of the modulus in bits (512, 768, or 1024)

genParams - [FIPS 140-2 control input] true for generating new parameters, false for using precomputed values for p, q and g

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

Throws:

java.security.InvalidParameterException - [FIPS 140-2 status output] if the given modulus length is not a multiple of 64 between 512 and 1024 when genParms = true; or the given modulus length is not 512, 768, or 1024 when when genParms = false

initialize

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

Initializes this DSAKeyPairGenerator with given DSAParameterSpec and random seed.

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:

params - [FIPS 140-2 data input] the DSAParamaterSpec representing p, q and g for initializing this generator

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 parameter specification is not a DSAParameterSpec

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