diff options
Diffstat (limited to 'libjava/java/security/KeyPairGenerator.java')
| -rw-r--r-- | libjava/java/security/KeyPairGenerator.java | 381 |
1 files changed, 238 insertions, 143 deletions
diff --git a/libjava/java/security/KeyPairGenerator.java b/libjava/java/security/KeyPairGenerator.java index 9ca1aa8ee5e..8bc829608c5 100644 --- a/libjava/java/security/KeyPairGenerator.java +++ b/libjava/java/security/KeyPairGenerator.java @@ -1,5 +1,5 @@ /* KeyPairGenerator.java --- Key Pair Generator Class - Copyright (C) 1999, 2002 Free Software Foundation, Inc. + Copyright (C) 1999, 2002, 2003 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -40,25 +40,94 @@ package java.security; import java.security.spec.AlgorithmParameterSpec; /** - KeyPairGenerator is the class used to generate key pairs - for a security algorithm. - - The KeyPairGenerator is created with the getInstance() - methods. The class is used to generate public and private - keys for an algorithm and associate it with - algorithm parameters. - - @author Mark Benvenuto + * <p>The <code>KeyPairGenerator</code> class is used to generate pairs of + * public and private keys. Key pair generators are constructed using the + * <code>getInstance()</code> factory methods (static methods that return + * instances of a given class).</p> + * + * <p>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.</p> + * + * <p>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:</p> + * + * <ul> + * <li><b>Algorithm-Independent Initialization</b><br/> + * All key pair generators share the concepts of a <i>keysize</i> and a + * <i>source of randomness</i>. The <i>keysize</i> is interpreted differently + * for different algorithms (e.g., in the case of the <i>DSA</i> algorithm, + * the <i>keysize</i> corresponds to the length of the modulus). There is an + * <code>initialize()</code> method in this <code>KeyPairGenerator</code> + * class that takes these two universally shared types of arguments. There + * is also one that takes just a <i>keysize</i> argument, and uses the + * {@link SecureRandom} implementation of the highest-priority installed + * provider as the <i>source of randomness</i>. (If none of the installed + * providers supply an implementation of {@link SecureRandom}, a + * system-provided source of randomness is used.)<br/><br/> + * + * Since no other parameters are specified when you call the above + * algorithm-independent 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.<br/><br/> + * + * If the algorithm is the <i>DSA</i> algorithm, and the <i>keysize</i> + * (modulus size) is <code>512</code>, <code>768</code>, or <code>1024</code>, + * then the <b>GNU</b> provider uses a set of precomputed values for the + * <code>p</code>, <code>q</code>, and <code>g</code> parameters. If the + * <i>modulus size</i> is not one of the above values, the <b>GNU</b> + * provider creates a new set of parameters. Other providers might have + * precomputed parameter sets for more than just the three modulus sizes + * mentioned above. Still others might not have a list of precomputed + * parameters at all and instead always create new parameter sets.<br/></li> + * + * <li><b>Algorithm-Specific Initialization</b><br/> + * For situations where a set of algorithm-specific parameters already + * exists (e.g., so-called <i>community parameters</i> in <i>DSA</i>), there + * are two initialize methods that have an {@link AlgorithmParameterSpec} + * argument. One also has a {@link SecureRandom} argument, while the the + * other uses the {@link SecureRandom} implementation of the highest-priority + * installed provider as the source of randomness. (If none of the installed + * providers supply an implementation of {@link SecureRandom}, a + * system-provided source of randomness is used.)</li> + * </ul> + * + * <p>In case the client does not explicitly initialize the + * <code>KeyPairGenerator</code> (via a call to an initialize method), each + * provider must supply (and document) a default initialization. For example, + * the <b>GNU</b> provider uses a default modulus size (keysize) of + * <code>1024</code> bits.</p> + * + * <p>Note that this class is abstract and extends from {@link + * KeyPairGeneratorSpi} for historical reasons. Application developers should + * only take notice of the methods defined in this <code>KeyPairGenerator</code> + * class; all the methods in the superclass are intended for cryptographic + * service providers who wish to supply their own implementations of key pair + * generators.</p> + * + * @see Signature + * @see KeyPair + * @see AlgorithmParameterSpec + * @author Mark Benvenuto + * @author Casey Marshall */ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi { + /** The service name for key pair generators. */ + private static final String KEY_PAIR_GENERATOR = "KeyPairGenerator"; + Provider provider; private String algorithm; /** - Constructs a new KeyPairGenerator - - @param algorithm the algorithm to use + * Creates a <code>KeyPairGenerator</code> object for the specified + * algorithm. + * + * @param algorithm the standard string name of the algorithm. + * See Appendix A in the Java Cryptography Architecture API + * Specification & Reference for information about standard + * algorithm names. */ protected KeyPairGenerator(String algorithm) { @@ -67,55 +136,65 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - Returns the name of the algorithm used - - @return A string with the name of the algorithm + * Returns the standard name of the algorithm for this key pair generator. + * See Appendix A in the Java Cryptography Architecture API Specification + * & Reference for information about standard algorithm names. + * + * @return the standard string name of the algorithm. */ public String getAlgorithm() { return algorithm; } - /** - Gets an instance of the KeyPairGenerator class - which generates key pairs for the specified algorithm. - If the algorithm is not found then, it throws NoSuchAlgorithmException. - - @param algorithm the name of algorithm to choose - @return a AlgorithmParameterGenerator repesenting the desired algorithm - - @throws NoSuchAlgorithmException if the algorithm is not implemented by - providers + /** + * Generates a <code>KeyPairGenerator</code> object that implements the + * specified digest algorithm. If the default provider package provides an + * implementation of the requested digest algorithm, an instance of + * <code>KeyPairGenerator</code> containing that implementation is returned. + * If the algorithm is not available in the default package, other packages + * are searched. + * + * @param algorithm the standard string name of the algorithm. See Appendix A + * in the Java Cryptography Architecture API Specification & Reference for + * information about standard algorithm names. + * @return the new <code>KeyPairGenerator</code> object. + * @throws NoSuchAlgorithmException if the algorithm is not available in the + * environment. */ - public static KeyPairGenerator getInstance(String algorithm) throws - NoSuchAlgorithmException + public static KeyPairGenerator getInstance(String algorithm) + throws NoSuchAlgorithmException { Provider[] p = Security.getProviders(); - for (int i = 0; i < p.length; i++) { - try - { - return getInstance(algorithm, p[i]); + try + { + return getInstance(algorithm, p[i]); } - catch (NoSuchAlgorithmException ignored) {} + catch (NoSuchAlgorithmException ignored) {} } throw new NoSuchAlgorithmException(algorithm); } - /** - Gets an instance of the KeyPairGenerator class - which generates key pairs for the specified algorithm. - If the algorithm is not found then, it throws NoSuchAlgorithmException. - - @param algorithm the name of algorithm to choose - @param provider the name of the provider to find the algorithm in - @return a AlgorithmParameterGenerator repesenting the desired algorithm - - @throws NoSuchAlgorithmException if the algorithm is not implemented by - the provider - @throws NoSuchProviderException if the provider is not found + /** + * Generates a <code>KeyPairGenerator</code> object implementing the + * specified algorithm, as supplied from the specified provider, if + * such an algorithm is available from the provider. + * + * @param algorithm the standard string name of the algorithm. See + * Appendix A in the Java Cryptography Architecture API Specification + * & Reference for information about standard algorithm names. + * @param provider the string name of the provider. + * @return the new <code>KeyPairGenerator</code> object. + * @throws NoSuchAlgorithmException if the algorithm is not available + * from the provider. + * @throws NoSuchProviderException if the provider is not available in the + * environment. + * @throws IllegalArgumentException if the provider name is <code>null</code> + * or empty. + * @see Provider */ public static KeyPairGenerator getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException @@ -127,69 +206,50 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi return getInstance(algorithm, p); } - private static KeyPairGenerator getInstance(String algorithm, Provider p) - throws NoSuchAlgorithmException - { - // try the name as is - String className = p.getProperty("KeyPairGenerator." + algorithm); - if (className == null) { // try all uppercase - String upper = algorithm.toUpperCase(); - className = p.getProperty("KeyPairGenerator." + upper); - if (className == null) { // try if it's an alias - String alias = p.getProperty("Alg.Alias.KeyPairGenerator." + algorithm); - if (alias == null) { // try all-uppercase alias name - alias = p.getProperty("Alg.Alias.KeyPairGenerator." + upper); - if (alias == null) { // spit the dummy - throw new NoSuchAlgorithmException(algorithm); - } - } - className = p.getProperty("KeyPairGenerator." + alias); - if (className == null) { - throw new NoSuchAlgorithmException(algorithm); - } - } - } - return getInstance(className, algorithm, p); - } - - private static KeyPairGenerator getInstance(String classname, - String algorithm, - Provider provider) + /** + * Generates a <code>KeyPairGenerator</code> object implementing the specified + * algorithm, as supplied from the specified provider, if such an algorithm is + * available from the provider. Note: the provider doesn't have to be + * registered. + * + * @param algorithm the standard string name of the algorithm. See Appendix A + * in the Java Cryptography Architecture API Specification & Reference for + * information about standard algorithm names. + * @param provider the provider. + * @return the new <code>KeyPairGenerator</code> object. + * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not + * available from the <code>provider</code>. + * @throws IllegalArgumentException if the <code>provider</code> is + * <code>null</code>. + * @since 1.4 + * @see Provider + */ + public static KeyPairGenerator getInstance(String algorithm, + Provider provider) throws NoSuchAlgorithmException { - try - { - Object o = Class.forName(classname).newInstance(); - KeyPairGenerator kpg; - if (o instanceof KeyPairGeneratorSpi) - kpg = new DummyKeyPairGenerator((KeyPairGeneratorSpi) o, algorithm); - else - { - kpg = (KeyPairGenerator) o; - kpg.algorithm = algorithm; - } + if (provider == null) + throw new IllegalArgumentException("Illegal provider"); - kpg.provider = provider; - return kpg; - } - catch (ClassNotFoundException cnfe) + Object o = Engine.getInstance(KEY_PAIR_GENERATOR, algorithm, provider); + KeyPairGenerator result = null; + if (o instanceof KeyPairGeneratorSpi) { - throw new NoSuchAlgorithmException("Class not found"); + result = new DummyKeyPairGenerator((KeyPairGeneratorSpi) o, algorithm); } - catch (InstantiationException ie) + else if (o instanceof KeyPairGenerator) { - throw new NoSuchAlgorithmException("Class instantiation failed"); - } - catch (IllegalAccessException iae) - { - throw new NoSuchAlgorithmException("Illegal Access"); + result = (KeyPairGenerator) o; + result.algorithm = algorithm; } + result.provider = provider; + return result; } /** - Gets the provider that the class is from. - - @return the provider of this class + * Returns the provider of this key pair generator object. + * + * @return the provider of this key pair generator object. */ public final Provider getProvider() { @@ -197,11 +257,16 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - Initializes the KeyPairGenerator for the specified key size. - (Since no source of randomness is specified, a default one is - provided.) - - @param keysize Size of key to generate + * Initializes the key pair generator for a certain keysize using a default + * parameter set and the {@link SecureRandom} implementation of the + * highest-priority installed provider as the source of randomness. (If none + * of the installed providers supply an implementation of {@link 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. + * @throws InvalidParameterException if the keysize is not supported by this + * <code>KeyPairGenerator</code> object. */ public void initialize(int keysize) { @@ -209,13 +274,15 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - Initializes the KeyPairGenerator for the specified key size - and specified SecureRandom. - - @param keysize Size of key to generate - @param random SecureRandom to use - - @since JDK 1.2 + * 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. + * @throws InvalidParameterException if the <code>keysize</code> is not + * supported by this <code>KeyPairGenerator</code> object. + * @since 1.2 */ public void initialize(int keysize, SecureRandom random) { @@ -223,14 +290,25 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - Initializes the KeyPairGenerator with the specified - AlgorithmParameterSpec class. - (Since no source of randomness is specified, a default one is - provided.) - - @param params AlgorithmParameterSpec to initialize with - - @since JDK 1.2 + * <p>Initializes the key pair generator using the specified parameter set and + * the {@link SecureRandom} implementation of the highest-priority installed + * provider as the source of randomness. (If none of the installed providers + * supply an implementation of {@link SecureRandom}, a system-provided source + * of randomness is used.)</p> + * + * <p>This concrete method has been added to this previously-defined abstract + * class. This method calls the + * {@link KeyPairGeneratorSpi#initialize(AlgorithmParameterSpec, SecureRandom)} + * initialize method, passing it <code>params</code> 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 {@link UnsupportedOperationException} + * if it is not overridden by the provider.</p> + * + * @param params the parameter set used to generate the keys. + * @throws InvalidAlgorithmParameterException if the given parameters are + * inappropriate for this key pair generator. + * @since 1.2 */ public void initialize(AlgorithmParameterSpec params) throws InvalidAlgorithmParameterException @@ -239,13 +317,21 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - Initializes the KeyPairGenerator with the specified - AlgorithmParameterSpec class and specified SecureRandom. - - @param params AlgorithmParameterSpec to initialize with - @param random SecureRandom to use - - @since JDK 1.2 + * <p>Initializes the key pair generator with the given parameter set and + * source of randomness.</p> + * + * <p>This concrete method has been added to this previously-defined abstract + * class. This method calls the + * {@link KeyPairGeneratorSpi#initialize(AlgorithmParameterSpec, SecureRandom)} + * initialize method, passing it <code>params</code> and <code>random</code>. + * That initialize method always throws an {@link UnsupportedOperationException} + * if it is not overridden by the provider.</p> + * + * @param params the parameter set used to generate the keys. + * @param random the source of randomness. + * @throws InvalidAlgorithmParameterException if the given parameters are + * inappropriate for this key pair generator. + * @since 1.2 */ public void initialize(AlgorithmParameterSpec params, SecureRandom random) throws InvalidAlgorithmParameterException @@ -254,36 +340,45 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - Generates a KeyPair according the rules for the algorithm. - Unless intialized, algorithm defaults will be used. It - creates a unique key pair each time. - - Same as generateKeyPair(); - - @return a key pair + * <p>Generates a key pair.</p> + * + * <p>If this <code>KeyPairGenerator</code> has not been initialized + * explicitly, provider-specific defaults will be used for the size and other + * (algorithm-specific) values of the generated keys.</p> + * + * <p>This will generate a new key pair every time it is called.</p> + * + * <p>This method is functionally equivalent to {@link #generateKeyPair()}.</p> + * + * @return the generated key pair. + * @since 1.2 */ public final KeyPair genKeyPair() { try { - return getInstance("DSA", "GNU").generateKeyPair(); + return getInstance("DSA", "GNU").generateKeyPair(); } catch (Exception e) { - System.err.println("genKeyPair failed: " + e); - e.printStackTrace(); - return null; + System.err.println("genKeyPair failed: " + e); + e.printStackTrace(); + return null; } } /** - Generates a KeyPair according the rules for the algorithm. - Unless intialized, algorithm defaults will be used. It - creates a unique key pair each time. - - Same as genKeyPair(); - - @return a key pair + * <p>Generates a key pair.</p> + * + * <p>If this <code>KeyPairGenerator</code> has not been initialized + * explicitly, provider-specific defaults will be used for the size and other + * (algorithm-specific) values of the generated keys.</p> + * + * <p>This will generate a new key pair every time it is called.</p> + * + * <p>This method is functionally equivalent to {@link #genKeyPair()}.</p> + * + * @return the generated key pair. */ public KeyPair generateKeyPair() { |
