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: * *
All key pair generators share the concepts of a keysize and a * source of randomness. The keysize is interpreted differently for different * algorithms (e.g., in the case of the DSA algorithm, the keysize * corresponds to the length of the modulus). * There is an * {@link #initialize(int, java.security.SecureRandom) initialize} * method in this KeyPairGenerator class that takes these two universally * shared types of arguments. There is also one that takes just a * {@code keysize} argument, and uses the {@code SecureRandom} * implementation of the highest-priority installed provider as the source * of randomness. (If none of the installed providers supply an implementation * of {@code SecureRandom}, a system-provided source of randomness is * used.) * *
Since no other parameters are specified when you call the above * algorithm-independent {@code initialize} methods, it is up to the * provider what to do about the algorithm-specific parameters (if any) to be * associated with each of the keys. * *
If the algorithm is the DSA algorithm, and the keysize (modulus * size) is 512, 768, 1024, or 2048, then the Sun provider uses a set of * precomputed values for the {@code p}, {@code q}, and * {@code g} parameters. If the modulus size is not one of the above * values, the Sun provider creates a new set of parameters. Other * providers might have precomputed parameter sets for more than just the * modulus sizes mentioned above. Still others might not have a list of * precomputed parameters at all and instead always create new parameter sets. * *
For situations where a set of algorithm-specific parameters already * exists (e.g., so-called community parameters in DSA), there are two * {@link #initialize(java.security.spec.AlgorithmParameterSpec) * initialize} methods that have an {@code AlgorithmParameterSpec} * argument. One also has a {@code SecureRandom} argument, while * the other uses the {@code SecureRandom} * implementation of the highest-priority installed provider as the source * of randomness. (If none of the installed providers supply an implementation * of {@code SecureRandom}, a system-provided source of randomness is * used.) *
In case the client does not explicitly initialize the KeyPairGenerator * (via a call to an {@code initialize} method), each provider must * supply (and document) a default initialization. * For example, the Sun provider uses a default modulus size (keysize) * of 1024 bits. * *
Note that this class is abstract and extends from * {@code KeyPairGeneratorSpi} for historical reasons. * Application developers should only take notice of the methods defined in * this {@code 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. * *
Android provides the following KeyPairGenerator algorithms:
*
| Algorithm | *Supported API Levels | *
|---|---|
| DH | *1+ | *
| DSA | *1+ | *
| EC | *11+ | *
| RSA | *1+ | *
| XDH | *33+ | *
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 {@link Security#getProviders() Security.getProviders()} method.
*
* @implNote
* The JDK Reference Implementation additionally uses the
* {@code jdk.security.provider.preferred}
* {@link Security#getProperty(String) Security} property to determine
* the preferred provider order for the specified algorithm. This
* may be different than the order of providers returned by
* {@link Security#getProviders() Security.getProviders()}.
*
* @param algorithm 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.
*
* @return the new {@code KeyPairGenerator} object
*
* @throws NoSuchAlgorithmException if no {@code Provider} supports a
* {@code KeyPairGeneratorSpi} implementation for the
* specified algorithm
*
* @throws NullPointerException if {@code algorithm} is {@code null}
*
* @see Provider
*/
public static KeyPairGenerator getInstance(String algorithm)
throws NoSuchAlgorithmException {
Objects.requireNonNull(algorithm, "null algorithm name");
List 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 {@link Security#getProviders() Security.getProviders()} method.
*
* @param algorithm 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.
*
* @param provider the string name of the provider.
*
* @return the new {@code KeyPairGenerator} object
*
* @throws IllegalArgumentException if the provider name is {@code null}
* or empty
*
* @throws NoSuchAlgorithmException if a {@code KeyPairGeneratorSpi}
* implementation for the specified algorithm is not
* available from the specified provider
*
* @throws NoSuchProviderException if the specified provider is not
* registered in the security provider list
*
* @throws NullPointerException if {@code algorithm} is {@code null}
*
* @see Provider
*/
public static KeyPairGenerator getInstance(String algorithm,
String provider)
throws NoSuchAlgorithmException, NoSuchProviderException {
Objects.requireNonNull(algorithm, "null algorithm name");
// Android-added: Check for Bouncy Castle deprecation
Providers.checkBouncyCastleDeprecation(provider, "KeyPairGenerator", algorithm);
Instance instance = GetInstance.getInstance("KeyPairGenerator",
KeyPairGeneratorSpi.class, algorithm, provider);
return getInstance(instance, algorithm);
}
/**
* 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
* object is returned. Note that the specified Provider object
* does not have to be registered in the provider list.
*
* @param algorithm 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.
*
* @param provider the provider.
*
* @return the new {@code KeyPairGenerator} object
*
* @throws IllegalArgumentException if the specified provider is
* {@code null}
*
* @throws NoSuchAlgorithmException if a {@code KeyPairGeneratorSpi}
* implementation for the specified algorithm is not available
* from the specified {@code Provider} object
*
* @throws NullPointerException if {@code algorithm} is {@code null}
*
* @see Provider
*
* @since 1.4
*/
public static KeyPairGenerator getInstance(String algorithm,
Provider provider) throws NoSuchAlgorithmException {
Objects.requireNonNull(algorithm, "null algorithm name");
// Android-added: Check for Bouncy Castle deprecation
Providers.checkBouncyCastleDeprecation(provider, "KeyPairGenerator", algorithm);
Instance instance = GetInstance.getInstance("KeyPairGenerator",
KeyPairGeneratorSpi.class, algorithm, provider);
return getInstance(instance, algorithm);
}
/**
* Returns the provider of this key pair generator object.
*
* @return the provider of this key pair generator object
*/
public final Provider getProvider() {
disableFailover();
return this.provider;
}
void disableFailover() {
// empty, overridden in Delegate
}
/**
* Initializes the key pair generator for a certain keysize using
* a default parameter set and the {@code SecureRandom}
* implementation of the highest-priority installed provider as the source
* of randomness.
* (If none of the installed providers supply an implementation of
* {@code SecureRandom}, a system-provided source of randomness is
* used.)
*
* @param keysize the keysize. This is an
* algorithm-specific metric, such as modulus length, specified in
* number of bits.
*
* @exception InvalidParameterException if the {@code keysize} is not
* supported by this KeyPairGenerator object.
*/
public void initialize(int keysize) {
initialize(keysize, JCAUtil.getSecureRandom());
}
/**
* Initializes the key pair generator for a certain keysize with
* the given source of randomness (and a default parameter set).
*
* @param keysize the keysize. This is an
* algorithm-specific metric, such as modulus length, specified in
* number of bits.
* @param random the source of randomness.
*
* @exception InvalidParameterException if the {@code keysize} is not
* supported by this KeyPairGenerator object.
*
* @since 1.2
*/
public void initialize(int keysize, SecureRandom random) {
// This does nothing, because either
// 1. the implementation object returned by getInstance() is an
// instance of KeyPairGenerator which has its own
// initialize(keysize, random) method, so the application would
// be calling that method directly, or
// 2. the implementation returned by getInstance() is an instance
// of Delegate, in which case initialize(keysize, random) is
// overridden to call the corresponding SPI method.
// (This is a special case, because the API and SPI method have the
// same name.)
}
/**
* Initializes the key pair generator using the specified parameter
* set and the {@code SecureRandom}
* implementation of the highest-priority installed provider as the source
* of randomness.
* (If none of the installed providers supply an implementation of
* {@code 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
* {@link KeyPairGeneratorSpi#initialize(
* java.security.spec.AlgorithmParameterSpec,
* java.security.SecureRandom) initialize} method,
* passing it {@code 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 {@code initialize} method always throws an
* UnsupportedOperationException if it is not overridden by the provider.
*
* @param params the parameter set used to generate the keys.
*
* @exception InvalidAlgorithmParameterException if the given parameters
* are inappropriate for this key pair generator.
*
* @since 1.2
*/
public void initialize(AlgorithmParameterSpec params)
throws InvalidAlgorithmParameterException {
initialize(params, JCAUtil.getSecureRandom());
}
/**
* 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 {@link
* KeyPairGeneratorSpi#initialize(
* java.security.spec.AlgorithmParameterSpec,
* java.security.SecureRandom) initialize} method,
* passing it {@code params} and {@code random}.
* That {@code initialize}
* method always throws an
* UnsupportedOperationException if it is not overridden by the provider.
*
* @param params the parameter set used to generate the keys.
* @param random the source of randomness.
*
* @exception InvalidAlgorithmParameterException if the given parameters
* are inappropriate for this key pair generator.
*
* @since 1.2
*/
public void initialize(AlgorithmParameterSpec params,
SecureRandom random)
throws InvalidAlgorithmParameterException
{
// This does nothing, because either
// 1. the implementation object returned by getInstance() is an
// instance of KeyPairGenerator which has its own
// initialize(params, random) method, so the application would
// be calling that method directly, or
// 2. the implementation returned by getInstance() is an instance
// of Delegate, in which case initialize(params, random) is
// overridden to call the corresponding SPI method.
// (This is a special case, because the API and SPI method have the
// same name.)
}
/**
* 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
* {@link #generateKeyPair() generateKeyPair}.
*
* @return the generated key pair
*
* @since 1.2
*/
public final KeyPair genKeyPair() {
return 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
* {@link #genKeyPair() genKeyPair}.
*
* @return the generated key pair
*/
public KeyPair generateKeyPair() {
// This does nothing (except returning null), because either:
//
// 1. the implementation object returned by getInstance() is an
// instance of KeyPairGenerator which has its own implementation
// of generateKeyPair (overriding this one), so the application
// would be calling that method directly, or
//
// 2. the implementation returned by getInstance() is an instance
// of Delegate, in which case generateKeyPair is
// overridden to invoke the corresponding SPI method.
//
// (This is a special case, because in JDK 1.1.x the generateKeyPair
// method was used both as an API and a SPI method.)
return null;
}
/*
* The following class allows providers to extend from KeyPairGeneratorSpi
* rather than from KeyPairGenerator. It represents a KeyPairGenerator
* with an encapsulated, provider-supplied SPI object (of type
* KeyPairGeneratorSpi).
* If the provider implementation is an instance of KeyPairGeneratorSpi,
* the getInstance() methods above return an instance of this class, with
* the SPI object encapsulated.
*
* Note: All SPI methods from the original KeyPairGenerator class have been
* moved up the hierarchy into a new class (KeyPairGeneratorSpi), which has
* been interposed in the hierarchy between the API (KeyPairGenerator)
* and its original parent (Object).
*/
//
// error failover notes:
//
// . we failover if the implementation throws an error during init
// by retrying the init on other providers
//
// . we also failover if the init succeeded but the subsequent call
// to generateKeyPair() fails. In order for this to work, we need
// to remember the parameters to the last successful call to init
// and initialize() the next spi using them.
//
// . although not specified, KeyPairGenerators could be thread safe,
// so we make sure we do not interfere with that
//
// . failover is not available, if:
// . getInstance(algorithm, provider) was used
// . a provider extends KeyPairGenerator rather than
// KeyPairGeneratorSpi (JDK 1.1 style)
// . once getProvider() is called
//
private static final class Delegate extends KeyPairGenerator {
// The provider implementation (delegate)
private volatile KeyPairGeneratorSpi spi;
private final Object lock = new Object();
private Iterator