diff options
Diffstat (limited to 'java/security/KeyPairGenerator.java')
| -rw-r--r-- | java/security/KeyPairGenerator.java | 294 |
1 files changed, 94 insertions, 200 deletions
diff --git a/java/security/KeyPairGenerator.java b/java/security/KeyPairGenerator.java index a6e010be2..357d7a75f 100644 --- a/java/security/KeyPairGenerator.java +++ b/java/security/KeyPairGenerator.java @@ -43,72 +43,14 @@ import gnu.java.security.Engine; import java.security.spec.AlgorithmParameterSpec; /** - * <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> + * <code>KeyPairGenerator</code> is a class used to generate key-pairs for a + * security algorithm. + * + * <p>The <code>KeyPairGenerator</code> is created with the + * <code>getInstance()</code> Factory methods. It is used to generate a pair of + * public and private keys for a specific algorithm and associate this key-pair + * with the algorithm parameters it was initialized with.</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.) - * - * <p>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.</p> - * - * <p>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.</p></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 @@ -123,13 +65,10 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi private String algorithm; /** - * 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. + * Constructs a new instance of <code>KeyPairGenerator</code>. + * + * @param algorithm + * the algorithm to use. */ protected KeyPairGenerator(String algorithm) { @@ -138,11 +77,9 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * 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. + * Returns the name of the algorithm used. + * + * @return the name of the algorithm used. */ public String getAlgorithm() { @@ -150,19 +87,14 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * 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. + * Returns a new instance of <code>KeyPairGenerator</code> which generates + * key-pairs for the specified algorithm. + * + * @param algorithm + * the name of the algorithm to use. + * @return a new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by any provider. */ public static KeyPairGenerator getInstance(String algorithm) throws NoSuchAlgorithmException @@ -184,22 +116,18 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * 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 + * Returns a new instance of <code>KeyPairGenerator</code> which generates + * key-pairs for the specified algorithm from a named provider. + * + * @param algorithm + * the name of the algorithm to use. + * @param provider + * the name of a {@link Provider} to use. + * @return a new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the named provider. + * @throws NoSuchProviderException + * if the named provider was not found. */ public static KeyPairGenerator getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException @@ -212,20 +140,18 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * 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>. + * Returns a new instance of <code>KeyPairGenerator</code> which generates + * key-pairs for the specified algorithm from a designated {@link Provider}. + * + * @param algorithm + * the name of the algorithm to use. + * @param provider + * the {@link Provider} to use. + * @return a new insatnce repesenting the desired algorithm. + * @throws IllegalArgumentException + * if <code>provider</code> is <code>null</code>. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the {@link Provider}. * @since 1.4 * @see Provider */ @@ -247,23 +173,22 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } KeyPairGenerator result = null; - if (o instanceof KeyPairGeneratorSpi) - { - result = new DummyKeyPairGenerator((KeyPairGeneratorSpi) o, algorithm); - } - else if (o instanceof KeyPairGenerator) + if (o instanceof KeyPairGenerator) { result = (KeyPairGenerator) o; result.algorithm = algorithm; } + else if (o instanceof KeyPairGeneratorSpi) + result = new DummyKeyPairGenerator((KeyPairGeneratorSpi) o, algorithm); + result.provider = provider; return result; } /** - * Returns the provider of this key pair generator object. - * - * @return the provider of this key pair generator object. + * Returns the {@link Provider} of this instance. + * + * @return the {@link Provider} of this instance. */ public final Provider getProvider() { @@ -271,16 +196,11 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * 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. + * Initializes this instance for the specified key size. Since no source of + * randomness is specified, a default one will be used. + * + * @param keysize + * the size of keys to use. */ public void initialize(int keysize) { @@ -288,14 +208,13 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * 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. + * Initializes this instance for the specified key size and + * {@link SecureRandom}. + * + * @param keysize + * the size of keys to use. + * @param random + * the {@link SecureRandom} to use. * @since 1.2 */ public void initialize(int keysize, SecureRandom random) @@ -303,24 +222,14 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * <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. + * Initializes this instance with the specified + * {@link AlgorithmParameterSpec}. Since no source of randomness is specified, + * a default one will be used. + * + * @param params + * the {@link AlgorithmParameterSpec} to use. + * @throws InvalidAlgorithmParameterException + * if the designated specifications are invalid. * @since 1.2 */ public void initialize(AlgorithmParameterSpec params) @@ -330,20 +239,15 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * <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. + * Initializes this instance with the specified {@link AlgorithmParameterSpec} + * and {@link SecureRandom}. + * + * @param params + * the {@link AlgorithmParameterSpec} to use. + * @param random + * the {@link SecureRandom} to use. + * @throws InvalidAlgorithmParameterException + * if the designated specifications are invalid. * @since 1.2 */ public void initialize(AlgorithmParameterSpec params, SecureRandom random) @@ -353,17 +257,12 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * <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. + * Generates a new "DSA" {@link KeyPair} from the "GNU" security provider. + * + * <p>This method generates a unique key-pair each time it is called.</p> + * + * @return a new unique {@link KeyPair}. + * @see #generateKeyPair() * @since 1.2 */ public final KeyPair genKeyPair() @@ -381,17 +280,12 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi } /** - * <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. + * Generates a new "DSA" {@link KeyPair} from the "GNU" security provider. + * + * <p>This method generates a unique key pair each time it is called.</p> + * + * @return a new unique {@link KeyPair}. + * @see #genKeyPair() */ public KeyPair generateKeyPair() { |