1 /*
2 * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.security;
27
28 import java.util.*;
29
30 import java.security.spec.AlgorithmParameterSpec;
31
32 import java.security.Provider.Service;
33
34 import sun.security.jca.*;
35 import sun.security.jca.GetInstance.Instance;
36
37 /**
38 * The KeyPairGenerator class is used to generate pairs of
39 * public and private keys. Key pair generators are constructed using the
40 * <code>getInstance</code> factory methods (static methods that
41 * return instances of a given class).
42 *
43 * <p>A Key pair generator for a particular algorithm creates a public/private
44 * key pair that can be used with this algorithm. It also associates
45 * algorithm-specific parameters with each of the generated keys.
46 *
47 * <p>There are two ways to generate a key pair: in an algorithm-independent
48 * manner, and in an algorithm-specific manner.
49 * The only difference between the two is the initialization of the object:
50 *
51 * <ul>
52 * <li><b>Algorithm-Independent Initialization</b>
53 * <p>All key pair generators share the concepts of a keysize and a
54 * source of randomness. The keysize is interpreted differently for different
55 * algorithms (e.g., in the case of the <i>DSA</i> algorithm, the keysize
56 * corresponds to the length of the modulus).
57 * There is an
58 * {@link #initialize(int, java.security.SecureRandom) initialize}
59 * method in this KeyPairGenerator class that takes these two universally
60 * shared types of arguments. There is also one that takes just a
61 * <code>keysize</code> argument, and uses the <code>SecureRandom</code>
62 * implementation of the highest-priority installed provider as the source
63 * of randomness. (If none of the installed providers supply an implementation
64 * of <code>SecureRandom</code>, a system-provided source of randomness is
65 * used.)
66 *
67 * <p>Since no other parameters are specified when you call the above
68 * algorithm-independent <code>initialize</code> methods, it is up to the
69 * provider what to do about the algorithm-specific parameters (if any) to be
70 * associated with each of the keys.
71 *
72 * <p>If the algorithm is the <i>DSA</i> algorithm, and the keysize (modulus
73 * size) is 512, 768, or 1024, then the <i>Sun</i> provider uses a set of
74 * precomputed values for the <code>p</code>, <code>q</code>, and
75 * <code>g</code> parameters. If the modulus size is not one of the above
76 * values, the <i>Sun</i> provider creates a new set of parameters. Other
77 * providers might have precomputed parameter sets for more than just the
78 * three modulus sizes mentioned above. Still others might not have a list of
79 * precomputed parameters at all and instead always create new parameter sets.
80 * <p>
81 *
82 * <li><b>Algorithm-Specific Initialization</b>
83 * <p>For situations where a set of algorithm-specific parameters already
84 * exists (e.g., so-called <i>community parameters</i> in DSA), there are two
85 * {@link #initialize(java.security.spec.AlgorithmParameterSpec)
86 * initialize} methods that have an <code>AlgorithmParameterSpec</code>
87 * argument. One also has a <code>SecureRandom</code> argument, while the
88 * the other uses the <code>SecureRandom</code>
89 * implementation of the highest-priority installed provider as the source
90 * of randomness. (If none of the installed providers supply an implementation
91 * of <code>SecureRandom</code>, a system-provided source of randomness is
92 * used.)
93 * </ul>
94 *
95 * <p>In case the client does not explicitly initialize the KeyPairGenerator
96 * (via a call to an <code>initialize</code> method), each provider must
97 * supply (and document) a default initialization.
98 * For example, the <i>Sun</i> provider uses a default modulus size (keysize)
99 * of 1024 bits.
100 *
101 * <p>Note that this class is abstract and extends from
102 * <code>KeyPairGeneratorSpi</code> for historical reasons.
103 * Application developers should only take notice of the methods defined in
104 * this <code>KeyPairGenerator</code> class; all the methods in
105 * the superclass are intended for cryptographic service providers who wish to
106 * supply their own implementations of key pair generators.
107 *
108 * <p> Every implementation of the Java platform is required to support the
109 * following standard <code>KeyPairGenerator</code> algorithms and keysizes in
110 * parentheses:
111 * <ul>
112 * <li><tt>DiffieHellman</tt> (1024)</li>
113 * <li><tt>DSA</tt> (1024)</li>
114 * <li><tt>RSA</tt> (1024, 2048)</li>
115 * </ul>
116 * These algorithms are described in the <a href=
117 * "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyPairGenerator">
118 * KeyPairGenerator section</a> of the
119 * Java Cryptography Architecture Standard Algorithm Name Documentation.
120 * Consult the release documentation for your implementation to see if any
121 * other algorithms are supported.
122 *
123 * @author Benjamin Renaud
124 *
125 * @see java.security.spec.AlgorithmParameterSpec
126 */
127
128 public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
129
130 private final String algorithm;
131
132 // The provider
133 Provider provider;
134
305 KeyPairGeneratorSpi.class, algorithm, provider);
306 return getInstance(instance, algorithm);
307 }
308
309 /**
310 * Returns the provider of this key pair generator object.
311 *
312 * @return the provider of this key pair generator object
313 */
314 public final Provider getProvider() {
315 disableFailover();
316 return this.provider;
317 }
318
319 void disableFailover() {
320 // empty, overridden in Delegate
321 }
322
323 /**
324 * Initializes the key pair generator for a certain keysize using
325 * a default parameter set and the <code>SecureRandom</code>
326 * implementation of the highest-priority installed provider as the source
327 * of randomness.
328 * (If none of the installed providers supply an implementation of
329 * <code>SecureRandom</code>, a system-provided source of randomness is
330 * used.)
331 *
332 * @param keysize the keysize. This is an
333 * algorithm-specific metric, such as modulus length, specified in
334 * number of bits.
335 *
336 * @exception InvalidParameterException if the <code>keysize</code> is not
337 * supported by this KeyPairGenerator object.
338 */
339 public void initialize(int keysize) {
340 initialize(keysize, JCAUtil.getSecureRandom());
341 }
342
343 /**
344 * Initializes the key pair generator for a certain keysize with
345 * the given source of randomness (and a default parameter set).
346 *
347 * @param keysize the keysize. This is an
348 * algorithm-specific metric, such as modulus length, specified in
349 * number of bits.
350 * @param random the source of randomness.
351 *
352 * @exception InvalidParameterException if the <code>keysize</code> is not
353 * supported by this KeyPairGenerator object.
354 *
355 * @since 1.2
356 */
357 public void initialize(int keysize, SecureRandom random) {
358 // This does nothing, because either
359 // 1. the implementation object returned by getInstance() is an
360 // instance of KeyPairGenerator which has its own
361 // initialize(keysize, random) method, so the application would
362 // be calling that method directly, or
363 // 2. the implementation returned by getInstance() is an instance
364 // of Delegate, in which case initialize(keysize, random) is
365 // overridden to call the corresponding SPI method.
366 // (This is a special case, because the API and SPI method have the
367 // same name.)
368 }
369
370 /**
371 * Initializes the key pair generator using the specified parameter
372 * set and the <code>SecureRandom</code>
373 * implementation of the highest-priority installed provider as the source
374 * of randomness.
375 * (If none of the installed providers supply an implementation of
376 * <code>SecureRandom</code>, a system-provided source of randomness is
377 * used.).
378 *
379 * <p>This concrete method has been added to this previously-defined
380 * abstract class.
381 * This method calls the KeyPairGeneratorSpi
382 * {@link KeyPairGeneratorSpi#initialize(
383 * java.security.spec.AlgorithmParameterSpec,
384 * java.security.SecureRandom) initialize} method,
385 * passing it <code>params</code> and a source of randomness (obtained
386 * from the highest-priority installed provider or system-provided if none
387 * of the installed providers supply one).
388 * That <code>initialize</code> method always throws an
389 * UnsupportedOperationException if it is not overridden by the provider.
390 *
391 * @param params the parameter set used to generate the keys.
392 *
393 * @exception InvalidAlgorithmParameterException if the given parameters
394 * are inappropriate for this key pair generator.
395 *
396 * @since 1.2
397 */
398 public void initialize(AlgorithmParameterSpec params)
399 throws InvalidAlgorithmParameterException {
400 initialize(params, JCAUtil.getSecureRandom());
401 }
402
403 /**
404 * Initializes the key pair generator with the given parameter
405 * set and source of randomness.
406 *
407 * <p>This concrete method has been added to this previously-defined
408 * abstract class.
409 * This method calls the KeyPairGeneratorSpi {@link
410 * KeyPairGeneratorSpi#initialize(
411 * java.security.spec.AlgorithmParameterSpec,
412 * java.security.SecureRandom) initialize} method,
413 * passing it <code>params</code> and <code>random</code>.
414 * That <code>initialize</code>
415 * method always throws an
416 * UnsupportedOperationException if it is not overridden by the provider.
417 *
418 * @param params the parameter set used to generate the keys.
419 * @param random the source of randomness.
420 *
421 * @exception InvalidAlgorithmParameterException if the given parameters
422 * are inappropriate for this key pair generator.
423 *
424 * @since 1.2
425 */
426 public void initialize(AlgorithmParameterSpec params,
427 SecureRandom random)
428 throws InvalidAlgorithmParameterException
429 {
430 // This does nothing, because either
431 // 1. the implementation object returned by getInstance() is an
432 // instance of KeyPairGenerator which has its own
433 // initialize(params, random) method, so the application would
434 // be calling that method directly, or
|
1 /*
2 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.security;
27
28 import java.util.*;
29
30 import java.security.spec.AlgorithmParameterSpec;
31
32 import java.security.Provider.Service;
33
34 import sun.security.jca.*;
35 import sun.security.jca.GetInstance.Instance;
36
37 /**
38 * The KeyPairGenerator class is used to generate pairs of
39 * public and private keys. Key pair generators are constructed using the
40 * {@code getInstance} factory methods (static methods that
41 * return instances of a given class).
42 *
43 * <p>A Key pair generator for a particular algorithm creates a public/private
44 * key pair that can be used with this algorithm. It also associates
45 * algorithm-specific parameters with each of the generated keys.
46 *
47 * <p>There are two ways to generate a key pair: in an algorithm-independent
48 * manner, and in an algorithm-specific manner.
49 * The only difference between the two is the initialization of the object:
50 *
51 * <ul>
52 * <li><b>Algorithm-Independent Initialization</b>
53 * <p>All key pair generators share the concepts of a keysize and a
54 * source of randomness. The keysize is interpreted differently for different
55 * algorithms (e.g., in the case of the <i>DSA</i> algorithm, the keysize
56 * corresponds to the length of the modulus).
57 * There is an
58 * {@link #initialize(int, java.security.SecureRandom) initialize}
59 * method in this KeyPairGenerator class that takes these two universally
60 * shared types of arguments. There is also one that takes just a
61 * {@code keysize} argument, and uses the {@code SecureRandom}
62 * implementation of the highest-priority installed provider as the source
63 * of randomness. (If none of the installed providers supply an implementation
64 * of {@code SecureRandom}, a system-provided source of randomness is
65 * used.)
66 *
67 * <p>Since no other parameters are specified when you call the above
68 * algorithm-independent {@code initialize} methods, it is up to the
69 * provider what to do about the algorithm-specific parameters (if any) to be
70 * associated with each of the keys.
71 *
72 * <p>If the algorithm is the <i>DSA</i> algorithm, and the keysize (modulus
73 * size) is 512, 768, or 1024, then the <i>Sun</i> provider uses a set of
74 * precomputed values for the {@code p}, {@code q}, and
75 * {@code g} parameters. If the modulus size is not one of the above
76 * values, the <i>Sun</i> provider creates a new set of parameters. Other
77 * providers might have precomputed parameter sets for more than just the
78 * three modulus sizes mentioned above. Still others might not have a list of
79 * precomputed parameters at all and instead always create new parameter sets.
80 * <p>
81 *
82 * <li><b>Algorithm-Specific Initialization</b>
83 * <p>For situations where a set of algorithm-specific parameters already
84 * exists (e.g., so-called <i>community parameters</i> in DSA), there are two
85 * {@link #initialize(java.security.spec.AlgorithmParameterSpec)
86 * initialize} methods that have an {@code AlgorithmParameterSpec}
87 * argument. One also has a {@code SecureRandom} argument, while the
88 * the other uses the {@code SecureRandom}
89 * implementation of the highest-priority installed provider as the source
90 * of randomness. (If none of the installed providers supply an implementation
91 * of {@code SecureRandom}, a system-provided source of randomness is
92 * used.)
93 * </ul>
94 *
95 * <p>In case the client does not explicitly initialize the KeyPairGenerator
96 * (via a call to an {@code initialize} method), each provider must
97 * supply (and document) a default initialization.
98 * For example, the <i>Sun</i> provider uses a default modulus size (keysize)
99 * of 1024 bits.
100 *
101 * <p>Note that this class is abstract and extends from
102 * {@code KeyPairGeneratorSpi} for historical reasons.
103 * Application developers should only take notice of the methods defined in
104 * this {@code KeyPairGenerator} class; all the methods in
105 * the superclass are intended for cryptographic service providers who wish to
106 * supply their own implementations of key pair generators.
107 *
108 * <p> Every implementation of the Java platform is required to support the
109 * following standard {@code KeyPairGenerator} algorithms and keysizes in
110 * parentheses:
111 * <ul>
112 * <li>{@code DiffieHellman} (1024)</li>
113 * <li>{@code DSA} (1024)</li>
114 * <li>{@code RSA} (1024, 2048)</li>
115 * </ul>
116 * These algorithms are described in the <a href=
117 * "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyPairGenerator">
118 * KeyPairGenerator section</a> of the
119 * Java Cryptography Architecture Standard Algorithm Name Documentation.
120 * Consult the release documentation for your implementation to see if any
121 * other algorithms are supported.
122 *
123 * @author Benjamin Renaud
124 *
125 * @see java.security.spec.AlgorithmParameterSpec
126 */
127
128 public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
129
130 private final String algorithm;
131
132 // The provider
133 Provider provider;
134
305 KeyPairGeneratorSpi.class, algorithm, provider);
306 return getInstance(instance, algorithm);
307 }
308
309 /**
310 * Returns the provider of this key pair generator object.
311 *
312 * @return the provider of this key pair generator object
313 */
314 public final Provider getProvider() {
315 disableFailover();
316 return this.provider;
317 }
318
319 void disableFailover() {
320 // empty, overridden in Delegate
321 }
322
323 /**
324 * Initializes the key pair generator for a certain keysize using
325 * a default parameter set and the {@code SecureRandom}
326 * implementation of the highest-priority installed provider as the source
327 * of randomness.
328 * (If none of the installed providers supply an implementation of
329 * {@code SecureRandom}, a system-provided source of randomness is
330 * used.)
331 *
332 * @param keysize the keysize. This is an
333 * algorithm-specific metric, such as modulus length, specified in
334 * number of bits.
335 *
336 * @exception InvalidParameterException if the {@code keysize} is not
337 * supported by this KeyPairGenerator object.
338 */
339 public void initialize(int keysize) {
340 initialize(keysize, JCAUtil.getSecureRandom());
341 }
342
343 /**
344 * Initializes the key pair generator for a certain keysize with
345 * the given source of randomness (and a default parameter set).
346 *
347 * @param keysize the keysize. This is an
348 * algorithm-specific metric, such as modulus length, specified in
349 * number of bits.
350 * @param random the source of randomness.
351 *
352 * @exception InvalidParameterException if the {@code keysize} is not
353 * supported by this KeyPairGenerator object.
354 *
355 * @since 1.2
356 */
357 public void initialize(int keysize, SecureRandom random) {
358 // This does nothing, because either
359 // 1. the implementation object returned by getInstance() is an
360 // instance of KeyPairGenerator which has its own
361 // initialize(keysize, random) method, so the application would
362 // be calling that method directly, or
363 // 2. the implementation returned by getInstance() is an instance
364 // of Delegate, in which case initialize(keysize, random) is
365 // overridden to call the corresponding SPI method.
366 // (This is a special case, because the API and SPI method have the
367 // same name.)
368 }
369
370 /**
371 * Initializes the key pair generator using the specified parameter
372 * set and the {@code SecureRandom}
373 * implementation of the highest-priority installed provider as the source
374 * of randomness.
375 * (If none of the installed providers supply an implementation of
376 * {@code SecureRandom}, a system-provided source of randomness is
377 * used.).
378 *
379 * <p>This concrete method has been added to this previously-defined
380 * abstract class.
381 * This method calls the KeyPairGeneratorSpi
382 * {@link KeyPairGeneratorSpi#initialize(
383 * java.security.spec.AlgorithmParameterSpec,
384 * java.security.SecureRandom) initialize} method,
385 * passing it {@code params} and a source of randomness (obtained
386 * from the highest-priority installed provider or system-provided if none
387 * of the installed providers supply one).
388 * That {@code initialize} method always throws an
389 * UnsupportedOperationException if it is not overridden by the provider.
390 *
391 * @param params the parameter set used to generate the keys.
392 *
393 * @exception InvalidAlgorithmParameterException if the given parameters
394 * are inappropriate for this key pair generator.
395 *
396 * @since 1.2
397 */
398 public void initialize(AlgorithmParameterSpec params)
399 throws InvalidAlgorithmParameterException {
400 initialize(params, JCAUtil.getSecureRandom());
401 }
402
403 /**
404 * Initializes the key pair generator with the given parameter
405 * set and source of randomness.
406 *
407 * <p>This concrete method has been added to this previously-defined
408 * abstract class.
409 * This method calls the KeyPairGeneratorSpi {@link
410 * KeyPairGeneratorSpi#initialize(
411 * java.security.spec.AlgorithmParameterSpec,
412 * java.security.SecureRandom) initialize} method,
413 * passing it {@code params} and {@code random}.
414 * That {@code initialize}
415 * method always throws an
416 * UnsupportedOperationException if it is not overridden by the provider.
417 *
418 * @param params the parameter set used to generate the keys.
419 * @param random the source of randomness.
420 *
421 * @exception InvalidAlgorithmParameterException if the given parameters
422 * are inappropriate for this key pair generator.
423 *
424 * @since 1.2
425 */
426 public void initialize(AlgorithmParameterSpec params,
427 SecureRandom random)
428 throws InvalidAlgorithmParameterException
429 {
430 // This does nothing, because either
431 // 1. the implementation object returned by getInstance() is an
432 // instance of KeyPairGenerator which has its own
433 // initialize(params, random) method, so the application would
434 // be calling that method directly, or
|