1 /*
2 * Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.security;
27
28 import java.io.*;
29 import java.util.*;
30
31 import java.security.KeyStore.*;
32 import java.security.cert.Certificate;
33 import java.security.cert.CertificateException;
34
35 import javax.crypto.SecretKey;
36
37 import javax.security.auth.callback.*;
38
39 /**
40 * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
41 * for the {@code KeyStore} class.
42 * All the abstract methods in this class must be implemented by each
43 * cryptographic service provider who wishes to supply the implementation
44 * of a keystore for a particular keystore type.
45 *
46 * @author Jan Luehe
47 *
48 *
49 * @see KeyStore
50 *
51 * @since 1.2
52 */
53
54 public abstract class KeyStoreSpi {
55
56 /**
57 * Returns the key associated with the given alias, using the given
58 * password to recover it. The key must have been associated with
59 * the alias by a call to {@code setKeyEntry},
60 * or by a call to {@code setEntry} with a
61 * {@code PrivateKeyEntry} or {@code SecretKeyEntry}.
62 *
63 * @param alias the alias name
64 * @param password the password for recovering the key
65 *
66 * @return the requested key, or null if the given alias does not exist
67 * or does not identify a key-related entry.
68 *
69 * @exception NoSuchAlgorithmException if the algorithm for recovering the
70 * key cannot be found
71 * @exception UnrecoverableKeyException if the key cannot be recovered
72 * (e.g., the given password is wrong).
73 */
74 public abstract Key engineGetKey(String alias, char[] password)
75 throws NoSuchAlgorithmException, UnrecoverableKeyException;
76
77 /**
78 * Returns the certificate chain associated with the given alias.
79 * The certificate chain must have been associated with the alias
80 * by a call to {@code setKeyEntry},
81 * or by a call to {@code setEntry} with a
82 * {@code PrivateKeyEntry}.
83 *
84 * @param alias the alias name
85 *
86 * @return the certificate chain (ordered with the user's certificate first
87 * and the root certificate authority last), or null if the given alias
88 * does not exist or does not contain a certificate chain
89 */
90 public abstract Certificate[] engineGetCertificateChain(String alias);
91
92 /**
93 * Returns the certificate associated with the given alias.
94 *
95 * <p> If the given alias name identifies an entry
96 * created by a call to {@code setCertificateEntry},
97 * or created by a call to {@code setEntry} with a
98 * {@code TrustedCertificateEntry},
99 * then the trusted certificate contained in that entry is returned.
100 *
101 * <p> If the given alias name identifies an entry
102 * created by a call to {@code setKeyEntry},
103 * or created by a call to {@code setEntry} with a
104 * {@code PrivateKeyEntry},
105 * then the first element of the certificate chain in that entry
106 * (if a chain exists) is returned.
107 *
108 * @param alias the alias name
109 *
110 * @return the certificate, or null if the given alias does not exist or
111 * does not contain a certificate.
112 */
113 public abstract Certificate engineGetCertificate(String alias);
114
115 /**
116 * Returns the creation date of the entry identified by the given alias.
117 *
118 * @param alias the alias name
119 *
120 * @return the creation date of this entry, or null if the given alias does
121 * not exist
122 */
123 public abstract Date engineGetCreationDate(String alias);
124
125 /**
126 * Assigns the given key to the given alias, protecting it with the given
127 * password.
128 *
129 * <p>If the given key is of type {@code java.security.PrivateKey},
130 * it must be accompanied by a certificate chain certifying the
131 * corresponding public key.
132 *
133 * <p>If the given alias already exists, the keystore information
134 * associated with it is overridden by the given key (and possibly
135 * certificate chain).
136 *
137 * @param alias the alias name
138 * @param key the key to be associated with the alias
139 * @param password the password to protect the key
140 * @param chain the certificate chain for the corresponding public
141 * key (only required if the given key is of type
142 * {@code java.security.PrivateKey}).
143 *
144 * @exception KeyStoreException if the given key cannot be protected, or
145 * this operation fails for some other reason
146 */
147 public abstract void engineSetKeyEntry(String alias, Key key,
148 char[] password,
149 Certificate[] chain)
150 throws KeyStoreException;
151
152 /**
153 * Assigns the given key (that has already been protected) to the given
154 * alias.
155 *
156 * <p>If the protected key is of type
157 * {@code java.security.PrivateKey},
158 * it must be accompanied by a certificate chain certifying the
159 * corresponding public key.
160 *
161 * <p>If the given alias already exists, the keystore information
162 * associated with it is overridden by the given key (and possibly
163 * certificate chain).
164 *
165 * @param alias the alias name
166 * @param key the key (in protected format) to be associated with the alias
167 * @param chain the certificate chain for the corresponding public
168 * key (only useful if the protected key is of type
169 * {@code java.security.PrivateKey}).
170 *
171 * @exception KeyStoreException if this operation fails.
172 */
173 public abstract void engineSetKeyEntry(String alias, byte[] key,
174 Certificate[] chain)
175 throws KeyStoreException;
176
177 /**
178 * Assigns the given certificate to the given alias.
179 *
180 * <p> If the given alias identifies an existing entry
181 * created by a call to {@code setCertificateEntry},
182 * or created by a call to {@code setEntry} with a
183 * {@code TrustedCertificateEntry},
184 * the trusted certificate in the existing entry
185 * is overridden by the given certificate.
186 *
187 * @param alias the alias name
188 * @param cert the certificate
189 *
190 * @exception KeyStoreException if the given alias already exists and does
191 * not identify an entry containing a trusted certificate,
192 * or this operation fails for some other reason.
193 */
194 public abstract void engineSetCertificateEntry(String alias,
195 Certificate cert)
196 throws KeyStoreException;
197
198 /**
199 * Deletes the entry identified by the given alias from this keystore.
200 *
201 * @param alias the alias name
202 *
203 * @exception KeyStoreException if the entry cannot be removed.
204 */
205 public abstract void engineDeleteEntry(String alias)
206 throws KeyStoreException;
207
208 /**
209 * Lists all the alias names of this keystore.
210 *
211 * @return enumeration of the alias names
212 */
213 public abstract Enumeration<String> engineAliases();
214
215 /**
216 * Checks if the given alias exists in this keystore.
217 *
218 * @param alias the alias name
219 *
220 * @return true if the alias exists, false otherwise
221 */
222 public abstract boolean engineContainsAlias(String alias);
223
224 /**
225 * Retrieves the number of entries in this keystore.
226 *
227 * @return the number of entries in this keystore
228 */
229 public abstract int engineSize();
230
231 /**
232 * Returns true if the entry identified by the given alias
233 * was created by a call to {@code setKeyEntry},
234 * or created by a call to {@code setEntry} with a
235 * {@code PrivateKeyEntry} or a {@code SecretKeyEntry}.
236 *
237 * @param alias the alias for the keystore entry to be checked
238 *
239 * @return true if the entry identified by the given alias is a
240 * key-related, false otherwise.
241 */
242 public abstract boolean engineIsKeyEntry(String alias);
243
244 /**
245 * Returns true if the entry identified by the given alias
246 * was created by a call to {@code setCertificateEntry},
247 * or created by a call to {@code setEntry} with a
248 * {@code TrustedCertificateEntry}.
249 *
250 * @param alias the alias for the keystore entry to be checked
251 *
252 * @return true if the entry identified by the given alias contains a
253 * trusted certificate, false otherwise.
254 */
255 public abstract boolean engineIsCertificateEntry(String alias);
256
257 /**
258 * Returns the (alias) name of the first keystore entry whose certificate
259 * matches the given certificate.
260 *
261 * <p>This method attempts to match the given certificate with each
262 * keystore entry. If the entry being considered was
263 * created by a call to {@code setCertificateEntry},
264 * or created by a call to {@code setEntry} with a
265 * {@code TrustedCertificateEntry},
266 * then the given certificate is compared to that entry's certificate.
267 *
268 * <p> If the entry being considered was
269 * created by a call to {@code setKeyEntry},
270 * or created by a call to {@code setEntry} with a
271 * {@code PrivateKeyEntry},
272 * then the given certificate is compared to the first
273 * element of that entry's certificate chain.
274 *
275 * @param cert the certificate to match with.
276 *
277 * @return the alias name of the first entry with matching certificate,
278 * or null if no such entry exists in this keystore.
279 */
280 public abstract String engineGetCertificateAlias(Certificate cert);
281
282 /**
283 * Stores this keystore to the given output stream, and protects its
284 * integrity with the given password.
285 *
286 * @param stream the output stream to which this keystore is written.
287 * @param password the password to generate the keystore integrity check
288 *
289 * @exception IOException if there was an I/O problem with data
290 * @exception NoSuchAlgorithmException if the appropriate data integrity
291 * algorithm could not be found
292 * @exception CertificateException if any of the certificates included in
293 * the keystore data could not be stored
294 */
295 public abstract void engineStore(OutputStream stream, char[] password)
296 throws IOException, NoSuchAlgorithmException, CertificateException;
297
298 /**
299 * Stores this keystore using the given
300 * {@code KeyStore.LoadStoreParmeter}.
301 *
302 * @param param the {@code KeyStore.LoadStoreParmeter}
303 * that specifies how to store the keystore,
304 * which may be {@code null}
305 *
306 * @exception IllegalArgumentException if the given
307 * {@code KeyStore.LoadStoreParmeter}
308 * input is not recognized
309 * @exception IOException if there was an I/O problem with data
310 * @exception NoSuchAlgorithmException if the appropriate data integrity
311 * algorithm could not be found
312 * @exception CertificateException if any of the certificates included in
313 * the keystore data could not be stored
314 *
315 * @since 1.5
316 */
317 public void engineStore(KeyStore.LoadStoreParameter param)
318 throws IOException, NoSuchAlgorithmException,
319 CertificateException {
320 throw new UnsupportedOperationException();
321 }
322
323 /**
324 * Loads the keystore from the given input stream.
325 *
326 * <p>A password may be given to unlock the keystore
327 * (e.g. the keystore resides on a hardware token device),
328 * or to check the integrity of the keystore data.
329 * If a password is not given for integrity checking,
330 * then integrity checking is not performed.
331 *
332 * @param stream the input stream from which the keystore is loaded,
333 * or {@code null}
334 * @param password the password used to check the integrity of
335 * the keystore, the password used to unlock the keystore,
336 * or {@code null}
337 *
338 * @exception IOException if there is an I/O or format problem with the
339 * keystore data, if a password is required but not given,
340 * or if the given password was incorrect. If the error is due to a
341 * wrong password, the {@link Throwable#getCause cause} of the
342 * {@code IOException} should be an
343 * {@code UnrecoverableKeyException}
344 * @exception NoSuchAlgorithmException if the algorithm used to check
345 * the integrity of the keystore cannot be found
346 * @exception CertificateException if any of the certificates in the
347 * keystore could not be loaded
348 */
349 public abstract void engineLoad(InputStream stream, char[] password)
350 throws IOException, NoSuchAlgorithmException, CertificateException;
351
352 /**
353 * Loads the keystore using the given
354 * {@code KeyStore.LoadStoreParameter}.
355 *
356 * <p> Note that if this KeyStore has already been loaded, it is
357 * reinitialized and loaded again from the given parameter.
358 *
359 * @param param the {@code KeyStore.LoadStoreParameter}
360 * that specifies how to load the keystore,
361 * which may be {@code null}
362 *
363 * @implSpec
364 * The default implementation examines {@code KeyStore.LoadStoreParameter}
365 * to extract its password and pass it to
366 * {@link KeyStoreSpi#engineLoad(InputStream, char[])} along with a
367 * {@code null} {@code InputStream}.
368 * <p>
369 * If {@code KeyStore.LoadStoreParameter} is {@code null} then
370 * the password parameter will also be {@code null}.
371 * Otherwise the {@code KeyStore.ProtectionParameter} of
372 * {@code KeyStore.LoadStoreParameter} must be either a
373 * {@code KeyStore.PasswordProtection} or a
374 * {@code KeyStore.CallbackHandlerProtection} that supports
375 * {@code PasswordCallback} so that the password parameter can be
376 * extracted. If the {@code KeyStore.ProtectionParameter} is neither
377 * of those classes then a {@code NoSuchAlgorithmException} is thrown.
378 *
379 * @exception IllegalArgumentException if the given
380 * {@code KeyStore.LoadStoreParameter}
381 * input is not recognized
382 * @exception IOException if there is an I/O or format problem with the
383 * keystore data. If the error is due to an incorrect
384 * {@code ProtectionParameter} (e.g. wrong password)
385 * the {@link Throwable#getCause cause} of the
386 * {@code IOException} should be an
387 * {@code UnrecoverableKeyException}
388 * @exception NoSuchAlgorithmException if the algorithm used to check
389 * the integrity of the keystore cannot be found
390 * @exception CertificateException if any of the certificates in the
391 * keystore could not be loaded
392 *
393 * @since 1.5
394 */
395 public void engineLoad(KeyStore.LoadStoreParameter param)
396 throws IOException, NoSuchAlgorithmException,
397 CertificateException {
398
399 if (param == null) {
400 engineLoad((InputStream)null, (char[])null);
401 return;
402 }
403
404 ProtectionParameter protection = param.getProtectionParameter();
405 char[] password;
406 if (protection instanceof PasswordProtection) {
407 password = ((PasswordProtection)protection).getPassword();
408 } else if (protection instanceof CallbackHandlerProtection) {
409 CallbackHandler handler =
410 ((CallbackHandlerProtection)protection).getCallbackHandler();
411 PasswordCallback callback =
412 new PasswordCallback("Password: ", false);
413 try {
414 handler.handle(new Callback[] {callback});
415 } catch (UnsupportedCallbackException e) {
416 throw new NoSuchAlgorithmException
417 ("Could not obtain password", e);
418 }
419 password = callback.getPassword();
420 callback.clearPassword();
421 if (password == null) {
422 throw new NoSuchAlgorithmException("No password provided");
423 }
424 } else {
425 throw new NoSuchAlgorithmException("ProtectionParameter must"
426 + " be PasswordProtection or CallbackHandlerProtection");
427 }
428 engineLoad(null, password);
429 return;
430 }
431
432 /**
433 * Gets a {@code KeyStore.Entry} for the specified alias
434 * with the specified protection parameter.
435 *
436 * @param alias get the {@code KeyStore.Entry} for this alias
437 * @param protParam the {@code ProtectionParameter}
438 * used to protect the {@code Entry},
439 * which may be {@code null}
440 *
441 * @return the {@code KeyStore.Entry} for the specified alias,
442 * or {@code null} if there is no such entry
443 *
444 * @exception KeyStoreException if the operation failed
445 * @exception NoSuchAlgorithmException if the algorithm for recovering the
446 * entry cannot be found
447 * @exception UnrecoverableEntryException if the specified
448 * {@code protParam} were insufficient or invalid
449 * @exception UnrecoverableKeyException if the entry is a
450 * {@code PrivateKeyEntry} or {@code SecretKeyEntry}
451 * and the specified {@code protParam} does not contain
452 * the information needed to recover the key (e.g. wrong password)
453 *
454 * @since 1.5
455 */
456 public KeyStore.Entry engineGetEntry(String alias,
457 KeyStore.ProtectionParameter protParam)
458 throws KeyStoreException, NoSuchAlgorithmException,
459 UnrecoverableEntryException {
460
461 if (!engineContainsAlias(alias)) {
462 return null;
463 }
464
465 if (protParam == null) {
466 if (engineIsCertificateEntry(alias)) {
467 return new KeyStore.TrustedCertificateEntry
468 (engineGetCertificate(alias));
469 } else {
470 throw new UnrecoverableKeyException
471 ("requested entry requires a password");
472 }
473 }
474
475 if (protParam instanceof KeyStore.PasswordProtection) {
476 if (engineIsCertificateEntry(alias)) {
477 throw new UnsupportedOperationException
478 ("trusted certificate entries are not password-protected");
479 } else if (engineIsKeyEntry(alias)) {
480 KeyStore.PasswordProtection pp =
481 (KeyStore.PasswordProtection)protParam;
482 char[] password = pp.getPassword();
483
484 Key key = engineGetKey(alias, password);
485 if (key instanceof PrivateKey) {
486 Certificate[] chain = engineGetCertificateChain(alias);
487 return new KeyStore.PrivateKeyEntry((PrivateKey)key, chain);
488 } else if (key instanceof SecretKey) {
489 return new KeyStore.SecretKeyEntry((SecretKey)key);
490 }
491 }
492 }
493
494 throw new UnsupportedOperationException();
495 }
496
497 /**
498 * Saves a {@code KeyStore.Entry} under the specified alias.
499 * The specified protection parameter is used to protect the
500 * {@code Entry}.
501 *
502 * <p> If an entry already exists for the specified alias,
503 * it is overridden.
504 *
505 * @param alias save the {@code KeyStore.Entry} under this alias
506 * @param entry the {@code Entry} to save
507 * @param protParam the {@code ProtectionParameter}
508 * used to protect the {@code Entry},
509 * which may be {@code null}
510 *
511 * @exception KeyStoreException if this operation fails
512 *
513 * @since 1.5
514 */
515 public void engineSetEntry(String alias, KeyStore.Entry entry,
516 KeyStore.ProtectionParameter protParam)
517 throws KeyStoreException {
518
519 // get password
520 if (protParam != null &&
521 !(protParam instanceof KeyStore.PasswordProtection)) {
522 throw new KeyStoreException("unsupported protection parameter");
523 }
524 KeyStore.PasswordProtection pProtect = null;
525 if (protParam != null) {
526 pProtect = (KeyStore.PasswordProtection)protParam;
527 }
528
529 // set entry
530 if (entry instanceof KeyStore.TrustedCertificateEntry) {
531 if (protParam != null && pProtect.getPassword() != null) {
532 // pre-1.5 style setCertificateEntry did not allow password
533 throw new KeyStoreException
534 ("trusted certificate entries are not password-protected");
535 } else {
536 KeyStore.TrustedCertificateEntry tce =
537 (KeyStore.TrustedCertificateEntry)entry;
538 engineSetCertificateEntry(alias, tce.getTrustedCertificate());
539 return;
540 }
541 } else if (entry instanceof KeyStore.PrivateKeyEntry) {
542 if (pProtect == null || pProtect.getPassword() == null) {
543 // pre-1.5 style setKeyEntry required password
544 throw new KeyStoreException
545 ("non-null password required to create PrivateKeyEntry");
546 } else {
547 engineSetKeyEntry
548 (alias,
549 ((KeyStore.PrivateKeyEntry)entry).getPrivateKey(),
550 pProtect.getPassword(),
551 ((KeyStore.PrivateKeyEntry)entry).getCertificateChain());
552 return;
553 }
554 } else if (entry instanceof KeyStore.SecretKeyEntry) {
555 if (pProtect == null || pProtect.getPassword() == null) {
556 // pre-1.5 style setKeyEntry required password
557 throw new KeyStoreException
558 ("non-null password required to create SecretKeyEntry");
559 } else {
560 engineSetKeyEntry
561 (alias,
562 ((KeyStore.SecretKeyEntry)entry).getSecretKey(),
563 pProtect.getPassword(),
564 (Certificate[])null);
565 return;
566 }
567 }
568
569 throw new KeyStoreException
570 ("unsupported entry type: " + entry.getClass().getName());
571 }
572
573 /**
574 * Determines if the keystore {@code Entry} for the specified
575 * {@code alias} is an instance or subclass of the specified
576 * {@code entryClass}.
577 *
578 * @param alias the alias name
579 * @param entryClass the entry class
580 *
581 * @return true if the keystore {@code Entry} for the specified
582 * {@code alias} is an instance or subclass of the
583 * specified {@code entryClass}, false otherwise
584 *
585 * @since 1.5
586 */
587 public boolean
588 engineEntryInstanceOf(String alias,
589 Class<? extends KeyStore.Entry> entryClass)
590 {
591 if (entryClass == KeyStore.TrustedCertificateEntry.class) {
592 return engineIsCertificateEntry(alias);
593 }
594 if (entryClass == KeyStore.PrivateKeyEntry.class) {
595 return engineIsKeyEntry(alias) &&
596 engineGetCertificate(alias) != null;
597 }
598 if (entryClass == KeyStore.SecretKeyEntry.class) {
599 return engineIsKeyEntry(alias) &&
600 engineGetCertificate(alias) == null;
601 }
602 return false;
603 }
604
605 /**
606 * Probes the specified input stream to determine whether it contains a
607 * keystore that is supported by this implementation, or not.
608 *
609 * @implSpec
610 * This method returns false by default. Keystore implementations should
611 * override this method to peek at the data stream directly or to use other
612 * content detection mechanisms.
613 *
614 * @param stream the keystore data to be probed
615 *
616 * @return true if the keystore data is supported, otherwise false
617 *
618 * @throws IOException if there is an I/O problem with the keystore data.
619 * @throws NullPointerException if stream is {@code null}.
620 *
621 * @since 9
622 */
623 public boolean engineProbe(InputStream stream) throws IOException {
624 if (stream == null) {
625 throw new NullPointerException("input stream must not be null");
626 }
627 return false;
628 }
629 }