home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / security / KeyFactory.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  8.1 KB  |  242 lines
  1. /*
  2.  * @(#)KeyFactory.java    1.14 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.KeySpec;
  18. import java.security.spec.InvalidKeySpecException;
  19.  
  20. /**
  21.  * Key factories are used to convert <I>keys</I> (opaque
  22.  * cryptographic keys of type <code>Key</code>) into <I>key specifications</I>
  23.  * (transparent representations of the underlying key material), and vice
  24.  * versa.
  25.  *
  26.  * <P> Key factories are bi-directional. That is, they allow you to build an
  27.  * opaque key object from a given key specification (key material), or to
  28.  * retrieve the underlying key material of a key object in a suitable format.
  29.  *
  30.  * <P> Multiple compatible key specifications may exist for the same key.
  31.  * For example, a DSA public key may be specified using
  32.  * <code>DSAPublicKeySpec</code> or
  33.  * <code>X509EncodedKeySpec</code>. A key factory can be used to translate
  34.  * between compatible key specifications.
  35.  *
  36.  * <P> The following is an example of how to use a key factory in order to
  37.  * instantiate a DSA public key from its encoding.
  38.  * Assume Alice has received a digital signature from Bob.
  39.  * Bob also sent her his public key (in encoded format) to verify
  40.  * his signature. Alice then performs the following actions:
  41.  *
  42.  * <pre>
  43.  * X509EncodedKeySpec bobPubKeySpec = new X509EncodedKeySpec(bobEncodedPubKey);
  44.  * KeyFactory keyFactory = KeyFactory.getInstance("DSA");
  45.  * PublicKey bobPubKey = keyFactory.generatePublic(bobPubKeySpec);
  46.  * Signature sig = Signature.getInstance("DSA");
  47.  * sig.initVerify(bobPubKey);
  48.  * sig.update(data);
  49.  * sig.verify(signature);
  50.  * </pre>
  51.  *
  52.  * @author Jan Luehe
  53.  *
  54.  * @version 1.14, 98/03/18
  55.  *
  56.  * @see Key
  57.  * @see PublicKey
  58.  * @see PrivateKey
  59.  * @see java.security.spec.KeySpec
  60.  * @see java.security.spec.DSAPublicKeySpec
  61.  * @see java.security.spec.X509EncodedKeySpec
  62.  *
  63.  * @since JDK1.2
  64.  */
  65.  
  66. public class KeyFactory {
  67.  
  68.     // The algorithm associated with this key factory
  69.     private String algorithm;
  70.  
  71.     // The provider
  72.     private Provider provider;
  73.  
  74.     // The provider implementation (delegate)
  75.     private KeyFactorySpi keyFacSpi;
  76.  
  77.     /**
  78.      * Creates a KeyFactory object.
  79.      *
  80.      * @param keyFacSpi the delegate
  81.      * @param provider the provider
  82.      */
  83.     protected KeyFactory(KeyFactorySpi keyFacSpi, Provider provider,
  84.              String algorithm) {
  85.     this.keyFacSpi = keyFacSpi;
  86.     this.provider = provider;
  87.     this.algorithm = algorithm;
  88.     }
  89.  
  90.     /**
  91.      * Generates a KeyFactory object that implements the specified digest
  92.      * algorithm. If the default provider package
  93.      * provides an implementation of the requested digest algorithm,
  94.      * an instance of KeyFactory containing that implementation is returned.
  95.      * If the algorithm is not available in the default 
  96.      * package, other packages are searched.
  97.      *
  98.      * @param algorithm the name of the requested key algorithm. 
  99.      * See Appendix A in the <a href=
  100.      * "../guide/security/CryptoSpec.html#AppA">
  101.      * Java Cryptography Architecture API Specification & Reference </a> 
  102.      * for information about standard algorithm names.
  103.      *
  104.      * @return a KeyFactory object for the specified algorithm.
  105.      *
  106.      * @exception NoSuchAlgorithmException if the requested algorithm is
  107.      * not available in the default provider package or any of the other
  108.      * provider packages that were searched.  
  109.      */
  110.     public static final KeyFactory getInstance(String algorithm) 
  111.     throws NoSuchAlgorithmException { 
  112.         try {
  113.         Object[] objs = Security.getImpl(algorithm, "KeyFactory",
  114.                          null);
  115.         return new KeyFactory((KeyFactorySpi)objs[0],
  116.                       (Provider)objs[1],
  117.                       algorithm);
  118.         } catch(NoSuchProviderException e) {
  119.         throw new NoSuchAlgorithmException(algorithm + " not found");
  120.         }
  121.     }
  122.  
  123.     /**
  124.      * Generates a KeyFactory object for the specified algorithm from the
  125.      * specified provider.
  126.      *
  127.      * @param algorithm the name of the requested key algorithm. 
  128.      * See Appendix A in the <a href=
  129.      * "../guide/security/CryptoSpec.html#AppA">
  130.      * Java Cryptography Architecture API Specification & Reference </a> 
  131.      * for information about standard algorithm names.
  132.      *
  133.      * @param provider the name of the provider.
  134.      *
  135.      * @return a KeyFactory object for the specified algorithm.
  136.      *
  137.      * @exception NoSuchAlgorithmException if the algorithm is
  138.      * not available from the specified provider.
  139.      *
  140.      * @exception NoSuchProviderException if the provider has not been 
  141.      * configured. 
  142.      * 
  143.      * @see Provider 
  144.      */
  145.     public static final KeyFactory getInstance(String algorithm,
  146.                            String provider)
  147.     throws NoSuchAlgorithmException, NoSuchProviderException {
  148.         Object[] objs = Security.getImpl(algorithm, "KeyFactory",
  149.                          provider);
  150.         return new KeyFactory((KeyFactorySpi)objs[0], (Provider)objs[1],
  151.                   algorithm);
  152.     }
  153.  
  154.     /** 
  155.      * Returns the provider of this key factory object.
  156.      * 
  157.      * @return the provider of this key factory object
  158.      */
  159.     public final Provider getProvider() {
  160.     return this.provider;
  161.     }
  162.  
  163.     /**
  164.      * Returns the name of the algorithm associated with this key factory.
  165.      */
  166.     public final String getAlgorithm() {
  167.     return this.algorithm;
  168.     }
  169.  
  170.     /**
  171.      * Generates a public key object from the provided key specification
  172.      * (key material).
  173.      *
  174.      * @param keySpec the specification (key material) of the public key.
  175.      *
  176.      * @return the public key.
  177.      *
  178.      * @exception InvalidKeySpecException if the given key specification
  179.      * is inappropriate for this key factory to produce a public key.
  180.      */
  181.     public final PublicKey generatePublic(KeySpec keySpec)
  182.         throws InvalidKeySpecException {
  183.         return keyFacSpi.engineGeneratePublic(keySpec);
  184.     }
  185.  
  186.     /**
  187.      * Generates a private key object from the provided key specification
  188.      * (key material).
  189.      *
  190.      * @param keySpec the specification (key material) of the private key.
  191.      *
  192.      * @return the private key.
  193.      *
  194.      * @exception InvalidKeySpecException if the given key specification
  195.      * is inappropriate for this key factory to produce a private key.
  196.      */
  197.     public final PrivateKey generatePrivate(KeySpec keySpec)
  198.         throws InvalidKeySpecException {
  199.         return keyFacSpi.engineGeneratePrivate(keySpec);
  200.     }
  201.  
  202.     /**
  203.      * Returns a specification (key material) of the given key object.
  204.      * <code>keySpec</code> identifies the specification class in which 
  205.      * the key material should be returned. It could, for example, be
  206.      * <code>DSAPublicKeySpec.class</code>, to indicate that the
  207.      * key material should be returned in an instance of the 
  208.      * <code>DSAPublicKeySpec</code> class.
  209.      *
  210.      * @param key the key.
  211.      *
  212.      * @param keySpec the specification class in which 
  213.      * the key material should be returned.
  214.      *
  215.      * @return the underlying key specification (key material) in an instance
  216.      * of the requested specification class.
  217.      *
  218.      * @exception InvalidKeySpecException if the requested key specification is
  219.      * inappropriate for the given key, or the given key cannot be processed
  220.      * (e.g., the given key has an unrecognized algorithm or format).
  221.      */
  222.     public final KeySpec getKeySpec(Key key, Class keySpec)
  223.     throws InvalidKeySpecException {
  224.         return keyFacSpi.engineGetKeySpec(key, keySpec);
  225.     }
  226.  
  227.     /**
  228.      * Translates a key object, whose provider may be unknown or potentially
  229.      * untrusted, into a corresponding key object of this key factory.
  230.      *
  231.      * @param key the key whose provider is unknown or untrusted.
  232.      *
  233.      * @return the translated key.
  234.      *
  235.      * @exception InvalidKeyException if the given key cannot be processed
  236.      * by this key factory.
  237.      */
  238.     public final Key translateKey(Key key) throws InvalidKeyException {
  239.     return keyFacSpi.engineTranslateKey(key);
  240.     }
  241. }
  242.