1. /*

  2.  * @(#)KeyStoreSpi.java	1.5 01/11/29

  3.  *

  4.  * Copyright 2002 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.security;

  9. 

  10. import java.io.*;

  11. import java.security.cert.Certificate;

  12. import java.security.cert.CertificateException;

  13. import java.util.*;

  14. 

  15. /**

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

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

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

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

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

  21.  *

  22.  * @author Jan Luehe

  23.  *

  24.  * @version 1.5, 11/29/01

  25.  *

  26.  * @see KeyStore

  27.  *

  28.  * @since JDK1.2

  29.  */

  30. 

  31. public abstract class KeyStoreSpi {

  32. 

  33.     /**

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

  35.      * password to recover it.

  36.      *

  37.      * @param alias the alias name

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

  39.      *

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

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

  42.      *

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

  44.      * key cannot be found

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

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

  47.      */

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

  49. 	throws NoSuchAlgorithmException, UnrecoverableKeyException;

  50. 

  51.     /**

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

  53.      *

  54.      * @param alias the alias name

  55.      *

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

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

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

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

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

  61.      */

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

  63. 

  64.     /**

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

  66.      *

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

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

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

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

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

  72.      * chain.

  73.      *

  74.      * @param alias the alias name

  75.      *

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

  77.      * does not contain a certificate.

  78.      */

  79.     public abstract Certificate engineGetCertificate(String alias);

  80. 

  81.     /**

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

  83.      *

  84.      * @param alias the alias name

  85.      *

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

  87.      * not exist

  88.      */

  89.     public abstract Date engineGetCreationDate(String alias);

  90. 

  91.     /**

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

  93.      * password.

  94.      *

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

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

  97.      * corresponding public key.

  98.      *

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

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

  101.      * certificate chain).

  102.      *

  103.      * @param alias the alias name

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

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

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

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

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

  109.      *

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

  111.      * this operation fails for some other reason

  112.      */

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

  114. 					   char[] password,

  115. 					   Certificate[] chain)

  116. 	throws KeyStoreException;

  117. 

  118.     /**

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

  120.      * alias.

  121.      *

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

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

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

  125.      * corresponding public key.

  126.      *

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

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

  129.      * certificate chain).

  130.      *

  131.      * @param alias the alias name

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

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

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

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

  136.      *

  137.      * @exception KeyStoreException if this operation fails.

  138.      */

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

  140. 					   Certificate[] chain)

  141. 	throws KeyStoreException;

  142. 

  143.     /**

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

  145.      *

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

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

  148.      * overridden by the given certificate.

  149.      *

  150.      * @param alias the alias name

  151.      * @param cert the certificate

  152.      *

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

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

  155.      * fails for some other reason.

  156.      */

  157.     public abstract void engineSetCertificateEntry(String alias,

  158. 						   Certificate cert)

  159. 	throws KeyStoreException;

  160. 

  161.     /**

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

  163.      *

  164.      * @param alias the alias name

  165.      *

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

  167.      */

  168.     public abstract void engineDeleteEntry(String alias)

  169. 	throws KeyStoreException;

  170. 

  171.     /**

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

  173.      *

  174.      * @return enumeration of the alias names

  175.      */

  176.     public abstract Enumeration	engineAliases();

  177. 

  178.     /**

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

  180.      *

  181.      * @param alias the alias name

  182.      *

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

  184.      */

  185.     public abstract boolean engineContainsAlias(String alias);

  186. 

  187.     /**

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

  189.      *

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

  191.      */

  192.     public abstract int engineSize();

  193. 

  194.     /**

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

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

  197.      *

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

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

  200.      */

  201.     public abstract boolean engineIsKeyEntry(String alias);

  202. 

  203.     /**

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

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

  206.      *

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

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

  209.      */

  210.     public abstract boolean engineIsCertificateEntry(String alias);

  211. 

  212.     /**

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

  214.      * matches the given certificate.

  215.      *

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

  217.      * keystore entry. If the entry being considered

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

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

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

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

  222.      *

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

  224.      *

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

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

  227.      */

  228.     public abstract String engineGetCertificateAlias(Certificate cert);

  229. 

  230.     /**

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

  232.      * integrity with the given password.

  233.      *

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

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

  236.      *

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

  238.      * @exception NoSuchAlgorithmException if the appropriate data integrity

  239.      * algorithm could not be found

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

  241.      * the keystore data could not be stored

  242.      */

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

  244. 	throws IOException, NoSuchAlgorithmException, CertificateException;

  245. 

  246.     /**

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

  248.      *

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

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

  251.      *

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

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

  254.      * the keystore.

  255.      *

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

  257.      * keystore data

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

  259.      * the integrity of the keystore cannot be found

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

  261.      * keystore could not be loaded

  262.      */

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

  264. 	throws IOException, NoSuchAlgorithmException, CertificateException;

  265. }