1 /*
2 * Copyright (c) 1998, 2019, 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 * @throws NoSuchAlgorithmException if the algorithm for recovering the
70 * key cannot be found
71 * @throws 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 * @throws 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 * @throws 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 * @throws 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 * @throws 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 * @throws IOException if there was an I/O problem with data
290 * @throws NoSuchAlgorithmException if the appropriate data integrity
291 * algorithm could not be found
292 * @throws 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 * @throws IllegalArgumentException if the given
307 * {@code KeyStore.LoadStoreParmeter}
308 * input is not recognized
309 * @throws IOException if there was an I/O problem with data
310 * @throws NoSuchAlgorithmException if the appropriate data integrity
311 * algorithm could not be found
312 * @throws 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 * @throws 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 * @throws NoSuchAlgorithmException if the algorithm used to check
345 * the integrity of the keystore cannot be found
346 * @throws 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 * @throws IllegalArgumentException if the given
380 * {@code KeyStore.LoadStoreParameter}
381 * input is not recognized
382 * @throws 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 * @throws NoSuchAlgorithmException if the algorithm used to check
389 * the integrity of the keystore cannot be found
390 * @throws 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 engineLoad(null, param);
399 }
400
401 void engineLoad(InputStream stream, KeyStore.LoadStoreParameter param)
402 throws IOException, NoSuchAlgorithmException,
403 CertificateException {
404
405 if (param == null) {
406 engineLoad((InputStream)null, (char[])null);
407 return;
408 }
409
410 ProtectionParameter protection = param.getProtectionParameter();
411 char[] password;
412 if (protection instanceof PasswordProtection) {
413 password = ((PasswordProtection)protection).getPassword();
414 } else if (protection instanceof CallbackHandlerProtection) {
415 CallbackHandler handler =
416 ((CallbackHandlerProtection)protection).getCallbackHandler();
417 PasswordCallback callback =
418 new PasswordCallback("Password: ", false);
419 try {
420 handler.handle(new Callback[] {callback});
421 } catch (UnsupportedCallbackException e) {
422 throw new NoSuchAlgorithmException
423 ("Could not obtain password", e);
424 }
425 password = callback.getPassword();
426 callback.clearPassword();
427 if (password == null) {
428 throw new NoSuchAlgorithmException("No password provided");
429 }
430 } else {
431 throw new NoSuchAlgorithmException("ProtectionParameter must"
432 + " be PasswordProtection or CallbackHandlerProtection");
433 }
434 engineLoad(stream, password);
435 return;
436 }
437
438 /**
439 * Gets a {@code KeyStore.Entry} for the specified alias
440 * with the specified protection parameter.
441 *
442 * @param alias get the {@code KeyStore.Entry} for this alias
443 * @param protParam the {@code ProtectionParameter}
444 * used to protect the {@code Entry},
445 * which may be {@code null}
446 *
447 * @return the {@code KeyStore.Entry} for the specified alias,
448 * or {@code null} if there is no such entry
449 *
450 * @throws KeyStoreException if the operation failed
451 * @throws NoSuchAlgorithmException if the algorithm for recovering the
452 * entry cannot be found
453 * @throws UnrecoverableEntryException if the specified
454 * {@code protParam} were insufficient or invalid
455 * @throws UnrecoverableKeyException if the entry is a
456 * {@code PrivateKeyEntry} or {@code SecretKeyEntry}
457 * and the specified {@code protParam} does not contain
458 * the information needed to recover the key (e.g. wrong password)
459 *
460 * @since 1.5
461 */
462 public KeyStore.Entry engineGetEntry(String alias,
463 KeyStore.ProtectionParameter protParam)
464 throws KeyStoreException, NoSuchAlgorithmException,
465 UnrecoverableEntryException {
466
467 if (!engineContainsAlias(alias)) {
468 return null;
469 }
470
471 if (protParam == null) {
472 if (engineIsCertificateEntry(alias)) {
473 return new KeyStore.TrustedCertificateEntry
474 (engineGetCertificate(alias));
475 } else {
476 throw new UnrecoverableKeyException
477 ("requested entry requires a password");
478 }
479 }
480
481 if (protParam instanceof KeyStore.PasswordProtection) {
482 if (engineIsCertificateEntry(alias)) {
483 throw new UnsupportedOperationException
484 ("trusted certificate entries are not password-protected");
485 } else if (engineIsKeyEntry(alias)) {
486 KeyStore.PasswordProtection pp =
487 (KeyStore.PasswordProtection)protParam;
488 if (pp.getProtectionAlgorithm() != null) {
489 throw new KeyStoreException(
490 "unsupported password protection algorithm");
491 }
492 char[] password = pp.getPassword();
493
494 Key key = engineGetKey(alias, password);
495 if (key instanceof PrivateKey) {
496 Certificate[] chain = engineGetCertificateChain(alias);
497 return new KeyStore.PrivateKeyEntry((PrivateKey)key, chain);
498 } else if (key instanceof SecretKey) {
499 return new KeyStore.SecretKeyEntry((SecretKey)key);
500 }
501 }
502 }
503
504 throw new UnsupportedOperationException();
505 }
506
507 /**
508 * Saves a {@code KeyStore.Entry} under the specified alias.
509 * The specified protection parameter is used to protect the
510 * {@code Entry}.
511 *
512 * <p> If an entry already exists for the specified alias,
513 * it is overridden.
514 *
515 * @param alias save the {@code KeyStore.Entry} under this alias
516 * @param entry the {@code Entry} to save
517 * @param protParam the {@code ProtectionParameter}
518 * used to protect the {@code Entry},
519 * which may be {@code null}
520 *
521 * @throws KeyStoreException if this operation fails
522 *
523 * @since 1.5
524 */
525 public void engineSetEntry(String alias, KeyStore.Entry entry,
526 KeyStore.ProtectionParameter protParam)
527 throws KeyStoreException {
528
529 // get password
530 if (protParam != null &&
531 !(protParam instanceof KeyStore.PasswordProtection)) {
532 throw new KeyStoreException("unsupported protection parameter");
533 }
534 KeyStore.PasswordProtection pProtect = null;
535 if (protParam != null) {
536 pProtect = (KeyStore.PasswordProtection)protParam;
537 if (pProtect.getProtectionAlgorithm() != null) {
538 throw new KeyStoreException(
539 "unsupported password protection algorithm");
540 }
541 }
542
543 // set entry
544 if (entry instanceof KeyStore.TrustedCertificateEntry) {
545 if (protParam != null && pProtect.getPassword() != null) {
546 // pre-1.5 style setCertificateEntry did not allow password
547 throw new KeyStoreException
548 ("trusted certificate entries are not password-protected");
549 } else {
550 KeyStore.TrustedCertificateEntry tce =
551 (KeyStore.TrustedCertificateEntry)entry;
552 engineSetCertificateEntry(alias, tce.getTrustedCertificate());
553 return;
554 }
555 } else if (entry instanceof KeyStore.PrivateKeyEntry) {
556 if (pProtect == null || pProtect.getPassword() == null) {
557 // pre-1.5 style setKeyEntry required password
558 throw new KeyStoreException
559 ("non-null password required to create PrivateKeyEntry");
560 } else {
561 engineSetKeyEntry
562 (alias,
563 ((KeyStore.PrivateKeyEntry)entry).getPrivateKey(),
564 pProtect.getPassword(),
565 ((KeyStore.PrivateKeyEntry)entry).getCertificateChain());
566 return;
567 }
568 } else if (entry instanceof KeyStore.SecretKeyEntry) {
569 if (pProtect == null || pProtect.getPassword() == null) {
570 // pre-1.5 style setKeyEntry required password
571 throw new KeyStoreException
572 ("non-null password required to create SecretKeyEntry");
573 } else {
574 engineSetKeyEntry
575 (alias,
576 ((KeyStore.SecretKeyEntry)entry).getSecretKey(),
577 pProtect.getPassword(),
578 (Certificate[])null);
579 return;
580 }
581 }
582
583 throw new KeyStoreException
584 ("unsupported entry type: " + entry.getClass().getName());
585 }
586
587 /**
588 * Determines if the keystore {@code Entry} for the specified
589 * {@code alias} is an instance or subclass of the specified
590 * {@code entryClass}.
591 *
592 * @param alias the alias name
593 * @param entryClass the entry class
594 *
595 * @return true if the keystore {@code Entry} for the specified
596 * {@code alias} is an instance or subclass of the
597 * specified {@code entryClass}, false otherwise
598 *
599 * @since 1.5
600 */
601 public boolean
602 engineEntryInstanceOf(String alias,
603 Class<? extends KeyStore.Entry> entryClass)
604 {
605 if (entryClass == KeyStore.TrustedCertificateEntry.class) {
606 return engineIsCertificateEntry(alias);
607 }
608 if (entryClass == KeyStore.PrivateKeyEntry.class) {
609 return engineIsKeyEntry(alias) &&
610 engineGetCertificate(alias) != null;
611 }
612 if (entryClass == KeyStore.SecretKeyEntry.class) {
613 return engineIsKeyEntry(alias) &&
614 engineGetCertificate(alias) == null;
615 }
616 return false;
617 }
618
619 /**
620 * Probes the specified input stream to determine whether it contains a
621 * keystore that is supported by this implementation, or not.
622 *
623 * @implSpec
624 * This method returns false by default. Keystore implementations should
625 * override this method to peek at the data stream directly or to use other
626 * content detection mechanisms.
627 *
628 * @param stream the keystore data to be probed
629 *
630 * @return true if the keystore data is supported, otherwise false
631 *
632 * @throws IOException if there is an I/O problem with the keystore data.
633 * @throws NullPointerException if stream is {@code null}.
634 *
635 * @since 9
636 */
637 public boolean engineProbe(InputStream stream) throws IOException {
638 if (stream == null) {
639 throw new NullPointerException("input stream must not be null");
640 }
641 return false;
642 }
643 }