3909N/A * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The KeyPairGenerator class is used to generate pairs of 0N/A * public and private keys. Key pair generators are constructed using the 0N/A * <code>getInstance</code> factory methods (static methods that 0N/A * return instances of a given class). 0N/A * key pair that can be used with this algorithm. It also associates 0N/A * algorithm-specific parameters with each of the generated keys. 0N/A * <p>There are two ways to generate a key pair: in an algorithm-independent 0N/A * manner, and in an algorithm-specific manner. 0N/A * The only difference between the two is the initialization of the object: 0N/A * <li><b>Algorithm-Independent Initialization</b> 0N/A * <p>All key pair generators share the concepts of a keysize and a 0N/A * source of randomness. The keysize is interpreted differently for different 0N/A * algorithms (e.g., in the case of the <i>DSA</i> algorithm, the keysize 0N/A * corresponds to the length of the modulus). 0N/A * {@link #initialize(int, java.security.SecureRandom) initialize} 0N/A * method in this KeyPairGenerator class that takes these two universally 0N/A * shared types of arguments. There is also one that takes just a 0N/A * <code>keysize</code> argument, and uses the <code>SecureRandom</code> 0N/A * implementation of the highest-priority installed provider as the source 0N/A * of randomness. (If none of the installed providers supply an implementation 0N/A * of <code>SecureRandom</code>, a system-provided source of randomness is 0N/A * <p>Since no other parameters are specified when you call the above 0N/A * algorithm-independent <code>initialize</code> methods, it is up to the 0N/A * provider what to do about the algorithm-specific parameters (if any) to be 0N/A * associated with each of the keys. 0N/A * <p>If the algorithm is the <i>DSA</i> algorithm, and the keysize (modulus 0N/A * size) is 512, 768, or 1024, then the <i>Sun</i> provider uses a set of 0N/A * precomputed values for the <code>p</code>, <code>q</code>, and 0N/A * <code>g</code> parameters. If the modulus size is not one of the above 0N/A * values, the <i>Sun</i> provider creates a new set of parameters. Other 0N/A * providers might have precomputed parameter sets for more than just the 0N/A * three modulus sizes mentioned above. Still others might not have a list of 0N/A * precomputed parameters at all and instead always create new parameter sets. 0N/A * <li><b>Algorithm-Specific Initialization</b> 0N/A * <p>For situations where a set of algorithm-specific parameters already 0N/A * exists (e.g., so-called <i>community parameters</i> in DSA), there are two 0N/A * {@link #initialize(java.security.spec.AlgorithmParameterSpec) 0N/A * initialize} methods that have an <code>AlgorithmParameterSpec</code> 0N/A * argument. One also has a <code>SecureRandom</code> argument, while the 0N/A * the other uses the <code>SecureRandom</code> 0N/A * implementation of the highest-priority installed provider as the source 0N/A * of randomness. (If none of the installed providers supply an implementation 0N/A * of <code>SecureRandom</code>, a system-provided source of randomness is 0N/A * <p>In case the client does not explicitly initialize the KeyPairGenerator 0N/A * (via a call to an <code>initialize</code> method), each provider must 0N/A * supply (and document) a default initialization. 0N/A * For example, the <i>Sun</i> provider uses a default modulus size (keysize) 0N/A * <p>Note that this class is abstract and extends from 0N/A * <code>KeyPairGeneratorSpi</code> for historical reasons. 0N/A * Application developers should only take notice of the methods defined in 0N/A * this <code>KeyPairGenerator</code> class; all the methods in 0N/A * the superclass are intended for cryptographic service providers who wish to 0N/A * supply their own implementations of key pair generators. 3465N/A * <p> Every implementation of the Java platform is required to support the 3465N/A * following standard <code>KeyPairGenerator</code> algorithms and keysizes in 3465N/A * <li><tt>DiffieHellman</tt> (1024)</li> 3465N/A * <li><tt>DSA</tt> (1024)</li> 3465N/A * <li><tt>RSA</tt> (1024, 2048)</li> 3465N/A * These algorithms are described in the <a href= 3465N/A * KeyPairGenerator section</a> of the 3465N/A * Java Cryptography Architecture Standard Algorithm Name Documentation. 3465N/A * Consult the release documentation for your implementation to see if any 3465N/A * other algorithms are supported. 0N/A * @author Benjamin Renaud 0N/A * @see java.security.spec.AlgorithmParameterSpec 0N/A * Creates a KeyPairGenerator object for the specified algorithm. 0N/A * @param algorithm the standard string name of the algorithm. 3465N/A * See the KeyPairGenerator section in the <a href= 3465N/A * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 0N/A * for information about standard algorithm names. 0N/A * Returns the standard name of the algorithm for this key pair generator. 3465N/A * See the KeyPairGenerator section in the <a href= 3465N/A * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 0N/A * for information about standard algorithm names. 0N/A * @return the standard string name of the algorithm. 0N/A * key pairs for the specified algorithm. 0N/A * <p> This method traverses the list of registered security Providers, 0N/A * starting with the most preferred Provider. 0N/A * A new KeyPairGenerator object encapsulating the 0N/A * KeyPairGeneratorSpi implementation from the first 0N/A * Provider that supports the specified algorithm is returned. 0N/A * <p> Note that the list of registered providers may be retrieved via 0N/A * the {@link Security#getProviders() Security.getProviders()} method. 0N/A * @param algorithm the standard string name of the algorithm. 3465N/A * See the KeyPairGenerator section in the <a href= 3465N/A * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 0N/A * for information about standard algorithm names. 0N/A * @return the new KeyPairGenerator object. 0N/A * @exception NoSuchAlgorithmException if no Provider supports a 0N/A * KeyPairGeneratorSpi implementation for the 0N/A * specified algorithm. 0N/A // find a working Spi or KeyPairGenerator subclass 0N/A * key pairs for the specified algorithm. 0N/A * <p> A new KeyPairGenerator object encapsulating the 0N/A * KeyPairGeneratorSpi implementation from the specified provider 0N/A * is returned. The specified provider must be registered 0N/A * in the security provider list. 0N/A * <p> Note that the list of registered providers may be retrieved via 0N/A * the {@link Security#getProviders() Security.getProviders()} method. 0N/A * @param algorithm the standard string name of the algorithm. 3465N/A * See the KeyPairGenerator section in the <a href= 3465N/A * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 0N/A * for information about standard algorithm names. 0N/A * @param provider the string name of the provider. 0N/A * @return the new KeyPairGenerator object. 0N/A * @exception NoSuchAlgorithmException if a KeyPairGeneratorSpi 0N/A * implementation for the specified algorithm is not 0N/A * available from the specified provider. 0N/A * @exception NoSuchProviderException if the specified provider is not 0N/A * registered in the security provider list. 0N/A * @exception IllegalArgumentException if the provider name is null 0N/A * key pairs for the specified algorithm. 0N/A * <p> A new KeyPairGenerator object encapsulating the 0N/A * KeyPairGeneratorSpi implementation from the specified Provider 0N/A * object is returned. Note that the specified Provider object 0N/A * does not have to be registered in the provider list. 0N/A * @param algorithm the standard string name of the algorithm. 3465N/A * See the KeyPairGenerator section in the <a href= 3465N/A * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 0N/A * for information about standard algorithm names. 0N/A * @param provider the provider. 0N/A * @return the new KeyPairGenerator object. 0N/A * @exception NoSuchAlgorithmException if a KeyPairGeneratorSpi 0N/A * implementation for the specified algorithm is not available 0N/A * from the specified Provider object. 0N/A * @exception IllegalArgumentException if the specified provider is null. 0N/A * Returns the provider of this key pair generator object. 0N/A * @return the provider of this key pair generator object 0N/A // empty, overridden in Delegate 0N/A * Initializes the key pair generator for a certain keysize using 0N/A * a default parameter set and the <code>SecureRandom</code> 0N/A * implementation of the highest-priority installed provider as the source 0N/A * (If none of the installed providers supply an implementation of 0N/A * <code>SecureRandom</code>, a system-provided source of randomness is 0N/A * @param keysize the keysize. This is an 0N/A * algorithm-specific metric, such as modulus length, specified in 0N/A * @exception InvalidParameterException if the <code>keysize</code> is not 0N/A * supported by this KeyPairGenerator object. 0N/A * Initializes the key pair generator for a certain keysize with 0N/A * the given source of randomness (and a default parameter set). 0N/A * @param keysize the keysize. This is an 0N/A * algorithm-specific metric, such as modulus length, specified in 0N/A * @param random the source of randomness. 0N/A * @exception InvalidParameterException if the <code>keysize</code> is not 0N/A * supported by this KeyPairGenerator object. 0N/A // This does nothing, because either 0N/A // 1. the implementation object returned by getInstance() is an 0N/A // instance of KeyPairGenerator which has its own 0N/A // initialize(keysize, random) method, so the application would 0N/A // be calling that method directly, or 0N/A // 2. the implementation returned by getInstance() is an instance 0N/A // of Delegate, in which case initialize(keysize, random) is 0N/A // overridden to call the corresponding SPI method. 0N/A // (This is a special case, because the API and SPI method have the 0N/A * Initializes the key pair generator using the specified parameter 0N/A * set and the <code>SecureRandom</code> 0N/A * implementation of the highest-priority installed provider as the source 0N/A * (If none of the installed providers supply an implementation of 0N/A * <code>SecureRandom</code>, a system-provided source of randomness is 0N/A * <p>This concrete method has been added to this previously-defined 0N/A * This method calls the KeyPairGeneratorSpi 0N/A * {@link KeyPairGeneratorSpi#initialize( 0N/A * java.security.spec.AlgorithmParameterSpec, 0N/A * java.security.SecureRandom) initialize} method, 0N/A * passing it <code>params</code> and a source of randomness (obtained 0N/A * from the highest-priority installed provider or system-provided if none 0N/A * of the installed providers supply one). 0N/A * That <code>initialize</code> method always throws an 0N/A * UnsupportedOperationException if it is not overridden by the provider. 0N/A * @param params the parameter set used to generate the keys. 0N/A * @exception InvalidAlgorithmParameterException if the given parameters 0N/A * are inappropriate for this key pair generator. 0N/A * Initializes the key pair generator with the given parameter 0N/A * set and source of randomness. 0N/A * <p>This concrete method has been added to this previously-defined 0N/A * This method calls the KeyPairGeneratorSpi {@link 0N/A * KeyPairGeneratorSpi#initialize( 0N/A * java.security.spec.AlgorithmParameterSpec, 0N/A * java.security.SecureRandom) initialize} method, 0N/A * passing it <code>params</code> and <code>random</code>. 0N/A * That <code>initialize</code> 0N/A * method always throws an 0N/A * UnsupportedOperationException if it is not overridden by the provider. 0N/A * @param params the parameter set used to generate the keys. 0N/A * @param random the source of randomness. 0N/A * @exception InvalidAlgorithmParameterException if the given parameters 0N/A * are inappropriate for this key pair generator. 0N/A // This does nothing, because either 0N/A // 1. the implementation object returned by getInstance() is an 0N/A // instance of KeyPairGenerator which has its own 0N/A // initialize(params, random) method, so the application would 0N/A // be calling that method directly, or 0N/A // 2. the implementation returned by getInstance() is an instance 0N/A // of Delegate, in which case initialize(params, random) is 0N/A // overridden to call the corresponding SPI method. 0N/A // (This is a special case, because the API and SPI method have the 0N/A * Generates a key pair. 0N/A * <p>If this KeyPairGenerator has not been initialized explicitly, 0N/A * provider-specific defaults will be used for the size and other 0N/A * (algorithm-specific) values of the generated keys. 0N/A * <p>This will generate a new key pair every time it is called. 0N/A * <p>This method is functionally equivalent to 0N/A * {@link #generateKeyPair() generateKeyPair}. 0N/A * @return the generated key pair 0N/A * Generates a key pair. 0N/A * <p>If this KeyPairGenerator has not been initialized explicitly, 0N/A * provider-specific defaults will be used for the size and other 0N/A * (algorithm-specific) values of the generated keys. 0N/A * <p>This will generate a new key pair every time it is called. 0N/A * <p>This method is functionally equivalent to 0N/A * {@link #genKeyPair() genKeyPair}. 0N/A * @return the generated key pair 0N/A // This does nothing (except returning null), because either: 0N/A // 1. the implementation object returned by getInstance() is an 0N/A // instance of KeyPairGenerator which has its own implementation 0N/A // of generateKeyPair (overriding this one), so the application 0N/A // would be calling that method directly, or 0N/A // 2. the implementation returned by getInstance() is an instance 0N/A // of Delegate, in which case generateKeyPair is 0N/A // overridden to invoke the corresponding SPI method. 0N/A // (This is a special case, because in JDK 1.1.x the generateKeyPair 0N/A // method was used both as an API and a SPI method.) 0N/A * The following class allows providers to extend from KeyPairGeneratorSpi 0N/A * rather than from KeyPairGenerator. It represents a KeyPairGenerator 0N/A * with an encapsulated, provider-supplied SPI object (of type 0N/A * KeyPairGeneratorSpi). 0N/A * If the provider implementation is an instance of KeyPairGeneratorSpi, 0N/A * the getInstance() methods above return an instance of this class, with 0N/A * the SPI object encapsulated. 0N/A * Note: All SPI methods from the original KeyPairGenerator class have been 0N/A * moved up the hierarchy into a new class (KeyPairGeneratorSpi), which has 0N/A * been interposed in the hierarchy between the API (KeyPairGenerator) 0N/A * and its original parent (Object). 0N/A // error failover notes: 0N/A // . we failover if the implementation throws an error during init 0N/A // by retrying the init on other providers 0N/A // . we also failover if the init succeeded but the subsequent call 0N/A // to generateKeyPair() fails. In order for this to work, we need 0N/A // to remember the parameters to the last successful call to init 0N/A // and initialize() the next spi using them. 0N/A // . although not specified, KeyPairGenerators could be thread safe, 0N/A // so we make sure we do not interfere with that 0N/A // . failover is not available, if: 0N/A // . getInstance(algorithm, provider) was used 0N/A // . a provider extends KeyPairGenerator rather than 0N/A // KeyPairGeneratorSpi (JDK 1.1 style) 0N/A // . once getProvider() is called 0N/A // The provider implementation (delegate) 0N/A * Update the active spi of this class and return the next 0N/A * implementation for failover. If no more implemenations are 0N/A * available, this method returns null. However, the active spi of 0N/A * this class is never set to null. 0N/A // somebody else did a failover concurrently 0N/A // must be an InvalidAlgorithmParameterException