home *** CD-ROM | disk | FTP | other *** search
/ DOS/V Power Report 1998 February / VPR9802A.ISO / APP_DEMO / VC / MAIN.BIN / KeyPairGenerator.java < prev    next >
Text File  |  1997-10-27  |  7KB  |  197 lines
  1. /*
  2.  * @(#)KeyPairGenerator.java    1.9 97/02/10
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.security;
  24.  
  25. /**
  26.  * The KeyPairGenerator class is used to generate pairs of
  27.  * public and private keys. Key generators are constructed using the
  28.  * <code>getInstance</code> factory methods (static methods that
  29.  * return instances of a given class).
  30.  * 
  31.  * <p>Key generation is an area that sometimes
  32.  * does not lend itself well to algorithm independence. For example,
  33.  * it is possible to generate a DSA key pair specifying key family
  34.  * parameters (p, q and g), while it is not possible to do so for
  35.  * an RSA key pair. That is, those parameters are applicable to DSA
  36.  * but not to RSA.
  37.  * 
  38.  * <P>There are therefore two ways to generate a key pair: in an 
  39.  * algorithm-independent
  40.  * manner, and in an algorithm-specific manner. The only difference
  41.  * between the two is the initialization of the object. 
  42.  * 
  43.  * <p>All key pair generators share the concepts of a "strength" and a
  44.  * source of randomness. The measure of strength is universally shared 
  45.  * by all algorithms,
  46.  * though it is interpreted differently for different algorithms.
  47.  * The <a href = "#initialize ">initialize</a> method in this 
  48.  * KeyPairGenerator class 
  49.  * takes these two universally shared
  50.  * types of arguments. 
  51.  * 
  52.  * <p>Since no other parameters are specified when you call this
  53.  * algorithm-independent <code>initialize</code>
  54.  * method, all other values, such as algorithm parameters, public
  55.  * exponent, etc., are defaulted to standard values. 
  56.  * 
  57.  * <P>
  58.  * It is sometimes desirable to initialize a key pair generator object
  59.  * using algorithm-specific semantics. For example, you may want to
  60.  * initialize a DSA key generator for a given set of parameters 
  61.  * <code>p</code>, <code>q</code> and <code>g</code>,
  62.  * or an RSA key generator for a given public exponent.
  63.  * 
  64.  * <P>
  65.  * This is done through algorithm-specific standard interfaces. Rather than
  66.  * calling the algorithm-independent KeyPairGenerator <code>initialize</code>
  67.  * method, the key pair generator is cast to an algorithm-specific interface 
  68.  * so that one of its specialized parameter initialization methods can be
  69.  * called. An example is the DSAKeyPairGenerator interface (from
  70.  * <code>java.security.interfaces</code>).
  71.  * 
  72.  *  <p>See <a href =
  73.  * "../guide/security/CryptoSpec.html#KPG">The KeyPairGenerator Class</a> 
  74.  * in the "Java Cryptography Architecture API Specification & Reference"
  75.  * for more information and examples.
  76.  * 
  77.  * @see java.security.interfaces.DSAKeyPairGenerator
  78.  */
  79. public abstract class KeyPairGenerator {
  80.  
  81.     private String algorithm;
  82.  
  83.     /**
  84.      * Creates a KeyPairGenerator object for the specified algorithm.
  85.      *
  86.      * @param algorithm the standard string name of the algorithm. 
  87.      * See Appendix A in the <a href=
  88.      * "../guide/security/CryptoSpec.html#AppA">
  89.      * Java Cryptography Architecture API Specification & Reference </a> 
  90.      * for information about standard algorithm names.
  91.      */
  92.     protected KeyPairGenerator(String algorithm) {
  93.     this.algorithm = algorithm;
  94.     }
  95.     
  96.     /**
  97.      * Returns the standard name of the algorithm for this key generator.
  98.      * See Appendix A in the <a href=
  99.      * "../guide/security/CryptoSpec.html#AppA">
  100.      * Java Cryptography Architecture API Specification & Reference </a> 
  101.      * for information about standard algorithm names.
  102.      * 
  103.      * @return the standard string name of the algorithm. 
  104.    */
  105.     public String getAlgorithm() {
  106.     return algorithm;
  107.     }
  108.  
  109.     /**
  110.      * Generates a KeyPairGenerator object that implements the algorithm
  111.      * requested, as available in the environment.
  112.      *
  113.      * @param algorithm the standard string name of the algorithm. 
  114.      * See Appendix A in the <a href=
  115.      * "../guide/security/CryptoSpec.html#AppA">
  116.      * Java Cryptography Architecture API Specification & Reference </a> 
  117.      * for information about standard algorithm names.
  118.      *
  119.      * @return the new KeyPairGenerator object.
  120.      *
  121.      * @exception NoSuchAlgorithmException if the algorithm is
  122.      * not available in the environment.  
  123.      */
  124.     public static KeyPairGenerator getInstance(String algorithm)
  125.     throws NoSuchAlgorithmException {
  126.     try {
  127.         return (KeyPairGenerator)Security.getImpl(algorithm, 
  128.                               "KeyPairGenerator",
  129.                               null);
  130.     } catch(NoSuchProviderException e) {
  131.         throw new InternalError("please send a bug report " + 
  132.                     "to java-security@java.sun.com");
  133.     }
  134.     }
  135.  
  136.     /** 
  137.      * Generates a KeyPairGenerator object implementing the specified
  138.      * algorithm, as supplied from the specified provider, 
  139.      * if such an algorithm is available from the provider.
  140.      *
  141.      * @param algorithm the standard string name of the algorithm.
  142.      * See Appendix A in the <a href=
  143.      * "../guide/security/CryptoSpec.html#AppA">
  144.      * Java Cryptography Architecture API Specification & Reference </a> 
  145.      * for information about standard algorithm names.
  146.      *
  147.      * @param provider the string name of the provider.
  148.      *
  149.      * @return the new KeyPairGenerator object.
  150.      *
  151.      * @exception NoSuchAlgorithmException if the algorithm is
  152.      * not available from the provider.
  153.      *
  154.      * @exception NoSuchProviderException if the provider is not
  155.      * available in the environment. 
  156.      * 
  157.      * @see Provider 
  158.      */
  159.     public static KeyPairGenerator getInstance(String algorithm,
  160.                            String provider) 
  161.     throws NoSuchAlgorithmException, NoSuchProviderException {    
  162.     return (KeyPairGenerator)Security.getImpl(algorithm, 
  163.                           "KeyPairGenerator",
  164.                           provider);
  165.     }
  166.  
  167.     /**
  168.      * Initializes the key pair generator for a certain strength.
  169.      *
  170.      * @param strength the strength of the key. This is an
  171.      * algorithm-specific metric, such as modulus length.
  172.      *
  173.      * @param random the source of randomness for this generator.
  174.      */
  175.     public abstract void initialize(int strength, SecureRandom random);
  176.  
  177.     /**
  178.      * Initializes the key pair generator for a certain strength using
  179.      * a system-provided source of randomness.
  180.      *
  181.      * @param strength the strength of the key. This is an
  182.      * algorithm-specific metric, such as modulus length.
  183.      */
  184.     public void initialize(int strength) {
  185.     initialize(strength, new SecureRandom());
  186.     }
  187.  
  188.  
  189.     /**
  190.      * Generates a key pair. Unless an initialization method is called
  191.      * using a KeyPairGenerator interface, algorithm-specific defaults
  192.      * will be used. This will generate a new key pair every time it
  193.      * is called.
  194.      */
  195.     public abstract KeyPair generateKeyPair();
  196. }
  197.