com.entrust.toolkit.security.crypto.ec

Class EcKeyPairGenerator

java.lang.Object

java.security.KeyPairGeneratorSpi

com.entrust.toolkit.security.crypto.ec.EcKeyPairGenerator

public final class EcKeyPairGenerator
extends java.security.KeyPairGeneratorSpi

A software based implementation of the Elliptic Curve (EC) key pair generation algorithm.

An EC key generator is used to generate an EC key pair, which consists of an EC public key and an EC private key. This key pair can then be used with EC-based cryptographic algorithms (ex: ECDSA digital signatures - EcdsaSignature).

This implementation is based on the EC key pair generation routine defined in ANSI X9.62-2005. It produces EC keys that are JCA compliant; this means the EC public key produced implements the java.security.interfaces.ECPublicKey interface, and the EC private key produced implements the java.security.interfaces.ECPrivateKey interface. The EC keys generated are represented using the following Entrust classes: EcPublicKey, EcPrivateKey.

Before this EC key pair generator can be used to generate EC keys, it must be initialized with a set of EC domain parameters. EC domain parameters define (among other things) the strength of the EC key pair. During initialization, the EC domain parameters must be selected. This can be done by providing the actual EC domain parameters or selecting a pre-defined named set of EC domain parameters, or simply requesting a specific key strength in bits. This implementation accepts algorithm parameters in the following format:

• Specified, named, or implicitCA EC domain parameters (Entrust EC format); instance of EcParameterSpecWithName.
• Specified EC domain parameters (Sun JCA format); instance of java.security.spec.ECParameterSpec.
• Specified EC domain parameters (Old Entrust EC format); instances of ECParameters.
• Named EC domain parameters (Sun JCA format); instances of java.security.spec.ECGenParameterSpec.

Before the EC domain parameters are used, they are first validated. For additional details on the EC domain parameter validation routine, refer to EcParameterFactory . Additionally, a check is done to ensure that the EC domain parameters specify a key size of at least 160-bits (indicates the EC field size); anything smaller is deemed too weak.

When named EC domain parameters are provided, the actual EC domain parameters values are retrieved from a pre-defined set of known supported named EC domains. When named EC domain parameters are not provided, but the key size is provided, the actual EC domain parameters values are retrieved from a pre-defined set of known supported named EC domains. When the key generator is not initialized with a set of EC domain parameters and a key size is also not provided, a default set of EC domain parameters will be used during key generation. Refer to EcParameterFactory for details on the EC domain parameters, including a table of supported named EC domains that identifies default domains at each key size and an overall default. For EC keys, the key size refers to the EC field size.

This implementation supports curves in F_p (prime curves). For a list of the named curves that are supported, refer to EcParameterFactory. Point compression is not supported.

An instance of this algorithm can be obtained using the Java Cryptography Architecture (JCA), by requesting an 'EC' key pair generator from the Entrust cryptographic service provider. This can be done using the following call:

KeyPairGenerator.getInstance("EC", "Entrust");

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

Since:

7.2 SP2

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
static java.security.interfaces.ECPublicKey	calculatePublicKey(java.security.interfaces.ECPrivateKey privateKey) Determines the EC public key that corresponds to a given EC private key.
java.security.KeyPair	generateKeyPair() Generates a key pair.
void	initialize(java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes the key pair generator using the specified parameter set and 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.lang.Object

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

Constructor Detail

EcKeyPairGenerator

public EcKeyPairGenerator()

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

FIPS 140-2:

FIPS Service: Modify Object

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

calculatePublicKey

public static java.security.interfaces.ECPublicKey calculatePublicKey(java.security.interfaces.ECPrivateKey privateKey)
                                                               throws UnsupportedECDomainException

Determines the EC public key that corresponds to a given EC private key.

The EC public key that is returned and the EC private key provided form a matching key pair.

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

Parameters:

privateKey - [FIPS 140-2 data input] [FIPS 140-2 CSP] an EC private key

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the matching EC public key

Throws:

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

UnsupportedECDomainException - [FIPS 140-2 status output] if the EC domain parameters in the private key are not supported

Since:

8.0 patch

initialize

public void initialize(java.security.spec.AlgorithmParameterSpec params,
                       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.KeyPairGeneratorSpi

Parameters:

params - [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

initialize

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

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)

Specified by:

initialize in class java.security.KeyPairGeneratorSpi

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

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)

Specified by:

generateKeyPair in class java.security.KeyPairGeneratorSpi

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