Top Description Inners Fields Constructors Methods
java.security

public abstract Class KeyPairGenerator

extends KeyPairGeneratorSpi
Class Inheritance
Known Direct Subclasses
java.security.KeyPairGenerator.Delegate, sun.security.provider.DSAKeyPairGenerator
Imports
java.util.*, java.security.spec.AlgorithmParameterSpec, java.security.Provider.Service, sun.security.jca.*, .GetInstance.Instance, sun.security.util.Debug

The KeyPairGenerator class is used to generate pairs of public and private keys. Key pair generators are constructed using the getInstance factory methods (static methods that return instances of a given class).

A Key pair generator for a particular algorithm creates a public/private key pair that can be used with this algorithm. It also associates algorithm-specific parameters with each of the generated keys.

There are two ways to generate a key pair: in an algorithm-independent manner, and in an algorithm-specific manner. The only difference between the two is the initialization of the object:

In case the client does not explicitly initialize the KeyPairGenerator (via a call to an initialize method), each provider must supply (and document) a default initialization. See the Keysize Restriction sections of the JDK Providers document for information on the KeyPairGenerator defaults used by JDK providers. However, note that defaults may vary across different providers. Additionally, the default value for a provider may change in a future version. Therefore, it is recommended to explicitly initialize the KeyPairGenerator instead of relying on provider-specific defaults.

Note that this class is abstract and extends from KeyPairGeneratorSpi for historical reasons. Application developers should only take notice of the methods defined in this KeyPairGenerator class; all the methods in the superclass are intended for cryptographic service providers who wish to supply their own implementations of key pair generators.

Every implementation of the Java platform is required to support the following standard KeyPairGenerator algorithms and keysizes in parentheses:

These algorithms are described in the KeyPairGenerator section of the Java Security Standard Algorithm Names Specification. Consult the release documentation for your implementation to see if any other algorithms are supported.
Author
Benjamin Renaud
Since
1.1
See Also
java.security.spec.AlgorithmParameterSpec

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class

Field Summary

Modifier and TypeField and Description
private final String
private static final Debug
pack-priv Provider
private static final boolean

Constructor Summary

AccessConstructor and Description
protected
KeyPairGenerator(String
the standard string name of the algorithm. See the KeyPairGenerator section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.
algorithm
)

Creates a KeyPairGenerator object for the specified algorithm.

Method Summary

Modifier and TypeMethod and Description
pack-priv void
public KeyPair

Returns:

the generated key pair
generateKeyPair
()

Implements abstract java.security.KeyPairGeneratorSpi.generateKeyPair.

Generates a key pair.

public final KeyPair

Returns:

the generated key pair
genKeyPair
()

Generates a key pair.

public String

Returns:

the standard string name of the algorithm.
getAlgorithm
()

Returns the standard name of the algorithm for this key pair generator.

private static KeyPairGenerator
getInstance(GetInstance.Instance instance, String algorithm)

public static KeyPairGenerator

Returns:

the new KeyPairGenerator object
getInstance
(String
the standard string name of the algorithm. See the KeyPairGenerator section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.
algorithm
)

Returns a KeyPairGenerator object that generates public/private key pairs for the specified algorithm.

public static KeyPairGenerator

Returns:

the new KeyPairGenerator object
getInstance
(String
the standard string name of the algorithm. See the KeyPairGenerator section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.
algorithm
,
String
the string name of the provider.
provider
)

Returns a KeyPairGenerator object that generates public/private key pairs for the specified algorithm.

public static KeyPairGenerator

Returns:

the new KeyPairGenerator object
getInstance
(String
the standard string name of the algorithm. See the KeyPairGenerator section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.
algorithm
,
Provider
the provider.
provider
)

Returns a KeyPairGenerator object that generates public/private key pairs for the specified algorithm.

public final Provider

Returns:

the provider of this key pair generator object
getProvider
()

Returns the provider of this key pair generator object.

public void
initialize(int
the keysize. This is an algorithm-specific metric, such as modulus length, specified in number of bits.
keysize
)

Initializes the key pair generator for a certain keysize using a default parameter set and the SecureRandom implementation of the highest-priority installed provider as the source of randomness.

public void
initialize(int
the keysize. This is an algorithm-specific metric, such as modulus length, specified in number of bits.
keysize
,
SecureRandom
the source of randomness.
random
)

Implements abstract java.security.KeyPairGeneratorSpi.initialize.

Initializes the key pair generator for a certain keysize with the given source of randomness (and a default parameter set).

public void
initialize(AlgorithmParameterSpec
the parameter set used to generate the keys.
params
)

Initializes the key pair generator using the specified parameter set and the SecureRandom implementation of the highest-priority installed provider as the source of randomness.

public void
initialize(AlgorithmParameterSpec
the parameter set used to generate the keys.
params
,
SecureRandom
the source of randomness.
random
)

Overrides java.security.KeyPairGeneratorSpi.initialize.

Initializes the key pair generator with the given parameter set and source of randomness.

Field Detail

algorithmback to summary
private final String algorithm
pdebugback to summary
private static final Debug pdebug
providerback to summary
pack-priv Provider provider
skipDebugback to summary
private static final boolean skipDebug

Constructor Detail

KeyPairGeneratorback to summary
protected KeyPairGenerator(String algorithm)

Creates a KeyPairGenerator object for the specified algorithm.

Parameters
algorithm:String

the standard string name of the algorithm. See the KeyPairGenerator section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.

Method Detail

disableFailoverback to summary
pack-priv void disableFailover()
generateKeyPairback to summary
public KeyPair generateKeyPair()

Implements abstract java.security.KeyPairGeneratorSpi.generateKeyPair.

Generates a key pair.

If this KeyPairGenerator has not been initialized explicitly, provider-specific defaults will be used for the size and other (algorithm-specific) values of the generated keys.

This will generate a new key pair every time it is called.

This method is functionally equivalent to genKeyPair.

Returns:KeyPair

the generated key pair

genKeyPairback to summary
public final KeyPair genKeyPair()

Generates a key pair.

If this KeyPairGenerator has not been initialized explicitly, provider-specific defaults will be used for the size and other (algorithm-specific) values of the generated keys.

This will generate a new key pair every time it is called.

This method is functionally equivalent to generateKeyPair.

Returns:KeyPair

the generated key pair

Since
1.2
getAlgorithmback to summary
public String getAlgorithm()

Returns the standard name of the algorithm for this key pair generator. See the KeyPairGenerator section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.

Returns:String

the standard string name of the algorithm.

getInstanceback to summary
private static KeyPairGenerator getInstance(GetInstance.Instance instance, String algorithm)
getInstanceback to summary
public static KeyPairGenerator getInstance(String algorithm) throws NoSuchAlgorithmException

Returns a KeyPairGenerator object that generates public/private key pairs for the specified algorithm.

This method traverses the list of registered security Providers, starting with the most preferred Provider. A new KeyPairGenerator object encapsulating the KeyPairGeneratorSpi implementation from the first provider that supports the specified algorithm is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Implementation Note

The JDK Reference Implementation additionally uses the jdk.security.provider.preferred Security property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned by Security.getProviders().

Parameters
algorithm:String

the standard string name of the algorithm. See the KeyPairGenerator section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.

Returns:KeyPairGenerator

the new KeyPairGenerator object

Exceptions
NoSuchAlgorithmException:
if no Provider supports a KeyPairGeneratorSpi implementation for the specified algorithm
NullPointerException:
if algorithm is null
See Also
Provider
getInstanceback to summary
public static KeyPairGenerator getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException

Returns a KeyPairGenerator object that generates public/private key pairs for the specified algorithm.

A new KeyPairGenerator object encapsulating the KeyPairGeneratorSpi implementation from the specified provider is returned. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters
algorithm:String

the standard string name of the algorithm. See the KeyPairGenerator section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.

provider:String

the string name of the provider.

Returns:KeyPairGenerator

the new KeyPairGenerator object

Exceptions
NoSuchAlgorithmException:
if a KeyPairGeneratorSpi implementation for the specified algorithm is not available from the specified provider
NoSuchProviderException:
if the specified provider is not registered in the security provider list
IllegalArgumentException:
if the provider name is null or empty
NullPointerException:
if algorithm is null
See Also
Provider
getInstanceback to summary
public static KeyPairGenerator getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException

Returns a KeyPairGenerator object that generates public/private key pairs for the specified algorithm.

A new KeyPairGenerator object encapsulating the KeyPairGeneratorSpi implementation from the specified provider is returned. Note that the specified provider does not have to be registered in the provider list.

Parameters
algorithm:String

the standard string name of the algorithm. See the KeyPairGenerator section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.

provider:Provider

the provider.

Returns:KeyPairGenerator

the new KeyPairGenerator object

Exceptions
NoSuchAlgorithmException:
if a KeyPairGeneratorSpi implementation for the specified algorithm is not available from the specified Provider object
IllegalArgumentException:
if the specified provider is null
NullPointerException:
if algorithm is null
Since
1.4
See Also
Provider
getProviderback to summary
public final Provider getProvider()

Returns the provider of this key pair generator object.

Returns:Provider

the provider of this key pair generator object

initializeback to summary
public void initialize(int keysize)

Initializes the key pair generator for a certain keysize using a default parameter set and the SecureRandom implementation of the highest-priority installed provider as the source of randomness. (If none of the installed providers supply an implementation of SecureRandom, a system-provided source of randomness is used.)

Parameters
keysize:int

the keysize. This is an algorithm-specific metric, such as modulus length, specified in number of bits.

Exceptions
InvalidParameterException:
if the keysize is not supported by this KeyPairGenerator object.
initializeback to summary
public void initialize(int keysize, SecureRandom random)

Implements abstract java.security.KeyPairGeneratorSpi.initialize.

Initializes the key pair generator for a certain keysize with the given source of randomness (and a default parameter set).

Parameters
keysize:int

the keysize. This is an algorithm-specific metric, such as modulus length, specified in number of bits.

random:SecureRandom

the source of randomness.

Exceptions
InvalidParameterException:
if the keysize is not supported by this KeyPairGenerator object.
Since
1.2
initializeback to summary
public void initialize(AlgorithmParameterSpec params) throws InvalidAlgorithmParameterException

Initializes the key pair generator using the specified parameter set and the SecureRandom implementation of the highest-priority installed provider as the source of randomness. (If none of the installed providers supply an implementation of SecureRandom, a system-provided source of randomness is used.)

This concrete method has been added to this previously-defined abstract class. This method calls the KeyPairGeneratorSpi initialize method, passing it params and a source of randomness (obtained from the highest-priority installed provider or system-provided if none of the installed providers supply one). That initialize method always throws an UnsupportedOperationException if it is not overridden by the provider.

Parameters
params:AlgorithmParameterSpec

the parameter set used to generate the keys.

Exceptions
InvalidAlgorithmParameterException:
if the given parameters are inappropriate for this key pair generator.
Since
1.2
initializeback to summary
public void initialize(AlgorithmParameterSpec params, SecureRandom random) throws InvalidAlgorithmParameterException

Overrides java.security.KeyPairGeneratorSpi.initialize.

Initializes the key pair generator with the given parameter set and source of randomness.

This concrete method has been added to this previously-defined abstract class. This method calls the KeyPairGeneratorSpi initialize method, passing it params and random. That initialize method always throws an UnsupportedOperationException if it is not overridden by the provider.

Parameters
params:AlgorithmParameterSpec

the parameter set used to generate the keys.

random:SecureRandom

the source of randomness.

Exceptions
InvalidAlgorithmParameterException:
if the given parameters are inappropriate for this key pair generator.
Since
1.2
java.security back to summary

private final Class KeyPairGenerator.Delegate

extends KeyPairGenerator
Class Inheritance

Field Summary

Modifier and TypeField and Description
private static final int
private static final int
private static final int
private int
private AlgorithmParameterSpec
private SecureRandom
private int
private final Object
private Iterator<Provider.Service>
private volatile KeyPairGeneratorSpi
Inherited from java.security.KeyPairGenerator:
provider

Constructor Summary

AccessConstructor and Description
pack-priv
pack-priv
Delegate(GetInstance.Instance instance, Iterator<Provider.Service> serviceIterator, String algorithm)

Method Summary

Modifier and TypeMethod and Description
pack-priv void
public KeyPair
public void
initialize(int
the keysize. This is an algorithm-specific metric, such as modulus length, specified in number of bits.
keysize
,
SecureRandom
the source of randomness.
random
)

Overrides java.security.KeyPairGenerator.initialize.

Initializes the key pair generator for a certain keysize with the given source of randomness (and a default parameter set).

public void
initialize(AlgorithmParameterSpec
the parameter set used to generate the keys.
params
,
SecureRandom
the source of randomness.
random
)

Overrides java.security.KeyPairGenerator.initialize.

Initializes the key pair generator with the given parameter set and source of randomness.

private KeyPairGeneratorSpi
nextSpi(KeyPairGeneratorSpi oldSpi, boolean reinit)

Update the active spi of this class and return the next implementation for failover.

Inherited from java.security.KeyPairGenerator:
genKeyPairgetAlgorithmgetInstancegetInstancegetInstancegetProviderinitializeinitialize

Field Detail

I_NONEback to summary
private static final int I_NONE
I_PARAMSback to summary
private static final int I_PARAMS
I_SIZEback to summary
private static final int I_SIZE
initKeySizeback to summary
private int initKeySize
initParamsback to summary
private AlgorithmParameterSpec initParams
initRandomback to summary
private SecureRandom initRandom
initTypeback to summary
private int initType
lockback to summary
private final Object lock
serviceIteratorback to summary
private Iterator<Provider.Service> serviceIterator
spiback to summary
private volatile KeyPairGeneratorSpi spi

Constructor Detail

Delegateback to summary
pack-priv Delegate(KeyPairGeneratorSpi spi, String algorithm)
Delegateback to summary
pack-priv Delegate(GetInstance.Instance instance, Iterator<Provider.Service> serviceIterator, String algorithm)

Method Detail

disableFailoverback to summary
pack-priv void disableFailover()

Overrides java.security.KeyPairGenerator.disableFailover.

generateKeyPairback to summary
public KeyPair generateKeyPair()

Overrides java.security.KeyPairGenerator.generateKeyPair.

Doc from java.security.KeyPairGenerator.generateKeyPair.

Generates a key pair.

If this KeyPairGenerator has not been initialized explicitly, provider-specific defaults will be used for the size and other (algorithm-specific) values of the generated keys.

This will generate a new key pair every time it is called.

This method is functionally equivalent to genKeyPair.

Returns:KeyPair

the generated key pair

initializeback to summary
public void initialize(int keysize, SecureRandom random)

Overrides java.security.KeyPairGenerator.initialize.

Doc from java.security.KeyPairGenerator.initialize.

Initializes the key pair generator for a certain keysize with the given source of randomness (and a default parameter set).

Parameters
keysize:int

the keysize. This is an algorithm-specific metric, such as modulus length, specified in number of bits.

random:SecureRandom

the source of randomness.

initializeback to summary
public void initialize(AlgorithmParameterSpec params, SecureRandom random) throws InvalidAlgorithmParameterException

Overrides java.security.KeyPairGenerator.initialize.

Doc from java.security.KeyPairGenerator.initialize.

Initializes the key pair generator with the given parameter set and source of randomness.

This concrete method has been added to this previously-defined abstract class. This method calls the KeyPairGeneratorSpi initialize method, passing it params and random. That initialize method always throws an UnsupportedOperationException if it is not overridden by the provider.

Parameters
params:AlgorithmParameterSpec

the parameter set used to generate the keys.

random:SecureRandom

the source of randomness.

Exceptions
InvalidAlgorithmParameterException:
if the given parameters are inappropriate for this key pair generator.
nextSpiback to summary
private KeyPairGeneratorSpi nextSpi(KeyPairGeneratorSpi oldSpi, boolean reinit)

Update the active spi of this class and return the next implementation for failover. If no more implementations are available, this method returns null. However, the active spi of this class is never set to null.