home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / security / KeyStore.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  10.7 KB  |  308 lines
  1. /*
  2.  * @(#)KeyStore.java    1.6 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.io.*;
  18. import java.security.cert.Certificate;
  19. import java.security.cert.CertificateException;
  20. import java.util.*;
  21.  
  22. /**
  23.  * This abstract class represents an in-memory collection of private keys and
  24.  * associated certificate chains, for use in self-authentication.
  25.  * These keys and certificate chains are used by a given entity when it
  26.  * authenticates itself using public key certificates.
  27.  *
  28.  * <P> Applications for this authentication include software
  29.  * distribution organizations which sign JAR files as part of releasing
  30.  * and/or licensing software.
  31.  *
  32.  * <P> Each private key, and associated certificate chain, is
  33.  * identified by an "alias" string. These strings distinguish among
  34.  * the different ways in which the entity may authenticate itself.
  35.  * For example, the entity may authenticate itself using different
  36.  * certificate authorities, or using different public key algorithms.
  37.  *
  38.  * <P> This abstract class also manages trusted keys, which are used to
  39.  * authenticate other parties.
  40.  *
  41.  * <P> Whether keystores are persistent, and the mechanisms used by the
  42.  * keystore if it is persistent, are not specified here. This allows
  43.  * use of a variety of techniques for protecting private keys. Smart
  44.  * cards or other integrated cryptographic engines (SafeKeyper) are one
  45.  * option, and simpler mechanisms such as files with encrypted private
  46.  * keys may also be used (in a variety of formats).
  47.  *
  48.  * <P> In-memory instances of this class should be protected as strongly
  49.  * as the private keys to which they provide access.
  50.  *
  51.  * @author Jan Luehe
  52.  *
  53.  * @version 1.6, 03/18/98
  54.  *
  55.  * @since JDK1.2
  56.  */
  57.  
  58. public abstract class KeyStore {
  59.  
  60.     /*
  61.      * Keyword to look up in the security properties file.
  62.      * In the security properties file, the default implementation
  63.      * for KeyStore is given as:
  64.      * <pre>
  65.      * keystore=sun.security.tools.JavaKeyStore
  66.      * </pre>
  67.      */
  68.     private static final String KEYSTORE_PROVIDER = "keystore";
  69.  
  70.     /**
  71.      * Returns a new KeyStore object of the type configured in the
  72.      * security properties file for <code>keystore</code>. If the security
  73.      * properties file does not contain an entry for <code>keystore</code>,
  74.      * an instance of the default KeyStore implementation
  75.      * (sun.security.tools.JavaKeyStore) is returned.
  76.      *
  77.      * @return the new KeyStore object
  78.      *
  79.      * @exception KeyStoreException if the KeyStore object cannot be created
  80.      */
  81.     public static final KeyStore getInstance() throws KeyStoreException {
  82.     String className = null;
  83.  
  84.     try {
  85.         AccessController.beginPrivileged();
  86.         className = Security.getProperty(KEYSTORE_PROVIDER);
  87.     } finally {
  88.         AccessController.endPrivileged();
  89.     }
  90.  
  91.     if (className == null) {
  92.         className = "sun.security.tools.JavaKeyStore";
  93.     }
  94.  
  95.     try {
  96.         Class cl = Class.forName(className);
  97.         return (KeyStore)cl.newInstance();
  98.     } catch (ClassNotFoundException e) {
  99.         throw new KeyStoreException("Could not find class: " + e);
  100.     } catch (IllegalAccessException e) {
  101.         throw new KeyStoreException("Could not access class: " + e);
  102.     } catch (InstantiationException e) {
  103.         throw new KeyStoreException("Problems instantiating: " + e);
  104.     }
  105.     }
  106.  
  107.     /**
  108.      * Returns the private key associated with the given alias. The private key
  109.      * is recovered using the given password.
  110.      *
  111.      * @param alias the alias name
  112.      * @param password the password for recovering the key
  113.      *
  114.      * @return the private key, or null if the given alias does not exist,
  115.      * or the given alias does not have a private key
  116.      *
  117.      * @exception NoSuchAlgorithmException if the algorithm for recovering the
  118.      * private key could not be found
  119.      * @exception UnrecoverableKeyException if the private key could not be
  120.      * recovered
  121.      */
  122.     public abstract PrivateKey getPrivateKey(String alias, String password)
  123.     throws NoSuchAlgorithmException, UnrecoverableKeyException;
  124.  
  125.     /**
  126.      * Returns the certificate chain associated with the given alias.
  127.      *
  128.      * @param alias the alias name
  129.      *
  130.      * @return the certificate chain (ordered with the user's certificate first
  131.      * and the root certificate authority last), or null if the given alias
  132.      * does not exist
  133.      */
  134.     public abstract Certificate[] getCertificateChain(String alias);
  135.  
  136.     /**
  137.      * Returns the certificate associated with the given alias.
  138.      *
  139.      * @param alias the alias name
  140.      *
  141.      * @return the certificate, or null if the given alias does not exist
  142.      */
  143.     public abstract Certificate getCertificate(String alias);
  144.  
  145.     /**
  146.      * Returns the creation date of the entry identified by the given alias.
  147.      *
  148.      * @param alias the alias name
  149.      *
  150.      * @return the creation date of this entry, or null if the given alias does
  151.      * not exist
  152.      */
  153.     public abstract Date getCreationDate(String alias);
  154.  
  155.     /**
  156.      * Assigns a private key and certificate chain to the given alias.
  157.      *
  158.      * The alias may already exist, in which case the private key and
  159.      * certificate chain associated with it are replaced by the private key
  160.      * and certificate chain provided in this call.
  161.      * The private key is protected with the given password.
  162.      *
  163.      * @param alias the alias name
  164.      * @param key the private key to be associated with the alias
  165.      * @param password the password to protect the private key
  166.      * @param chain the certificate chain to be associated with the alias
  167.      *
  168.      * @exception KeyStoreException if the private key cannot be protected, or
  169.      * this operation failed for some other reason
  170.      */
  171.     public abstract void setKeyEntry(String alias, PrivateKey key,
  172.                      String password, Certificate chain[])
  173.     throws KeyStoreException;
  174.  
  175.     /**
  176.      * Assigns a protected private key and certificate chain to the given
  177.      * alias.
  178.      *
  179.      * The alias may already exist, in which case the private key and
  180.      * certificate chain associated with it are replaced by the private key
  181.      * and certificate chain provided in this call.
  182.      *
  183.      * @param alias the alias name
  184.      * @param key the protected private key to be associated with the alias
  185.      * @param chain the certificate chain to be associated with the alias
  186.      *
  187.      * @exception KeyStoreException if this operation failed
  188.      */
  189.     public abstract void setKeyEntry(String alias, byte[] key,
  190.                      Certificate chain[])
  191.     throws KeyStoreException;
  192.  
  193.     /**
  194.      * Assigns a certificate to the given alias.
  195.      *
  196.      * The alias may already exist, in which case the certificate associated
  197.      * with it is replaced by the certificate provided in this call.
  198.      *
  199.      * @param alias the alias name
  200.      * @param cert the certificate to be added
  201.      *
  202.      * @exception KeyStoreException if the given alias identifies a private key
  203.      * entry, or this operation failed for some other reason
  204.      */
  205.     public abstract void setCertificateEntry(String alias, Certificate cert)
  206.     throws KeyStoreException;
  207.  
  208.     /**
  209.      * Deletes the entry identified by alias.
  210.      *
  211.      * @param alias the alias name
  212.      *
  213.      * @exception KeyStoreException if the entry could not be removed
  214.      */
  215.     public abstract void deleteEntry(String alias)
  216.     throws KeyStoreException;
  217.  
  218.     /**
  219.      * Lists the alias names.
  220.      *
  221.      * @return enumeration of the alias names
  222.      */
  223.     public abstract Enumeration    aliases();
  224.  
  225.     /**
  226.      * Checks if alias exists.
  227.      *
  228.      * @param alias the alias name
  229.      *
  230.      * @return true if the alias exists, false otherwise
  231.      */
  232.     public abstract boolean containsAlias(String alias);
  233.  
  234.     /**
  235.      * Retrieves the number of elements in this keystore.
  236.      *
  237.      * @return the number of elements in this keystore
  238.      */
  239.     public abstract int size();
  240.  
  241.     /**
  242.      * Returns true if the entry identified by the given alias is a private
  243.      * key entry, and false otherwise.
  244.      *
  245.      * @return true if the entry identified by the given alias is a private
  246.      * key entry, false otherwise.
  247.      */
  248.     public abstract boolean isKeyEntry(String alias);
  249.  
  250.     /**
  251.      * Returns true if the entry identified by the given alias is a
  252.      * certificate entry, and false otherwise.
  253.      *
  254.      * @return true if the entry identified by the given alias is a
  255.      * certificate entry, false otherwise.
  256.      */
  257.     public abstract boolean isCertificateEntry(String alias);
  258.  
  259.     /**
  260.      * Returns the (alias) name of the first entry whose certificate matches
  261.      * the given certificate.
  262.      *
  263.      * @param cert the certificate to compare against 
  264.      *
  265.      * @return the (alias) name of the first entry with matching certificate,
  266.      * or null if there is no such entry
  267.      */
  268.     public abstract String getCertificateAlias(Certificate cert);
  269.  
  270.     /**
  271.      * Stores the keystore data into an output stream.
  272.      *
  273.      * An integrity check is created using the given password, and appended
  274.      * to the stream. Such streams would typically come from a file or a URL.
  275.      *
  276.      * @param stream the stream to which an encrypted keystore will be written.
  277.      * @param password the password to generate the integrity check
  278.      *
  279.      * @exception IOException if there was an I/O problem with data
  280.      * @exception NoSuchAlgorithmException if the appropriate data integrity
  281.      * algorithm could not be found
  282.      * @exception CertificateException if any of the certificates included in
  283.      * the keystore data could not be stored
  284.      */
  285.     public abstract void store(OutputStream stream, String password)
  286.     throws IOException, NoSuchAlgorithmException, CertificateException;
  287.  
  288.     /**
  289.      * Loads the keystore from an input stream.
  290.      *
  291.      * The integrity of the keystore data is checked using the given
  292.      * password.
  293.      * Such streams would typically come from a file or a URL.
  294.      *
  295.      * @param stream the input stream holding an encrypted keystore
  296.      * @param password the password used to check the integrity of the
  297.      * keystore data
  298.      *
  299.      * @exception IOException if there was an I/O or format problem with data
  300.      * @exception NoSuchAlgorithmException if the appropriate data integrity
  301.      * algorithm could not be found
  302.      * @exception CertificateException if any of the certificates included in
  303.      * the keystore data could not be loaded
  304.      */
  305.     public abstract void load(InputStream stream, String password)
  306.     throws IOException, NoSuchAlgorithmException, CertificateException;
  307. }
  308.