001: /*
002: * @(#)KeyPairGenerator.java 1.56 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.security;
029:
030: import java.security.spec.AlgorithmParameterSpec;
031:
032: /**
033: * The KeyPairGenerator class is used to generate pairs of
034: * public and private keys. Key pair generators are constructed using the
035: * <code>getInstance</code> factory methods (static methods that
036: * return instances of a given class).
037: *
038: * <p>A Key pair generator for a particular algorithm creates a public/private
039: * key pair that can be used with this algorithm. It also associates
040: * algorithm-specific parameters with each of the generated keys.
041: *
042: * <p>There are two ways to generate a key pair: in an algorithm-independent
043: * manner, and in an algorithm-specific manner.
044: * The only difference between the two is the initialization of the object:
045: *
046: * <ul>
047: * <li><b>Algorithm-Independent Initialization</b>
048: * <p>All key pair generators share the concepts of a keysize and a
049: * source of randomness. The keysize is interpreted differently for different
050: * algorithms (e.g., in the case of the <i>DSA</i> algorithm, the keysize
051: * corresponds to the length of the modulus).
052: * There is an
053: * {@link #initialize(int, java.security.SecureRandom) initialize}
054: * method in this KeyPairGenerator class that takes these two universally
055: * shared types of arguments. There is also one that takes just a
056: * <code>keysize</code> argument, and uses the <code>SecureRandom</code>
057: * implementation of the highest-priority installed provider as the source
058: * of randomness. (If none of the installed providers supply an implementation
059: * of <code>SecureRandom</code>, a system-provided source of randomness is
060: * used.)
061: *
062: * <p>Since no other parameters are specified when you call the above
063: * algorithm-independent <code>initialize</code> methods, it is up to the
064: * provider what to do about the algorithm-specific parameters (if any) to be
065: * associated with each of the keys.
066: *
067: * <p>If the algorithm is the <i>DSA</i> algorithm, and the keysize (modulus
068: * size) is 512, 768, or 1024, then the <i>Sun</i> provider uses a set of
069: * precomputed values for the <code>p</code>, <code>q</code>, and
070: * <code>g</code> parameters. If the modulus size is not one of the above
071: * values, the <i>Sun</i> provider creates a new set of parameters. Other
072: * providers might have precomputed parameter sets for more than just the
073: * three modulus sizes mentioned above. Still others might not have a list of
074: * precomputed parameters at all and instead always create new parameter sets.
075: * <p>
076: *
077: * <li><b>Algorithm-Specific Initialization</b>
078: * <p>For situations where a set of algorithm-specific parameters already
079: * exists (e.g., so-called <i>community parameters</i> in DSA), there are two
080: * {@link #initialize(java.security.spec.AlgorithmParameterSpec)
081: * initialize} methods that have an <code>AlgorithmParameterSpec</code>
082: * argument. One also has a <code>SecureRandom</code> argument, while the
083: * the other uses the <code>SecureRandom</code>
084: * implementation of the highest-priority installed provider as the source
085: * of randomness. (If none of the installed providers supply an implementation
086: * of <code>SecureRandom</code>, a system-provided source of randomness is
087: * used.)
088: * </ul>
089: *
090: * <p>In case the client does not explicitly initialize the KeyPairGenerator
091: * (via a call to an <code>initialize</code> method), each provider must
092: * supply (and document) a default initialization.
093: * For example, the <i>Sun</i> provider uses a default modulus size (keysize)
094: * of 1024 bits.
095: *
096: * <p>Note that this class is abstract and extends from
097: * <code>KeyPairGeneratorSpi</code> for historical reasons.
098: * Application developers should only take notice of the methods defined in
099: * this <code>KeyPairGenerator</code> class; all the methods in
100: * the superclass are intended for cryptographic service providers who wish to
101: * supply their own implementations of key pair generators.
102: *
103: * @author Benjamin Renaud
104: *
105: * @version 1.49, 02/02/00
106: *
107: * @see java.security.spec.AlgorithmParameterSpec
108: */
109:
110: public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
111:
112: private String algorithm;
113:
114: // The provider
115: private Provider provider;
116:
117: /**
118: * Creates a KeyPairGenerator object for the specified algorithm.
119: *
120: * @param algorithm the standard string name of the algorithm.
121: * See Appendix A in the <a href=
122: * "../../../guide/security/CryptoSpec.html#AppA">
123: * Java Cryptography Architecture API Specification & Reference </a>
124: * for information about standard algorithm names.
125: */
126: protected KeyPairGenerator(String algorithm) {
127: this .algorithm = algorithm;
128: }
129:
130: /**
131: * Returns the standard name of the algorithm for this key pair generator.
132: * See Appendix A in the <a href=
133: * "../../../guide/security/CryptoSpec.html#AppA">
134: * Java Cryptography Architecture API Specification & Reference </a>
135: * for information about standard algorithm names.
136: *
137: * @return the standard string name of the algorithm.
138: */
139: public String getAlgorithm() {
140: return this .algorithm;
141: }
142:
143: /**
144: * Generates a KeyPairGenerator object that implements the specified digest
145: * algorithm. If the default provider package
146: * provides an implementation of the requested digest algorithm,
147: * an instance of KeyPairGenerator containing that implementation is
148: * returned.
149: * If the algorithm is not available in the default
150: * package, other packages are searched.
151: *
152: * @param algorithm the standard string name of the algorithm.
153: * See Appendix A in the <a href=
154: * "../../../guide/security/CryptoSpec.html#AppA">
155: * Java Cryptography Architecture API Specification & Reference </a>
156: * for information about standard algorithm names.
157: *
158: * @return the new KeyPairGenerator object.
159: *
160: * @exception NoSuchAlgorithmException if the algorithm is
161: * not available in the environment.
162: */
163: public static KeyPairGenerator getInstance(String algorithm)
164: throws NoSuchAlgorithmException {
165: try {
166: Object[] objs = Security.getImpl(algorithm,
167: "KeyPairGenerator", (String) null);
168: if (objs[0] instanceof KeyPairGenerator) {
169: KeyPairGenerator keyPairGen = (KeyPairGenerator) objs[0];
170: keyPairGen.provider = (Provider) objs[1];
171: return keyPairGen;
172: } else {
173: KeyPairGenerator delegate = new Delegate(
174: (KeyPairGeneratorSpi) objs[0], algorithm);
175: delegate.provider = (Provider) objs[1];
176: return delegate;
177: }
178: } catch (NoSuchProviderException e) {
179: throw new NoSuchAlgorithmException(algorithm + " not found");
180: }
181: }
182:
183: /**
184: * Generates a KeyPairGenerator object implementing the specified
185: * algorithm, as supplied from the specified provider,
186: * if such an algorithm is available from the provider.
187: *
188: * @param algorithm the standard string name of the algorithm.
189: * See Appendix A in the <a href=
190: * "../../../guide/security/CryptoSpec.html#AppA">
191: * Java Cryptography Architecture API Specification & Reference </a>
192: * for information about standard algorithm names.
193: *
194: * @param provider the string name of the provider.
195: *
196: * @return the new KeyPairGenerator object.
197: *
198: * @exception NoSuchAlgorithmException if the algorithm is
199: * not available from the provider.
200: *
201: * @exception NoSuchProviderException if the provider is not
202: * available in the environment.
203: *
204: * @exception IllegalArgumentException if the provider name is null
205: * or empty.
206: *
207: * @see Provider
208: */
209: public static KeyPairGenerator getInstance(String algorithm,
210: String provider) throws NoSuchAlgorithmException,
211: NoSuchProviderException {
212: if (provider == null || provider.length() == 0)
213: throw new IllegalArgumentException("missing provider");
214: Object[] objs = Security.getImpl(algorithm, "KeyPairGenerator",
215: provider);
216: if (objs[0] instanceof KeyPairGenerator) {
217: KeyPairGenerator keyPairGen = (KeyPairGenerator) objs[0];
218: keyPairGen.provider = (Provider) objs[1];
219: return keyPairGen;
220: } else {
221: KeyPairGenerator delegate = new Delegate(
222: (KeyPairGeneratorSpi) objs[0], algorithm);
223: delegate.provider = (Provider) objs[1];
224: return delegate;
225: }
226: }
227:
228: /**
229: * Generates a KeyPairGenerator object implementing the specified
230: * algorithm, as supplied from the specified provider,
231: * if such an algorithm is available from the provider.
232: * Note: the <code>provider</code> doesn't have to be registered.
233: *
234: * @param algorithm the standard string name of the algorithm.
235: * See Appendix A in the <a href=
236: * "../../../guide/security/CryptoSpec.html#AppA">
237: * Java Cryptography Architecture API Specification & Reference </a>
238: * for information about standard algorithm names.
239: *
240: * @param provider the provider.
241: *
242: * @return the new KeyPairGenerator object.
243: *
244: * @exception NoSuchAlgorithmException if the algorithm is
245: * not available from the provider.
246: *
247: * @exception IllegalArgumentException if the <code>provider</code> is
248: * null.
249: *
250: * @see Provider
251: *
252: * @since 1.4
253: */
254: public static KeyPairGenerator getInstance(String algorithm,
255: Provider provider) throws NoSuchAlgorithmException {
256: if (provider == null)
257: throw new IllegalArgumentException("missing provider");
258: Object[] objs = Security.getImpl(algorithm, "KeyPairGenerator",
259: provider);
260: if (objs[0] instanceof KeyPairGenerator) {
261: KeyPairGenerator keyPairGen = (KeyPairGenerator) objs[0];
262: keyPairGen.provider = (Provider) objs[1];
263: return keyPairGen;
264: } else {
265: KeyPairGenerator delegate = new Delegate(
266: (KeyPairGeneratorSpi) objs[0], algorithm);
267: delegate.provider = (Provider) objs[1];
268: return delegate;
269: }
270: }
271:
272: /**
273: * Returns the provider of this key pair generator object.
274: *
275: * @return the provider of this key pair generator object
276: */
277: public final Provider getProvider() {
278: return this .provider;
279: }
280:
281: /**
282: * Initializes the key pair generator for a certain keysize using
283: * a default parameter set and the <code>SecureRandom</code>
284: * implementation of the highest-priority installed provider as the source
285: * of randomness.
286: * (If none of the installed providers supply an implementation of
287: * <code>SecureRandom</code>, a system-provided source of randomness is
288: * used.)
289: *
290: * @param keysize the keysize. This is an
291: * algorithm-specific metric, such as modulus length, specified in
292: * number of bits.
293: *
294: * @exception InvalidParameterException if the <code>keysize</code> is not
295: * supported by this KeyPairGenerator object.
296: */
297: public void initialize(int keysize) {
298: initialize(keysize, new SecureRandom());
299: }
300:
301: /**
302: * Initializes the key pair generator for a certain keysize with
303: * the given source of randomness (and a default parameter set).
304: *
305: * @param keysize the keysize. This is an
306: * algorithm-specific metric, such as modulus length, specified in
307: * number of bits.
308: * @param random the source of randomness.
309: *
310: * @exception InvalidParameterException if the <code>keysize</code> is not
311: * supported by this KeyPairGenerator object.
312: *
313: * @since 1.2
314: */
315: public void initialize(int keysize, SecureRandom random) {
316: // This does nothing, because either
317: // 1. the implementation object returned by getInstance() is an
318: // instance of KeyPairGenerator which has its own
319: // initialize(keysize, random) method, so the application would
320: // be calling that method directly, or
321: // 2. the implementation returned by getInstance() is an instance
322: // of Delegate, in which case initialize(keysize, random) is
323: // overridden to call the corresponding SPI method.
324: // (This is a special case, because the API and SPI method have the
325: // same name.)
326: }
327:
328: /**
329: * Initializes the key pair generator using the specified parameter
330: * set and the <code>SecureRandom</code>
331: * implementation of the highest-priority installed provider as the source
332: * of randomness.
333: * (If none of the installed providers supply an implementation of
334: * <code>SecureRandom</code>, a system-provided source of randomness is
335: * used.).
336: *
337: * <p>This concrete method has been added to this previously-defined
338: * abstract class.
339: * This method calls the KeyPairGeneratorSpi
340: * {@link KeyPairGeneratorSpi.html#
341: * initialize(java.security.spec.AlgorithmParameterSpec,
342: * java.security.SecureRandom) initialize} method,
343: * passing it <code>params</code> and a source of randomness (obtained
344: * from the highest-priority installed provider or system-provided if none
345: * of the installed providers supply one).
346: * That <code>initialize</code> method always throws an
347: * UnsupportedOperationException if it is not overridden by the provider.
348: *
349: * @param params the parameter set used to generate the keys.
350: *
351: * @exception InvalidAlgorithmParameterException if the given parameters
352: * are inappropriate for this key pair generator.
353: *
354: * @since 1.2
355: */
356: public void initialize(AlgorithmParameterSpec params)
357: throws InvalidAlgorithmParameterException {
358: initialize(params, new SecureRandom());
359: }
360:
361: /**
362: * Initializes the key pair generator with the given parameter
363: * set and source of randomness.
364: *
365: * <p>This concrete method has been added to this previously-defined
366: * abstract class.
367: * This method calls the KeyPairGeneratorSpi {@link
368: * KeyPairGeneratorSpi.html#
369: * initialize(java.security.spec.AlgorithmParameterSpec,
370: * java.security.SecureRandom) initialize} method,
371: * passing it <code>params</code> and <code>random</code>.
372: * That <code>initialize</code>
373: * method always throws an
374: * UnsupportedOperationException if it is not overridden by the provider.
375: *
376: * @param params the parameter set used to generate the keys.
377: * @param random the source of randomness.
378: *
379: * @exception InvalidAlgorithmParameterException if the given parameters
380: * are inappropriate for this key pair generator.
381: *
382: * @since 1.2
383: */
384: public void initialize(AlgorithmParameterSpec params,
385: SecureRandom random)
386: throws InvalidAlgorithmParameterException {
387: // This does nothing, because either
388: // 1. the implementation object returned by getInstance() is an
389: // instance of KeyPairGenerator which has its own
390: // initialize(params, random) method, so the application would
391: // be calling that method directly, or
392: // 2. the implementation returned by getInstance() is an instance
393: // of Delegate, in which case initialize(params, random) is
394: // overridden to call the corresponding SPI method.
395: // (This is a special case, because the API and SPI method have the
396: // same name.)
397: }
398:
399: /**
400: * Generates a key pair.
401: *
402: * <p>If this KeyPairGenerator has not been initialized explicitly,
403: * provider-specific defaults will be used for the size and other
404: * (algorithm-specific) values of the generated keys.
405: *
406: * <p>This will generate a new key pair every time it is called.
407: *
408: * <p>This method is functionally equivalent to
409: * {@link #generateKeyPair() generateKeyPair}.
410: *
411: * @return the generated key pair
412: *
413: * @since 1.2
414: */
415: public final KeyPair genKeyPair() {
416: return generateKeyPair();
417: }
418:
419: /**
420: * Generates a key pair.
421: *
422: * <p>If this KeyPairGenerator has not been initialized explicitly,
423: * provider-specific defaults will be used for the size and other
424: * (algorithm-specific) values of the generated keys.
425: *
426: * <p>This will generate a new key pair every time it is called.
427: *
428: * <p>This method is functionally equivalent to
429: * {@link #genKeyPair() genKeyPair}.
430: *
431: * @return the generated key pair
432: */
433: public KeyPair generateKeyPair() {
434: // This does nothing (except returning null), because either:
435: //
436: // 1. the implementation object returned by getInstance() is an
437: // instance of KeyPairGenerator which has its own implementation
438: // of generateKeyPair (overriding this one), so the application
439: // would be calling that method directly, or
440: //
441: // 2. the implementation returned by getInstance() is an instance
442: // of Delegate, in which case generateKeyPair is
443: // overridden to invoke the corresponding SPI method.
444: //
445: // (This is a special case, because in JDK 1.1.x the generateKeyPair
446: // method was used both as an API and a SPI method.)
447: return null;
448: }
449:
450: /*
451: * The following class allows providers to extend from KeyPairGeneratorSpi
452: * rather than from KeyPairGenerator. It represents a KeyPairGenerator
453: * with an encapsulated, provider-supplied SPI object (of type
454: * KeyPairGeneratorSpi).
455: * If the provider implementation is an instance of KeyPairGeneratorSpi,
456: * the getInstance() methods above return an instance of this class, with
457: * the SPI object encapsulated.
458: *
459: * Note: All SPI methods from the original KeyPairGenerator class have been
460: * moved up the hierarchy into a new class (KeyPairGeneratorSpi), which has
461: * been interposed in the hierarchy between the API (KeyPairGenerator)
462: * and its original parent (Object).
463: */
464:
465: static class Delegate extends KeyPairGenerator {
466:
467: // The provider implementation (delegate)
468: private KeyPairGeneratorSpi kpairGenSpi;
469:
470: // constructor
471: public Delegate(KeyPairGeneratorSpi kpairGenSpi,
472: String algorithm) {
473: super (algorithm);
474: this .kpairGenSpi = kpairGenSpi;
475: }
476:
477: // engine method
478: public void initialize(int keysize, SecureRandom random) {
479: kpairGenSpi.initialize(keysize, random);
480: }
481:
482: // engine method
483: public void initialize(AlgorithmParameterSpec params,
484: SecureRandom random)
485: throws InvalidAlgorithmParameterException {
486: kpairGenSpi.initialize(params, random);
487: ;
488: }
489:
490: // engine method
491: public KeyPair generateKeyPair() {
492: return kpairGenSpi.generateKeyPair();
493: }
494: }
495: }
|