home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / security / KeyPairGenerator.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  11.2 KB  |  310 lines
  1. /*
  2.  * @(#)KeyPairGenerator.java    1.31 98/03/18
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.security;
  16.  
  17. import java.security.spec.AlgorithmParameterSpec;
  18.  
  19. /**
  20.  * The KeyPairGenerator class is used to generate pairs of
  21.  * public and private keys. Key pair generators are constructed using the
  22.  * <code>getInstance</code> factory methods (static methods that
  23.  * return instances of a given class).
  24.  *
  25.  * <p>A Key pair generator for a particular algorithm creates a public/private
  26.  * key pair that can be used with this algorithm. It also associates
  27.  * algorithm-specific parameters with each of the generated keys.
  28.  * 
  29.  * <p>There are two ways to generate a key pair: in an algorithm-independent
  30.  * manner, and in an algorithm-specific manner.
  31.  * The only difference between the two is the initialization of the object:
  32.  * 
  33.  * <ul>
  34.  * <li><b>Algorithm-Independent Initialization</b>
  35.  * <p>All key pair generators share the concepts of a "strength" and a
  36.  * source of randomness. The measure of strength is universally shared 
  37.  * by all algorithms, though it is interpreted differently for different
  38.  * algorithms.
  39.  * There is an 
  40.  * <a href = "#initialize(int, java.security.SecureRandom)">initialize</a> 
  41.  * method in this KeyPairGenerator class that takes these two universally
  42.  * shared types of arguments. There is also one that takes just a
  43.  * <code>strength</code> argument, and uses a system-provided source of
  44.  * randomness.
  45.  * 
  46.  * <p>Since no other parameters are specified when you call the above
  47.  * algorithm-independent <code>initialize</code> methods, it is up to the
  48.  * provider what to do about the algorithm-specific parameters (if any) to be
  49.  * associated with each of the keys.
  50.  * 
  51.  * <p>If the algorithm is the <i>DSA</i> algorithm, and the strength (modulus
  52.  * size) is 512, 768, or 1024, then the <i>Sun</i> provider uses a set of
  53.  * precomputed values for the <code>p</code>, <code>q</code>, and
  54.  * <code>g</code> parameters. If the modulus size is not one of the above
  55.  * values, the <i>Sun</i> provider creates a new set of parameters. Other
  56.  * providers might have precomputed parameter sets for more than just the
  57.  * three modulus sizes mentioned above. Still others might not have a list of
  58.  * precomputed parameters at all and instead always create new parameter sets.
  59.  * <p>
  60.  *
  61.  * <li><b>Algorithm-Specific Initialization</b>
  62.  * <p>For situations where a set of algorithm-specific parameters already
  63.  * exists (e.g., so-called <i>community parameters</i> in DSA), there are two
  64.  * <a href = "#initialize(java.security.spec.AlgorithmParameterSpec)">
  65.  * initialize</a> methods that have an <code>AlgorithmParameterSpec</code>
  66.  * argument. One also has a <code>SecureRandom</code> argument, while the
  67.  * source of randomness is system-provided for the other.
  68.  * </ul>
  69.  *
  70.  * <p>In case the client does not explicitly initialize the KeyPairGenerator
  71.  * (via a call to an <code>initialize</code> method), each provider must
  72.  * supply (and document) a default initialization.
  73.  * For example, the <i>Sun</i> provider uses a default modulus size (strength)
  74.  * of 1024 bits.
  75.  *
  76.  * <p>Note that this class is abstract and extends from
  77.  * <code>KeyPairGeneratorSpi</code> for historical reasons.
  78.  * Application developers should only take notice of the methods defined in
  79.  * this <code>KeyPairGenerator</code> class, and ignore all the methods in
  80.  * the superclass.
  81.  *
  82.  * @author Benjamin Renaud
  83.  *
  84.  * @version 1.31, 98/03/18
  85.  *
  86.  * @see java.security.spec.AlgorithmParameterSpec
  87.  */
  88.  
  89. public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
  90.  
  91.     private String algorithm;
  92.  
  93.     // The provider
  94.     private Provider provider;
  95.  
  96.     /**
  97.      * Creates a KeyPairGenerator object for the specified algorithm.
  98.      *
  99.      * @param algorithm the standard string name of the algorithm. 
  100.      * See Appendix A in the <a href=
  101.      * "../guide/security/CryptoSpec.html#AppA">
  102.      * Java Cryptography Architecture API Specification & Reference </a> 
  103.      * for information about standard algorithm names.
  104.      */
  105.     protected KeyPairGenerator(String algorithm) {
  106.     this.algorithm = algorithm;
  107.     }
  108.     
  109.     /**
  110.      * Returns the standard name of the algorithm for this key pair generator.
  111.      * See Appendix A in the <a href=
  112.      * "../guide/security/CryptoSpec.html#AppA">
  113.      * Java Cryptography Architecture API Specification & Reference </a> 
  114.      * for information about standard algorithm names.
  115.      * 
  116.      * @return the standard string name of the algorithm. 
  117.      */
  118.     public String getAlgorithm() {
  119.     return this.algorithm;
  120.     }
  121.  
  122.     /**
  123.      * Generates a KeyPairGenerator object that implements the specified digest
  124.      * algorithm. If the default provider package
  125.      * provides an implementation of the requested digest algorithm,
  126.      * an instance of KeyPairGenerator containing that implementation is returned.
  127.      * If the algorithm is not available in the default 
  128.      * package, other packages are searched.
  129.      *
  130.      * @param algorithm the standard string name of the algorithm. 
  131.      * See Appendix A in the <a href=
  132.      * "../guide/security/CryptoSpec.html#AppA">
  133.      * Java Cryptography Architecture API Specification & Reference </a> 
  134.      * for information about standard algorithm names.
  135.      *
  136.      * @return the new KeyPairGenerator object.
  137.      *
  138.      * @exception NoSuchAlgorithmException if the algorithm is
  139.      * not available in the environment.  
  140.      */
  141.     public static KeyPairGenerator getInstance(String algorithm)
  142.     throws NoSuchAlgorithmException {
  143.     try {
  144.         Object[] objs = Security.getImpl(algorithm, "KeyPairGenerator",
  145.                          null);
  146.         if (objs[0] instanceof KeyPairGenerator) {
  147.         KeyPairGenerator keyPairGen = (KeyPairGenerator)objs[0];
  148.         keyPairGen.provider = (Provider)objs[1];
  149.         return keyPairGen;
  150.         } else {
  151.         Delegate delegate = new Delegate((KeyPairGeneratorSpi)objs[0],
  152.                          algorithm);
  153.         delegate.provider = (Provider)objs[1];
  154.         return delegate;
  155.         }
  156.     } catch(NoSuchProviderException e) {
  157.         throw new NoSuchAlgorithmException(algorithm + " not found");
  158.     }
  159.     }
  160.  
  161.     /** 
  162.      * Generates a KeyPairGenerator object implementing the specified
  163.      * algorithm, as supplied from the specified provider, 
  164.      * if such an algorithm is available from the provider.
  165.      *
  166.      * @param algorithm the standard string name of the algorithm.
  167.      * See Appendix A in the <a href=
  168.      * "../guide/security/CryptoSpec.html#AppA">
  169.      * Java Cryptography Architecture API Specification & Reference </a> 
  170.      * for information about standard algorithm names.
  171.      *
  172.      * @param provider the string name of the provider.
  173.      *
  174.      * @return the new KeyPairGenerator object.
  175.      *
  176.      * @exception NoSuchAlgorithmException if the algorithm is
  177.      * not available from the provider.
  178.      *
  179.      * @exception NoSuchProviderException if the provider is not
  180.      * available in the environment. 
  181.      * 
  182.      * @see Provider 
  183.      */
  184.     public static KeyPairGenerator getInstance(String algorithm,
  185.                            String provider) 
  186.     throws NoSuchAlgorithmException, NoSuchProviderException {    
  187.     Object[] objs = Security.getImpl(algorithm, "KeyPairGenerator",
  188.                      provider);
  189.     if (objs[0] instanceof KeyPairGenerator) {
  190.         KeyPairGenerator keyPairGen = (KeyPairGenerator)objs[0];
  191.         keyPairGen.provider = (Provider)objs[1];
  192.         return keyPairGen;
  193.     } else {
  194.         Delegate delegate = new Delegate((KeyPairGeneratorSpi)objs[0],
  195.                          algorithm);
  196.         delegate.provider = (Provider)objs[1];
  197.         return delegate;
  198.     }
  199.     }
  200.  
  201.     /** 
  202.      * Returns the provider of this key pair generator object.
  203.      * 
  204.      * @return the provider of this key pair generator object
  205.      */
  206.     public final Provider getProvider() {
  207.     return this.provider;
  208.     }
  209.  
  210.     /**
  211.      * Initializes the key pair generator for a certain strength using
  212.      * a system-provided source of randomness and the default parameter set.
  213.      *
  214.      * @param strength the strength of the key. This is an
  215.      * algorithm-specific metric, such as modulus length, specified in
  216.      * number of bits.
  217.      */
  218.     public void initialize(int strength) {
  219.     initialize(strength, new SecureRandom());
  220.     }
  221.  
  222.     /**
  223.      * Initializes the key pair generator using the specified parameter 
  224.      * set and a system-provided source of randomness.
  225.      *
  226.      * <p>This concrete method has been added to this previously-defined
  227.      * abstract class.
  228.      * This method calls <a href =
  229.      * "KeyPairGeneratorSpi#
  230.      * initialize(java.security.spec.AlgorithmParameterSpec,
  231.      * java.security.SecureRandom)">initialize</a>, 
  232.      * passing it <code>params</code> and a 
  233.      * system-provided source of randomness. That <code>initialize</code>
  234.      * method always throws an
  235.      * UnsupportedOperationException if it is not overridden by the provider.
  236.      *
  237.      * @param params the parameter set used to generate the keys.
  238.      *
  239.      * @exception InvalidAlgorithmParameterException if the given parameters
  240.      * are inappropriate for this key pair generator.
  241.      *
  242.      * @since JDK1.2
  243.      */
  244.     public void initialize(AlgorithmParameterSpec params)
  245.     throws InvalidAlgorithmParameterException {
  246.         initialize(params, new SecureRandom());
  247.     }
  248.  
  249.     /**
  250.      * Generates a key pair. Unless an initialization method is called
  251.      * using a KeyPairGenerator interface, algorithm-specific defaults
  252.      * will be used. This will generate a new key pair every time it
  253.      * is called.
  254.      *
  255.      * @return the generated key pair
  256.      *
  257.      * @since JDK1.2
  258.      */
  259.     public final KeyPair genKeyPair() {
  260.     return generateKeyPair();
  261.     }
  262.  
  263.  
  264.  
  265.  
  266.     /*
  267.      * The following class allows providers to extend from KeyPairGeneratorSpi
  268.      * rather than from KeyPairGenerator. It represents a KeyPairGenerator
  269.      * with an encapsulated, provider-supplied SPI object (of type
  270.      * KeyPairGeneratorSpi).
  271.      * If the provider implementation is an instance of KeyPairGeneratorSpi,
  272.      * the getInstance() methods above return an instance of this class, with
  273.      * the SPI object encapsulated.
  274.      *
  275.      * Note: All SPI methods from the original KeyPairGenerator class have been
  276.      * moved up the hierarchy into a new class (KeyPairGeneratorSpi), which has
  277.      * been interposed in the hierarchy between the API (KeyPairGenerator)
  278.      * and its original parent (Object).
  279.      */
  280.  
  281.     static class Delegate extends KeyPairGenerator {
  282.  
  283.     // The provider implementation (delegate)
  284.     private KeyPairGeneratorSpi kpairGenSpi;
  285.  
  286.     // constructor
  287.     public Delegate(KeyPairGeneratorSpi kpairGenSpi, String algorithm) {
  288.         super(algorithm);
  289.         this.kpairGenSpi = kpairGenSpi;
  290.     }
  291.     
  292.     // engine method
  293.     public void initialize(int strength, SecureRandom random) {
  294.         kpairGenSpi.initialize(strength, random);
  295.     }
  296.  
  297.     // engine method
  298.     public void initialize(AlgorithmParameterSpec params,
  299.                    SecureRandom random)
  300.         throws InvalidAlgorithmParameterException {
  301.         kpairGenSpi.initialize(params, random);;
  302.     }
  303.  
  304.     // engine method
  305.     public KeyPair generateKeyPair() {
  306.         return kpairGenSpi.generateKeyPair();
  307.     }
  308.     }
  309. }
  310.