Source for java.security.KeyPairGenerator

   1: /* KeyPairGenerator.java --- Key Pair Generator Class
   2:    Copyright (C) 1999, 2002, 2003, 2004, 2005  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.security;
  40: 
  41: import gnu.java.security.Engine;
  42: 
  43: import java.security.spec.AlgorithmParameterSpec;
  44: 
  45: /**
  46:  * <p>The <code>KeyPairGenerator</code> class is used to generate pairs of
  47:  * public and private keys. Key pair generators are constructed using the
  48:  * <code>getInstance()</code> factory methods (static methods that return
  49:  * instances of a given class).</p>
  50:  *
  51:  * <p>A Key pair generator for a particular algorithm creates a public/private
  52:  * key pair that can be used with this algorithm. It also associates
  53:  * algorithm-specific parameters with each of the generated keys.</p>
  54:  *
  55:  * <p>There are two ways to generate a key pair: in an algorithm-independent
  56:  * manner, and in an algorithm-specific manner. The only difference between the
  57:  * two is the initialization of the object:</p>
  58:  *
  59:  * <ul>
  60:  * <li><b>Algorithm-Independent Initialization</b><br/>
  61:  *     All key pair generators share the concepts of a <i>keysize</i> and a
  62:  *     <i>source of randomness</i>. The <i>keysize</i> is interpreted differently
  63:  *     for different algorithms (e.g., in the case of the <i>DSA</i> algorithm,
  64:  *     the <i>keysize</i> corresponds to the length of the modulus). There is an
  65:  *     <code>initialize()</code> method in this <code>KeyPairGenerator</code>
  66:  *     class that takes these two universally shared types of arguments. There
  67:  *     is also one that takes just a <i>keysize</i> argument, and uses the
  68:  *     {@link SecureRandom} implementation of the highest-priority installed
  69:  *     provider as the <i>source of randomness</i>. (If none of the installed
  70:  *     providers supply an implementation of {@link SecureRandom}, a
  71:  *     system-provided source of randomness is used.)
  72:  *
  73:  *     <p>Since no other parameters are specified when you call the above
  74:  *     algorithm-independent initialize methods, it is up to the provider what
  75:  *     to do about the algorithm-specific parameters (if any) to be associated
  76:  *     with each of the keys.</p>
  77:  *
  78:  *     <p>If the algorithm is the <i>DSA</i> algorithm, and the <i>keysize</i>
  79:  *     (modulus size) is <code>512</code>, <code>768</code>, or <code>1024</code>,
  80:  *     then the <b>GNU</b> provider uses a set of precomputed values for the
  81:  *     <code>p</code>, <code>q</code>, and <code>g</code> parameters. If the
  82:  *     <i>modulus size</i> is not one of the above values, the <b>GNU</b>
  83:  *     provider creates a new set of parameters. Other providers might have
  84:  *     precomputed parameter sets for more than just the three modulus sizes
  85:  *     mentioned above. Still others might not have a list of precomputed
  86:  *     parameters at all and instead always create new parameter sets.</p></li>
  87:  * <li><b>Algorithm-Specific Initialization</b><br/>
  88:  *     For situations where a set of algorithm-specific parameters already
  89:  *     exists (e.g., so-called <i>community parameters</i> in <i>DSA</i>), there
  90:  *     are two initialize methods that have an {@link AlgorithmParameterSpec}
  91:  *     argument. One also has a {@link SecureRandom} argument, while the the
  92:  *     other uses the {@link SecureRandom} implementation of the highest-priority
  93:  *     installed provider as the source of randomness. (If none of the installed
  94:  *     providers supply an implementation of {@link SecureRandom}, a
  95:  *     system-provided source of randomness is used.)</li>
  96:  * </ul>
  97:  *
  98:  * <p>In case the client does not explicitly initialize the
  99:  * <code>KeyPairGenerator</code> (via a call to an initialize method), each
 100:  * provider must supply (and document) a default initialization. For example,
 101:  * the <b>GNU</b> provider uses a default modulus size (keysize) of
 102:  * <code>1024</code> bits.</p>
 103:  *
 104:  * <p>Note that this class is abstract and extends from {@link
 105:  * KeyPairGeneratorSpi} for historical reasons. Application developers should
 106:  * only take notice of the methods defined in this <code>KeyPairGenerator</code>
 107:  * class; all the methods in the superclass are intended for cryptographic
 108:  * service providers who wish to supply their own implementations of key pair
 109:  * generators.</p>
 110:  *
 111:  * @see Signature
 112:  * @see KeyPair
 113:  * @see AlgorithmParameterSpec
 114:  * @author Mark Benvenuto
 115:  * @author Casey Marshall
 116:  */
 117: public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
 118: {
 119:   /** The service name for key pair generators. */
 120:   private static final String KEY_PAIR_GENERATOR = "KeyPairGenerator";
 121: 
 122:   Provider provider;
 123:   private String algorithm;
 124: 
 125:   /**
 126:    * Creates a <code>KeyPairGenerator</code> object for the specified 
 127:    * algorithm.
 128:    *
 129:    * @param algorithm the standard string name of the algorithm. 
 130:    * See Appendix A in the Java Cryptography Architecture API 
 131:    * Specification &amp; Reference for information about standard 
 132:    * algorithm names.
 133:    */
 134:   protected KeyPairGenerator(String algorithm)
 135:   {
 136:     this.algorithm = algorithm;
 137:     this.provider = null;
 138:   }
 139: 
 140:   /**
 141:    * Returns the standard name of the algorithm for this key pair generator.
 142:    * See Appendix A in the Java Cryptography Architecture API Specification
 143:    * &amp; Reference for information about standard algorithm names.
 144:    *
 145:    * @return the standard string name of the algorithm.
 146:    */
 147:   public String getAlgorithm()
 148:   {
 149:     return algorithm;
 150:   }
 151: 
 152:   /**
 153:    * Generates a <code>KeyPairGenerator</code> object that implements the
 154:    * specified digest algorithm. If the default provider package provides an
 155:    * implementation of the requested digest algorithm, an instance of
 156:    * <code>KeyPairGenerator</code> containing that implementation is returned.
 157:    * If the algorithm is not available in the default package, other packages
 158:    * are searched.
 159:    *
 160:    * @param algorithm the standard string name of the algorithm. See Appendix A
 161:    * in the Java Cryptography Architecture API Specification &amp; Reference for
 162:    * information about standard algorithm names.
 163:    * @return the new <code>KeyPairGenerator</code> object.
 164:    * @throws NoSuchAlgorithmException if the algorithm is not available in the
 165:    * environment.
 166:    */
 167:   public static KeyPairGenerator getInstance(String algorithm)
 168:     throws NoSuchAlgorithmException
 169:   {
 170:     Provider[] p = Security.getProviders();
 171:     for (int i = 0; i < p.length; i++)
 172:       {
 173:         try
 174:           {
 175:             return getInstance(algorithm, p[i]);
 176:       }
 177:     catch (NoSuchAlgorithmException e)
 178:       {
 179:         // Ignored.
 180:       }
 181:       }
 182: 
 183:     throw new NoSuchAlgorithmException(algorithm);
 184:   }
 185: 
 186:   /**
 187:    * Generates a <code>KeyPairGenerator</code> object implementing the 
 188:    * specified algorithm, as supplied from the specified provider, if 
 189:    * such an algorithm is available from the provider.
 190:    *
 191:    * @param algorithm the standard string name of the algorithm. See 
 192:    * Appendix A in the Java Cryptography Architecture API Specification 
 193:    * &amp; Reference for information about standard algorithm names.
 194:    * @param provider the string name of the provider.
 195:    * @return the new <code>KeyPairGenerator</code> object.
 196:    * @throws NoSuchAlgorithmException if the algorithm is not available 
 197:    * from the provider.
 198:    * @throws NoSuchProviderException if the provider is not available in the
 199:    * environment.
 200:    * @throws IllegalArgumentException if the provider name is <code>null</code>
 201:    * or empty.
 202:    * @see Provider
 203:    */
 204:   public static KeyPairGenerator getInstance(String algorithm, String provider)
 205:     throws NoSuchAlgorithmException, NoSuchProviderException
 206:   {
 207:     Provider p = Security.getProvider(provider);
 208:     if (p == null)
 209:       throw new NoSuchProviderException(provider);
 210: 
 211:     return getInstance(algorithm, p);
 212:   }
 213: 
 214:   /**
 215:    * Generates a <code>KeyPairGenerator</code> object implementing the specified
 216:    * algorithm, as supplied from the specified provider, if such an algorithm is
 217:    * available from the provider. Note: the provider doesn't have to be
 218:    * registered.
 219:    *
 220:    * @param algorithm the standard string name of the algorithm. See Appendix A
 221:    * in the Java Cryptography Architecture API Specification &amp; Reference for
 222:    * information about standard algorithm names.
 223:    * @param provider the provider.
 224:    * @return the new <code>KeyPairGenerator</code> object.
 225:    * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
 226:    * available from the <code>provider</code>.
 227:    * @throws IllegalArgumentException if the <code>provider</code> is
 228:    * <code>null</code>.
 229:    * @since 1.4
 230:    * @see Provider
 231:    */
 232:   public static KeyPairGenerator getInstance(String algorithm, 
 233:                          Provider provider)
 234:     throws NoSuchAlgorithmException
 235:   {
 236:     if (provider == null)
 237:       throw new IllegalArgumentException("Illegal provider");
 238: 
 239:     Object o = null;
 240:     try
 241:       {
 242:         o = Engine.getInstance(KEY_PAIR_GENERATOR, algorithm, provider);
 243:       }
 244:     catch (java.lang.reflect.InvocationTargetException ite)
 245:       {
 246:     throw new NoSuchAlgorithmException(algorithm);
 247:       }
 248: 
 249:     KeyPairGenerator result = null;
 250:     if (o instanceof KeyPairGeneratorSpi)
 251:       {
 252:     result = new DummyKeyPairGenerator((KeyPairGeneratorSpi) o, algorithm);
 253:       }
 254:     else if (o instanceof KeyPairGenerator)
 255:       {
 256:         result = (KeyPairGenerator) o;
 257:         result.algorithm = algorithm;
 258:       }
 259:     result.provider = provider;
 260:     return result;
 261:   }
 262: 
 263:   /**
 264:    * Returns the provider of this key pair generator object.
 265:    *
 266:    * @return the provider of this key pair generator object.
 267:    */
 268:   public final Provider getProvider()
 269:   {
 270:     return provider;
 271:   }
 272: 
 273:   /**
 274:    * Initializes the key pair generator for a certain keysize using a default
 275:    * parameter set and the {@link SecureRandom} implementation of the
 276:    * highest-priority installed provider as the source of randomness. (If none
 277:    * of the installed providers supply an implementation of {@link SecureRandom},
 278:    * a system-provided source of randomness is used.)
 279:    *
 280:    * @param keysize the keysize. This is an algorithm-specific metric, such as
 281:    * modulus length, specified in number of bits.
 282:    * @throws InvalidParameterException if the keysize is not supported by this
 283:    * <code>KeyPairGenerator</code> object.
 284:    */
 285:   public void initialize(int keysize)
 286:   {
 287:     initialize(keysize, new SecureRandom());
 288:   }
 289: 
 290:   /**
 291:    * Initializes the key pair generator for a certain keysize with the given
 292:    * source of randomness (and a default parameter set).
 293:    *
 294:    * @param keysize the keysize. This is an algorithm-specific metric, such as
 295:    * modulus length, specified in number of bits.
 296:    * @param random the source of randomness.
 297:    * @throws InvalidParameterException if the <code>keysize</code> is not
 298:    * supported by this <code>KeyPairGenerator</code> object.
 299:    * @since 1.2
 300:    */
 301:   public void initialize(int keysize, SecureRandom random)
 302:   {
 303:   }
 304: 
 305:   /**
 306:    * <p>Initializes the key pair generator using the specified parameter set and
 307:    * the {@link SecureRandom} implementation of the highest-priority installed
 308:    * provider as the source of randomness. (If none of the installed providers
 309:    * supply an implementation of {@link SecureRandom}, a system-provided source
 310:    * of randomness is used.)</p>
 311:    *
 312:    * <p>This concrete method has been added to this previously-defined abstract
 313:    * class. This method calls the
 314:    * {@link KeyPairGeneratorSpi#initialize(AlgorithmParameterSpec, SecureRandom)}
 315:    * initialize method, passing it <code>params</code> and a source of
 316:    * randomness (obtained from the highest-priority installed provider or
 317:    * system-provided if none of the installed providers supply one). That
 318:    * initialize method always throws an {@link UnsupportedOperationException}
 319:    * if it is not overridden by the provider.</p>
 320:    *
 321:    * @param params the parameter set used to generate the keys.
 322:    * @throws InvalidAlgorithmParameterException if the given parameters are
 323:    * inappropriate for this key pair generator.
 324:    * @since 1.2
 325:    */
 326:   public void initialize(AlgorithmParameterSpec params)
 327:     throws InvalidAlgorithmParameterException
 328:   {
 329:     initialize(params, new SecureRandom());
 330:   }
 331: 
 332:   /**
 333:    * <p>Initializes the key pair generator with the given parameter set and
 334:    * source of randomness.</p>
 335:    *
 336:    * <p>This concrete method has been added to this previously-defined abstract
 337:    * class. This method calls the
 338:    * {@link KeyPairGeneratorSpi#initialize(AlgorithmParameterSpec, SecureRandom)}
 339:    * initialize method, passing it <code>params</code> and <code>random</code>.
 340:    * That initialize method always throws an {@link UnsupportedOperationException}
 341:    * if it is not overridden by the provider.</p>
 342:    *
 343:    * @param params the parameter set used to generate the keys.
 344:    * @param random the source of randomness.
 345:    * @throws InvalidAlgorithmParameterException if the given parameters are
 346:    * inappropriate for this key pair generator.
 347:    * @since 1.2
 348:    */
 349:   public void initialize(AlgorithmParameterSpec params, SecureRandom random)
 350:     throws InvalidAlgorithmParameterException
 351:   {
 352:     super.initialize(params, random);
 353:   }
 354: 
 355:   /**
 356:    * <p>Generates a key pair.</p>
 357:    *
 358:    * <p>If this <code>KeyPairGenerator</code> has not been initialized
 359:    * explicitly, provider-specific defaults will be used for the size and other
 360:    * (algorithm-specific) values of the generated keys.</p>
 361:    *
 362:    * <p>This will generate a new key pair every time it is called.</p>
 363:    *
 364:    * <p>This method is functionally equivalent to {@link #generateKeyPair()}.</p>
 365:    *
 366:    * @return the generated key pair.
 367:    * @since 1.2
 368:    */
 369:   public final KeyPair genKeyPair()
 370:   {
 371:     try
 372:       {
 373:         return getInstance("DSA", "GNU").generateKeyPair();
 374:       }
 375:     catch (Exception e)
 376:       {
 377:         System.err.println("genKeyPair failed: " + e);
 378:         e.printStackTrace();
 379:         return null;
 380:       }
 381:   }
 382: 
 383:   /**
 384:    * <p>Generates a key pair.</p>
 385:    *
 386:    * <p>If this <code>KeyPairGenerator</code> has not been initialized
 387:    * explicitly, provider-specific defaults will be used for the size and other
 388:    * (algorithm-specific) values of the generated keys.</p>
 389:    *
 390:    * <p>This will generate a new key pair every time it is called.</p>
 391:    *
 392:    * <p>This method is functionally equivalent to {@link #genKeyPair()}.</p>
 393:    *
 394:    * @return the generated key pair.
 395:    */
 396:   public KeyPair generateKeyPair()
 397:   {
 398:     return genKeyPair();
 399:   }
 400: }