001: /*
002: * @(#)KeyStoreSpi.java 1.15 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.security;
029:
030: import java.io.*;
031: import java.security.cert.Certificate;
032: import java.security.cert.CertificateException;
033: import java.util.*;
034:
035: /**
036: * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
037: * for the <code>KeyStore</code> class.
038: * All the abstract methods in this class must be implemented by each
039: * cryptographic service provider who wishes to supply the implementation
040: * of a keystore for a particular keystore type.
041: *
042: * @author Jan Luehe
043: *
044: * @version 1.9, 02/02/00
045: *
046: * @see KeyStore
047: *
048: * @since 1.2
049: */
050:
051: public abstract class KeyStoreSpi {
052:
053: /**
054: * Returns the key associated with the given alias, using the given
055: * password to recover it.
056: *
057: * @param alias the alias name
058: * @param password the password for recovering the key
059: *
060: * @return the requested key, or null if the given alias does not exist
061: * or does not identify a <i>key entry</i>.
062: *
063: * @exception NoSuchAlgorithmException if the algorithm for recovering the
064: * key cannot be found
065: * @exception UnrecoverableKeyException if the key cannot be recovered
066: * (e.g., the given password is wrong).
067: */
068: public abstract Key engineGetKey(String alias, char[] password)
069: throws NoSuchAlgorithmException, UnrecoverableKeyException;
070:
071: /**
072: * Returns the certificate chain associated with the given alias.
073: *
074: * @param alias the alias name
075: *
076: * @return the certificate chain (ordered with the user's certificate first
077: * and the root certificate authority last), or null if the given alias
078: * does not exist or does not contain a certificate chain (i.e., the given
079: * alias identifies either a <i>trusted certificate entry</i> or a
080: * <i>key entry</i> without a certificate chain).
081: */
082: public abstract Certificate[] engineGetCertificateChain(String alias);
083:
084: /**
085: * Returns the certificate associated with the given alias.
086: *
087: * <p>If the given alias name identifies a
088: * <i>trusted certificate entry</i>, the certificate associated with that
089: * entry is returned. If the given alias name identifies a
090: * <i>key entry</i>, the first element of the certificate chain of that
091: * entry is returned, or null if that entry does not have a certificate
092: * chain.
093: *
094: * @param alias the alias name
095: *
096: * @return the certificate, or null if the given alias does not exist or
097: * does not contain a certificate.
098: */
099: public abstract Certificate engineGetCertificate(String alias);
100:
101: /**
102: * Returns the creation date of the entry identified by the given alias.
103: *
104: * @param alias the alias name
105: *
106: * @return the creation date of this entry, or null if the given alias does
107: * not exist
108: */
109: public abstract Date engineGetCreationDate(String alias);
110:
111: /**
112: * Assigns the given key to the given alias, protecting it with the given
113: * password.
114: *
115: * <p>If the given key is of type <code>java.security.PrivateKey</code>,
116: * it must be accompanied by a certificate chain certifying the
117: * corresponding public key.
118: *
119: * <p>If the given alias already exists, the keystore information
120: * associated with it is overridden by the given key (and possibly
121: * certificate chain).
122: *
123: * @param alias the alias name
124: * @param key the key to be associated with the alias
125: * @param password the password to protect the key
126: * @param chain the certificate chain for the corresponding public
127: * key (only required if the given key is of type
128: * <code>java.security.PrivateKey</code>).
129: *
130: * @exception KeyStoreException if the given key cannot be protected, or
131: * this operation fails for some other reason
132: */
133: public abstract void engineSetKeyEntry(String alias, Key key,
134: char[] password, Certificate[] chain)
135: throws KeyStoreException;
136:
137: /**
138: * Assigns the given key (that has already been protected) to the given
139: * alias.
140: *
141: * <p>If the protected key is of type
142: * <code>java.security.PrivateKey</code>,
143: * it must be accompanied by a certificate chain certifying the
144: * corresponding public key.
145: *
146: * <p>If the given alias already exists, the keystore information
147: * associated with it is overridden by the given key (and possibly
148: * certificate chain).
149: *
150: * @param alias the alias name
151: * @param key the key (in protected format) to be associated with the alias
152: * @param chain the certificate chain for the corresponding public
153: * key (only useful if the protected key is of type
154: * <code>java.security.PrivateKey</code>).
155: *
156: * @exception KeyStoreException if this operation fails.
157: */
158: public abstract void engineSetKeyEntry(String alias, byte[] key,
159: Certificate[] chain) throws KeyStoreException;
160:
161: /**
162: * Assigns the given certificate to the given alias.
163: *
164: * <p>If the given alias already exists in this keystore and identifies a
165: * <i>trusted certificate entry</i>, the certificate associated with it is
166: * overridden by the given certificate.
167: *
168: * @param alias the alias name
169: * @param cert the certificate
170: *
171: * @exception KeyStoreException if the given alias already exists and does
172: * not identify a <i>trusted certificate entry</i>, or this operation
173: * fails for some other reason.
174: */
175: public abstract void engineSetCertificateEntry(String alias,
176: Certificate cert) throws KeyStoreException;
177:
178: /**
179: * Deletes the entry identified by the given alias from this keystore.
180: *
181: * @param alias the alias name
182: *
183: * @exception KeyStoreException if the entry cannot be removed.
184: */
185: public abstract void engineDeleteEntry(String alias)
186: throws KeyStoreException;
187:
188: /**
189: * Lists all the alias names of this keystore.
190: *
191: * @return enumeration of the alias names
192: */
193: public abstract Enumeration engineAliases();
194:
195: /**
196: * Checks if the given alias exists in this keystore.
197: *
198: * @param alias the alias name
199: *
200: * @return true if the alias exists, false otherwise
201: */
202: public abstract boolean engineContainsAlias(String alias);
203:
204: /**
205: * Retrieves the number of entries in this keystore.
206: *
207: * @return the number of entries in this keystore
208: */
209: public abstract int engineSize();
210:
211: /**
212: * Returns true if the entry identified by the given alias is a
213: * <i>key entry</i>, and false otherwise.
214: *
215: * @param alias the alias for the keystore entry to be checked
216: *
217: * @return true if the entry identified by the given alias is a
218: * <i>key entry</i>, false otherwise.
219: */
220: public abstract boolean engineIsKeyEntry(String alias);
221:
222: /**
223: * Returns true if the entry identified by the given alias is a
224: * <i>trusted certificate entry</i>, and false otherwise.
225: *
226: * @param alias the alias for the keystore entry to be checked
227: *
228: * @return true if the entry identified by the given alias is a
229: * <i>trusted certificate entry</i>, false otherwise.
230: */
231: public abstract boolean engineIsCertificateEntry(String alias);
232:
233: /**
234: * Returns the (alias) name of the first keystore entry whose certificate
235: * matches the given certificate.
236: *
237: * <p>This method attempts to match the given certificate with each
238: * keystore entry. If the entry being considered
239: * is a <i>trusted certificate entry</i>, the given certificate is
240: * compared to that entry's certificate. If the entry being considered is
241: * a <i>key entry</i>, the given certificate is compared to the first
242: * element of that entry's certificate chain (if a chain exists).
243: *
244: * @param cert the certificate to match with.
245: *
246: * @return the (alias) name of the first entry with matching certificate,
247: * or null if no such entry exists in this keystore.
248: */
249: public abstract String engineGetCertificateAlias(Certificate cert);
250:
251: /**
252: * Stores this keystore to the given output stream, and protects its
253: * integrity with the given password.
254: *
255: * @param stream the output stream to which this keystore is written.
256: * @param password the password to generate the keystore integrity check
257: *
258: * @exception IOException if there was an I/O problem with data
259: * @exception NoSuchAlgorithmException if the appropriate data integrity
260: * algorithm could not be found
261: * @exception CertificateException if any of the certificates included in
262: * the keystore data could not be stored
263: */
264: public abstract void engineStore(OutputStream stream,
265: char[] password) throws IOException,
266: NoSuchAlgorithmException, CertificateException;
267:
268: /**
269: * Loads the keystore from the given input stream.
270: *
271: * <p>If a password is given, it is used to check the integrity of the
272: * keystore data. Otherwise, the integrity of the keystore is not checked.
273: *
274: * @param stream the input stream from which the keystore is loaded
275: * @param password the (optional) password used to check the integrity of
276: * the keystore.
277: *
278: * @exception IOException if there is an I/O or format problem with the
279: * keystore data
280: * @exception NoSuchAlgorithmException if the algorithm used to check
281: * the integrity of the keystore cannot be found
282: * @exception CertificateException if any of the certificates in the
283: * keystore could not be loaded
284: */
285: public abstract void engineLoad(InputStream stream, char[] password)
286: throws IOException, NoSuchAlgorithmException,
287: CertificateException;
288: }
|