1. /*

  2.  * @(#)KeyStoreSpi.java	1.9 00/02/02

  3.  *

  4.  * Copyright 1998-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.security;

  12. 

  13. import java.io.*;

  14. import java.security.cert.Certificate;

  15. import java.security.cert.CertificateException;

  16. import java.util.*;

  17. 

  18. /**

  19.  * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)

  20.  * for the <code>KeyStore</code> class.

  21.  * All the abstract methods in this class must be implemented by each

  22.  * cryptographic service provider who wishes to supply the implementation

  23.  * of a keystore for a particular keystore type.

  24.  *

  25.  * @author Jan Luehe

  26.  *

  27.  * @version 1.9, 02/02/00

  28.  *

  29.  * @see KeyStore

  30.  *

  31.  * @since 1.2

  32.  */

  33. 

  34. public abstract class KeyStoreSpi {

  35. 

  36.     /**

  37.      * Returns the key associated with the given alias, using the given

  38.      * password to recover it.

  39.      *

  40.      * @param alias the alias name

  41.      * @param password the password for recovering the key

  42.      *

  43.      * @return the requested key, or null if the given alias does not exist

  44.      * or does not identify a <i>key entry</i>.

  45.      *

  46.      * @exception NoSuchAlgorithmException if the algorithm for recovering the

  47.      * key cannot be found

  48.      * @exception UnrecoverableKeyException if the key cannot be recovered

  49.      * (e.g., the given password is wrong).

  50.      */

  51.     public abstract Key engineGetKey(String alias, char[] password)

  52. 	throws NoSuchAlgorithmException, UnrecoverableKeyException;

  53. 

  54.     /**

  55.      * Returns the certificate chain associated with the given alias.

  56.      *

  57.      * @param alias the alias name

  58.      *

  59.      * @return the certificate chain (ordered with the user's certificate first

  60.      * and the root certificate authority last), or null if the given alias

  61.      * does not exist or does not contain a certificate chain (i.e., the given

  62.      * alias identifies either a <i>trusted certificate entry</i> or a

  63.      * <i>key entry</i> without a certificate chain).

  64.      */

  65.     public abstract Certificate[] engineGetCertificateChain(String alias);

  66. 

  67.     /**

  68.      * Returns the certificate associated with the given alias.

  69.      *

  70.      * <p>If the given alias name identifies a

  71.      * <i>trusted certificate entry</i>, the certificate associated with that

  72.      * entry is returned. If the given alias name identifies a

  73.      * <i>key entry</i>, the first element of the certificate chain of that

  74.      * entry is returned, or null if that entry does not have a certificate

  75.      * chain.

  76.      *

  77.      * @param alias the alias name

  78.      *

  79.      * @return the certificate, or null if the given alias does not exist or

  80.      * does not contain a certificate.

  81.      */

  82.     public abstract Certificate engineGetCertificate(String alias);

  83. 

  84.     /**

  85.      * Returns the creation date of the entry identified by the given alias.

  86.      *

  87.      * @param alias the alias name

  88.      *

  89.      * @return the creation date of this entry, or null if the given alias does

  90.      * not exist

  91.      */

  92.     public abstract Date engineGetCreationDate(String alias);

  93. 

  94.     /**

  95.      * Assigns the given key to the given alias, protecting it with the given

  96.      * password.

  97.      *

  98.      * <p>If the given key is of type <code>java.security.PrivateKey</code>,

  99.      * it must be accompanied by a certificate chain certifying the

  100.      * corresponding public key.

  101.      *

  102.      * <p>If the given alias already exists, the keystore information

  103.      * associated with it is overridden by the given key (and possibly

  104.      * certificate chain).

  105.      *

  106.      * @param alias the alias name

  107.      * @param key the key to be associated with the alias

  108.      * @param password the password to protect the key

  109.      * @param chain the certificate chain for the corresponding public

  110.      * key (only required if the given key is of type

  111.      * <code>java.security.PrivateKey</code>).

  112.      *

  113.      * @exception KeyStoreException if the given key cannot be protected, or

  114.      * this operation fails for some other reason

  115.      */

  116.     public abstract void engineSetKeyEntry(String alias, Key key,

  117. 					   char[] password,

  118. 					   Certificate[] chain)

  119. 	throws KeyStoreException;

  120. 

  121.     /**

  122.      * Assigns the given key (that has already been protected) to the given

  123.      * alias.

  124.      *

  125.      * <p>If the protected key is of type

  126.      * <code>java.security.PrivateKey</code>,

  127.      * it must be accompanied by a certificate chain certifying the

  128.      * corresponding public key.

  129.      *

  130.      * <p>If the given alias already exists, the keystore information

  131.      * associated with it is overridden by the given key (and possibly

  132.      * certificate chain).

  133.      *

  134.      * @param alias the alias name

  135.      * @param key the key (in protected format) to be associated with the alias

  136.      * @param chain the certificate chain for the corresponding public

  137.      * key (only useful if the protected key is of type

  138.      * <code>java.security.PrivateKey</code>).

  139.      *

  140.      * @exception KeyStoreException if this operation fails.

  141.      */

  142.     public abstract void engineSetKeyEntry(String alias, byte[] key,

  143. 					   Certificate[] chain)

  144. 	throws KeyStoreException;

  145. 

  146.     /**

  147.      * Assigns the given certificate to the given alias.

  148.      *

  149.      * <p>If the given alias already exists in this keystore and identifies a

  150.      * <i>trusted certificate entry</i>, the certificate associated with it is

  151.      * overridden by the given certificate.

  152.      *

  153.      * @param alias the alias name

  154.      * @param cert the certificate

  155.      *

  156.      * @exception KeyStoreException if the given alias already exists and does

  157.      * not identify a <i>trusted certificate entry</i>, or this operation

  158.      * fails for some other reason.

  159.      */

  160.     public abstract void engineSetCertificateEntry(String alias,

  161. 						   Certificate cert)

  162. 	throws KeyStoreException;

  163. 

  164.     /**

  165.      * Deletes the entry identified by the given alias from this keystore.

  166.      *

  167.      * @param alias the alias name

  168.      *

  169.      * @exception KeyStoreException if the entry cannot be removed.

  170.      */

  171.     public abstract void engineDeleteEntry(String alias)

  172. 	throws KeyStoreException;

  173. 

  174.     /**

  175.      * Lists all the alias names of this keystore.

  176.      *

  177.      * @return enumeration of the alias names

  178.      */

  179.     public abstract Enumeration	engineAliases();

  180. 

  181.     /**

  182.      * Checks if the given alias exists in this keystore.

  183.      *

  184.      * @param alias the alias name

  185.      *

  186.      * @return true if the alias exists, false otherwise

  187.      */

  188.     public abstract boolean engineContainsAlias(String alias);

  189. 

  190.     /**

  191.      * Retrieves the number of entries in this keystore.

  192.      *

  193.      * @return the number of entries in this keystore

  194.      */

  195.     public abstract int engineSize();

  196. 

  197.     /**

  198.      * Returns true if the entry identified by the given alias is a

  199.      * <i>key entry</i>, and false otherwise.

  200.      *

  201.      * @param alias the alias for the keystore entry to be checked

  202.      *

  203.      * @return true if the entry identified by the given alias is a

  204.      * <i>key entry</i>, false otherwise.

  205.      */

  206.     public abstract boolean engineIsKeyEntry(String alias);

  207. 

  208.     /**

  209.      * Returns true if the entry identified by the given alias is a

  210.      * <i>trusted certificate entry</i>, and false otherwise.

  211.      *

  212.      * @param alias the alias for the keystore entry to be checked

  213.      *

  214.      * @return true if the entry identified by the given alias is a

  215.      * <i>trusted certificate entry</i>, false otherwise.

  216.      */

  217.     public abstract boolean engineIsCertificateEntry(String alias);

  218. 

  219.     /**

  220.      * Returns the (alias) name of the first keystore entry whose certificate

  221.      * matches the given certificate.

  222.      *

  223.      * <p>This method attempts to match the given certificate with each

  224.      * keystore entry. If the entry being considered

  225.      * is a <i>trusted certificate entry</i>, the given certificate is

  226.      * compared to that entry's certificate. If the entry being considered is

  227.      * a <i>key entry</i>, the given certificate is compared to the first

  228.      * element of that entry's certificate chain (if a chain exists).

  229.      *

  230.      * @param cert the certificate to match with.

  231.      *

  232.      * @return the (alias) name of the first entry with matching certificate,

  233.      * or null if no such entry exists in this keystore.

  234.      */

  235.     public abstract String engineGetCertificateAlias(Certificate cert);

  236. 

  237.     /**

  238.      * Stores this keystore to the given output stream, and protects its

  239.      * integrity with the given password.

  240.      *

  241.      * @param stream the output stream to which this keystore is written.

  242.      * @param password the password to generate the keystore integrity check

  243.      *

  244.      * @exception IOException if there was an I/O problem with data

  245.      * @exception NoSuchAlgorithmException if the appropriate data integrity

  246.      * algorithm could not be found

  247.      * @exception CertificateException if any of the certificates included in

  248.      * the keystore data could not be stored

  249.      */

  250.     public abstract void engineStore(OutputStream stream, char[] password)

  251. 	throws IOException, NoSuchAlgorithmException, CertificateException;

  252. 

  253.     /**

  254.      * Loads the keystore from the given input stream.

  255.      *

  256.      * <p>If a password is given, it is used to check the integrity of the

  257.      * keystore data. Otherwise, the integrity of the keystore is not checked.

  258.      *

  259.      * @param stream the input stream from which the keystore is loaded

  260.      * @param password the (optional) password used to check the integrity of

  261.      * the keystore.

  262.      *

  263.      * @exception IOException if there is an I/O or format problem with the

  264.      * keystore data

  265.      * @exception NoSuchAlgorithmException if the algorithm used to check

  266.      * the integrity of the keystore cannot be found

  267.      * @exception CertificateException if any of the certificates in the

  268.      * keystore could not be loaded

  269.      */

  270.     public abstract void engineLoad(InputStream stream, char[] password)

  271. 	throws IOException, NoSuchAlgorithmException, CertificateException;

  272. }