GNU Classpath (0.20) | |
Frames | No Frames |
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 & 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: * & 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 & 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: * & 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 & 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: }
GNU Classpath (0.20) |