src/share/classes/java/security/KeyStoreSpi.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 36,46 ****
import javax.security.auth.callback.*;
/**
* This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
! * for the <code>KeyStore</code> class.
* All the abstract methods in this class must be implemented by each
* cryptographic service provider who wishes to supply the implementation
* of a keystore for a particular keystore type.
*
* @author Jan Luehe
--- 36,46 ----
import javax.security.auth.callback.*;
/**
* This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
! * for the {@code KeyStore} class.
* All the abstract methods in this class must be implemented by each
* cryptographic service provider who wishes to supply the implementation
* of a keystore for a particular keystore type.
*
* @author Jan Luehe
*** 54,66 ****
public abstract class KeyStoreSpi {
/**
* Returns the key associated with the given alias, using the given
* password to recover it. The key must have been associated with
! * the alias by a call to <code>setKeyEntry</code>,
! * or by a call to <code>setEntry</code> with a
! * <code>PrivateKeyEntry</code> or <code>SecretKeyEntry</code>.
*
* @param alias the alias name
* @param password the password for recovering the key
*
* @return the requested key, or null if the given alias does not exist
--- 54,66 ----
public abstract class KeyStoreSpi {
/**
* Returns the key associated with the given alias, using the given
* password to recover it. The key must have been associated with
! * the alias by a call to {@code setKeyEntry},
! * or by a call to {@code setEntry} with a
! * {@code PrivateKeyEntry} or {@code SecretKeyEntry}.
*
* @param alias the alias name
* @param password the password for recovering the key
*
* @return the requested key, or null if the given alias does not exist
*** 75,87 ****
throws NoSuchAlgorithmException, UnrecoverableKeyException;
/**
* Returns the certificate chain associated with the given alias.
* The certificate chain must have been associated with the alias
! * by a call to <code>setKeyEntry</code>,
! * or by a call to <code>setEntry</code> with a
! * <code>PrivateKeyEntry</code>.
*
* @param alias the alias name
*
* @return the certificate chain (ordered with the user's certificate first
* and the root certificate authority last), or null if the given alias
--- 75,87 ----
throws NoSuchAlgorithmException, UnrecoverableKeyException;
/**
* Returns the certificate chain associated with the given alias.
* The certificate chain must have been associated with the alias
! * by a call to {@code setKeyEntry},
! * or by a call to {@code setEntry} with a
! * {@code PrivateKeyEntry}.
*
* @param alias the alias name
*
* @return the certificate chain (ordered with the user's certificate first
* and the root certificate authority last), or null if the given alias
*** 91,109 ****
/**
* Returns the certificate associated with the given alias.
*
* <p> If the given alias name identifies an entry
! * created by a call to <code>setCertificateEntry</code>,
! * or created by a call to <code>setEntry</code> with a
! * <code>TrustedCertificateEntry</code>,
* then the trusted certificate contained in that entry is returned.
*
* <p> If the given alias name identifies an entry
! * created by a call to <code>setKeyEntry</code>,
! * or created by a call to <code>setEntry</code> with a
! * <code>PrivateKeyEntry</code>,
* then the first element of the certificate chain in that entry
* (if a chain exists) is returned.
*
* @param alias the alias name
*
--- 91,109 ----
/**
* Returns the certificate associated with the given alias.
*
* <p> If the given alias name identifies an entry
! * created by a call to {@code setCertificateEntry},
! * or created by a call to {@code setEntry} with a
! * {@code TrustedCertificateEntry},
* then the trusted certificate contained in that entry is returned.
*
* <p> If the given alias name identifies an entry
! * created by a call to {@code setKeyEntry},
! * or created by a call to {@code setEntry} with a
! * {@code PrivateKeyEntry},
* then the first element of the certificate chain in that entry
* (if a chain exists) is returned.
*
* @param alias the alias name
*
*** 124,134 ****
/**
* Assigns the given key to the given alias, protecting it with the given
* password.
*
! * <p>If the given key is of type <code>java.security.PrivateKey</code>,
* it must be accompanied by a certificate chain certifying the
* corresponding public key.
*
* <p>If the given alias already exists, the keystore information
* associated with it is overridden by the given key (and possibly
--- 124,134 ----
/**
* Assigns the given key to the given alias, protecting it with the given
* password.
*
! * <p>If the given key is of type {@code java.security.PrivateKey},
* it must be accompanied by a certificate chain certifying the
* corresponding public key.
*
* <p>If the given alias already exists, the keystore information
* associated with it is overridden by the given key (and possibly
*** 137,147 ****
* @param alias the alias name
* @param key the key to be associated with the alias
* @param password the password to protect the key
* @param chain the certificate chain for the corresponding public
* key (only required if the given key is of type
! * <code>java.security.PrivateKey</code>).
*
* @exception KeyStoreException if the given key cannot be protected, or
* this operation fails for some other reason
*/
public abstract void engineSetKeyEntry(String alias, Key key,
--- 137,147 ----
* @param alias the alias name
* @param key the key to be associated with the alias
* @param password the password to protect the key
* @param chain the certificate chain for the corresponding public
* key (only required if the given key is of type
! * {@code java.security.PrivateKey}).
*
* @exception KeyStoreException if the given key cannot be protected, or
* this operation fails for some other reason
*/
public abstract void engineSetKeyEntry(String alias, Key key,
*** 152,162 ****
/**
* Assigns the given key (that has already been protected) to the given
* alias.
*
* <p>If the protected key is of type
! * <code>java.security.PrivateKey</code>,
* it must be accompanied by a certificate chain certifying the
* corresponding public key.
*
* <p>If the given alias already exists, the keystore information
* associated with it is overridden by the given key (and possibly
--- 152,162 ----
/**
* Assigns the given key (that has already been protected) to the given
* alias.
*
* <p>If the protected key is of type
! * {@code java.security.PrivateKey},
* it must be accompanied by a certificate chain certifying the
* corresponding public key.
*
* <p>If the given alias already exists, the keystore information
* associated with it is overridden by the given key (and possibly
*** 164,174 ****
*
* @param alias the alias name
* @param key the key (in protected format) to be associated with the alias
* @param chain the certificate chain for the corresponding public
* key (only useful if the protected key is of type
! * <code>java.security.PrivateKey</code>).
*
* @exception KeyStoreException if this operation fails.
*/
public abstract void engineSetKeyEntry(String alias, byte[] key,
Certificate[] chain)
--- 164,174 ----
*
* @param alias the alias name
* @param key the key (in protected format) to be associated with the alias
* @param chain the certificate chain for the corresponding public
* key (only useful if the protected key is of type
! * {@code java.security.PrivateKey}).
*
* @exception KeyStoreException if this operation fails.
*/
public abstract void engineSetKeyEntry(String alias, byte[] key,
Certificate[] chain)
*** 176,188 ****
/**
* Assigns the given certificate to the given alias.
*
* <p> If the given alias identifies an existing entry
! * created by a call to <code>setCertificateEntry</code>,
! * or created by a call to <code>setEntry</code> with a
! * <code>TrustedCertificateEntry</code>,
* the trusted certificate in the existing entry
* is overridden by the given certificate.
*
* @param alias the alias name
* @param cert the certificate
--- 176,188 ----
/**
* Assigns the given certificate to the given alias.
*
* <p> If the given alias identifies an existing entry
! * created by a call to {@code setCertificateEntry},
! * or created by a call to {@code setEntry} with a
! * {@code TrustedCertificateEntry},
* the trusted certificate in the existing entry
* is overridden by the given certificate.
*
* @param alias the alias name
* @param cert the certificate
*** 228,253 ****
*/
public abstract int engineSize();
/**
* Returns true if the entry identified by the given alias
! * was created by a call to <code>setKeyEntry</code>,
! * or created by a call to <code>setEntry</code> with a
! * <code>PrivateKeyEntry</code> or a <code>SecretKeyEntry</code>.
*
* @param alias the alias for the keystore entry to be checked
*
* @return true if the entry identified by the given alias is a
* key-related, false otherwise.
*/
public abstract boolean engineIsKeyEntry(String alias);
/**
* Returns true if the entry identified by the given alias
! * was created by a call to <code>setCertificateEntry</code>,
! * or created by a call to <code>setEntry</code> with a
! * <code>TrustedCertificateEntry</code>.
*
* @param alias the alias for the keystore entry to be checked
*
* @return true if the entry identified by the given alias contains a
* trusted certificate, false otherwise.
--- 228,253 ----
*/
public abstract int engineSize();
/**
* Returns true if the entry identified by the given alias
! * was created by a call to {@code setKeyEntry},
! * or created by a call to {@code setEntry} with a
! * {@code PrivateKeyEntry} or a {@code SecretKeyEntry}.
*
* @param alias the alias for the keystore entry to be checked
*
* @return true if the entry identified by the given alias is a
* key-related, false otherwise.
*/
public abstract boolean engineIsKeyEntry(String alias);
/**
* Returns true if the entry identified by the given alias
! * was created by a call to {@code setCertificateEntry},
! * or created by a call to {@code setEntry} with a
! * {@code TrustedCertificateEntry}.
*
* @param alias the alias for the keystore entry to be checked
*
* @return true if the entry identified by the given alias contains a
* trusted certificate, false otherwise.
*** 258,276 ****
* Returns the (alias) name of the first keystore entry whose certificate
* matches the given certificate.
*
* <p>This method attempts to match the given certificate with each
* keystore entry. If the entry being considered was
! * created by a call to <code>setCertificateEntry</code>,
! * or created by a call to <code>setEntry</code> with a
! * <code>TrustedCertificateEntry</code>,
* then the given certificate is compared to that entry's certificate.
*
* <p> If the entry being considered was
! * created by a call to <code>setKeyEntry</code>,
! * or created by a call to <code>setEntry</code> with a
! * <code>PrivateKeyEntry</code>,
* then the given certificate is compared to the first
* element of that entry's certificate chain.
*
* @param cert the certificate to match with.
*
--- 258,276 ----
* Returns the (alias) name of the first keystore entry whose certificate
* matches the given certificate.
*
* <p>This method attempts to match the given certificate with each
* keystore entry. If the entry being considered was
! * created by a call to {@code setCertificateEntry},
! * or created by a call to {@code setEntry} with a
! * {@code TrustedCertificateEntry},
* then the given certificate is compared to that entry's certificate.
*
* <p> If the entry being considered was
! * created by a call to {@code setKeyEntry},
! * or created by a call to {@code setEntry} with a
! * {@code PrivateKeyEntry},
* then the given certificate is compared to the first
* element of that entry's certificate chain.
*
* @param cert the certificate to match with.
*
*** 295,312 ****
public abstract void engineStore(OutputStream stream, char[] password)
throws IOException, NoSuchAlgorithmException, CertificateException;
/**
* Stores this keystore using the given
! * <code>KeyStore.LoadStoreParmeter</code>.
*
! * @param param the <code>KeyStore.LoadStoreParmeter</code>
* that specifies how to store the keystore,
! * which may be <code>null</code>
*
* @exception IllegalArgumentException if the given
! * <code>KeyStore.LoadStoreParmeter</code>
* input is not recognized
* @exception IOException if there was an I/O problem with data
* @exception NoSuchAlgorithmException if the appropriate data integrity
* algorithm could not be found
* @exception CertificateException if any of the certificates included in
--- 295,312 ----
public abstract void engineStore(OutputStream stream, char[] password)
throws IOException, NoSuchAlgorithmException, CertificateException;
/**
* Stores this keystore using the given
! * {@code KeyStore.LoadStoreParmeter}.
*
! * @param param the {@code KeyStore.LoadStoreParmeter}
* that specifies how to store the keystore,
! * which may be {@code null}
*
* @exception IllegalArgumentException if the given
! * {@code KeyStore.LoadStoreParmeter}
* input is not recognized
* @exception IOException if there was an I/O problem with data
* @exception NoSuchAlgorithmException if the appropriate data integrity
* algorithm could not be found
* @exception CertificateException if any of the certificates included in
*** 328,376 ****
* or to check the integrity of the keystore data.
* If a password is not given for integrity checking,
* then integrity checking is not performed.
*
* @param stream the input stream from which the keystore is loaded,
! * or <code>null</code>
* @param password the password used to check the integrity of
* the keystore, the password used to unlock the keystore,
! * or <code>null</code>
*
* @exception IOException if there is an I/O or format problem with the
* keystore data, if a password is required but not given,
* or if the given password was incorrect. If the error is due to a
* wrong password, the {@link Throwable#getCause cause} of the
! * <code>IOException</code> should be an
! * <code>UnrecoverableKeyException</code>
* @exception NoSuchAlgorithmException if the algorithm used to check
* the integrity of the keystore cannot be found
* @exception CertificateException if any of the certificates in the
* keystore could not be loaded
*/
public abstract void engineLoad(InputStream stream, char[] password)
throws IOException, NoSuchAlgorithmException, CertificateException;
/**
* Loads the keystore using the given
! * <code>KeyStore.LoadStoreParameter</code>.
*
* <p> Note that if this KeyStore has already been loaded, it is
* reinitialized and loaded again from the given parameter.
*
! * @param param the <code>KeyStore.LoadStoreParameter</code>
* that specifies how to load the keystore,
! * which may be <code>null</code>
*
* @exception IllegalArgumentException if the given
! * <code>KeyStore.LoadStoreParameter</code>
* input is not recognized
* @exception IOException if there is an I/O or format problem with the
* keystore data. If the error is due to an incorrect
! * <code>ProtectionParameter</code> (e.g. wrong password)
* the {@link Throwable#getCause cause} of the
! * <code>IOException</code> should be an
! * <code>UnrecoverableKeyException</code>
* @exception NoSuchAlgorithmException if the algorithm used to check
* the integrity of the keystore cannot be found
* @exception CertificateException if any of the certificates in the
* keystore could not be loaded
*
--- 328,376 ----
* or to check the integrity of the keystore data.
* If a password is not given for integrity checking,
* then integrity checking is not performed.
*
* @param stream the input stream from which the keystore is loaded,
! * or {@code null}
* @param password the password used to check the integrity of
* the keystore, the password used to unlock the keystore,
! * or {@code null}
*
* @exception IOException if there is an I/O or format problem with the
* keystore data, if a password is required but not given,
* or if the given password was incorrect. If the error is due to a
* wrong password, the {@link Throwable#getCause cause} of the
! * {@code IOException} should be an
! * {@code UnrecoverableKeyException}
* @exception NoSuchAlgorithmException if the algorithm used to check
* the integrity of the keystore cannot be found
* @exception CertificateException if any of the certificates in the
* keystore could not be loaded
*/
public abstract void engineLoad(InputStream stream, char[] password)
throws IOException, NoSuchAlgorithmException, CertificateException;
/**
* Loads the keystore using the given
! * {@code KeyStore.LoadStoreParameter}.
*
* <p> Note that if this KeyStore has already been loaded, it is
* reinitialized and loaded again from the given parameter.
*
! * @param param the {@code KeyStore.LoadStoreParameter}
* that specifies how to load the keystore,
! * which may be {@code null}
*
* @exception IllegalArgumentException if the given
! * {@code KeyStore.LoadStoreParameter}
* input is not recognized
* @exception IOException if there is an I/O or format problem with the
* keystore data. If the error is due to an incorrect
! * {@code ProtectionParameter} (e.g. wrong password)
* the {@link Throwable#getCause cause} of the
! * {@code IOException} should be an
! * {@code UnrecoverableKeyException}
* @exception NoSuchAlgorithmException if the algorithm used to check
* the integrity of the keystore cannot be found
* @exception CertificateException if any of the certificates in the
* keystore could not be loaded
*
*** 417,445 ****
throw new UnsupportedOperationException();
}
/**
! * Gets a <code>KeyStore.Entry</code> for the specified alias
* with the specified protection parameter.
*
! * @param alias get the <code>KeyStore.Entry</code> for this alias
! * @param protParam the <code>ProtectionParameter</code>
! * used to protect the <code>Entry</code>,
! * which may be <code>null</code>
*
! * @return the <code>KeyStore.Entry</code> for the specified alias,
! * or <code>null</code> if there is no such entry
*
* @exception KeyStoreException if the operation failed
* @exception NoSuchAlgorithmException if the algorithm for recovering the
* entry cannot be found
* @exception UnrecoverableEntryException if the specified
! * <code>protParam</code> were insufficient or invalid
* @exception UnrecoverableKeyException if the entry is a
! * <code>PrivateKeyEntry</code> or <code>SecretKeyEntry</code>
! * and the specified <code>protParam</code> does not contain
* the information needed to recover the key (e.g. wrong password)
*
* @since 1.5
*/
public KeyStore.Entry engineGetEntry(String alias,
--- 417,445 ----
throw new UnsupportedOperationException();
}
/**
! * Gets a {@code KeyStore.Entry} for the specified alias
* with the specified protection parameter.
*
! * @param alias get the {@code KeyStore.Entry} for this alias
! * @param protParam the {@code ProtectionParameter}
! * used to protect the {@code Entry},
! * which may be {@code null}
*
! * @return the {@code KeyStore.Entry} for the specified alias,
! * or {@code null} if there is no such entry
*
* @exception KeyStoreException if the operation failed
* @exception NoSuchAlgorithmException if the algorithm for recovering the
* entry cannot be found
* @exception UnrecoverableEntryException if the specified
! * {@code protParam} were insufficient or invalid
* @exception UnrecoverableKeyException if the entry is a
! * {@code PrivateKeyEntry} or {@code SecretKeyEntry}
! * and the specified {@code protParam} does not contain
* the information needed to recover the key (e.g. wrong password)
*
* @since 1.5
*/
public KeyStore.Entry engineGetEntry(String alias,
*** 482,503 ****
throw new UnsupportedOperationException();
}
/**
! * Saves a <code>KeyStore.Entry</code> under the specified alias.
* The specified protection parameter is used to protect the
! * <code>Entry</code>.
*
* <p> If an entry already exists for the specified alias,
* it is overridden.
*
! * @param alias save the <code>KeyStore.Entry</code> under this alias
! * @param entry the <code>Entry</code> to save
! * @param protParam the <code>ProtectionParameter</code>
! * used to protect the <code>Entry</code>,
! * which may be <code>null</code>
*
* @exception KeyStoreException if this operation fails
*
* @since 1.5
*/
--- 482,503 ----
throw new UnsupportedOperationException();
}
/**
! * Saves a {@code KeyStore.Entry} under the specified alias.
* The specified protection parameter is used to protect the
! * {@code Entry}.
*
* <p> If an entry already exists for the specified alias,
* it is overridden.
*
! * @param alias save the {@code KeyStore.Entry} under this alias
! * @param entry the {@code Entry} to save
! * @param protParam the {@code ProtectionParameter}
! * used to protect the {@code Entry},
! * which may be {@code null}
*
* @exception KeyStoreException if this operation fails
*
* @since 1.5
*/
*** 558,577 ****
throw new KeyStoreException
("unsupported entry type: " + entry.getClass().getName());
}
/**
! * Determines if the keystore <code>Entry</code> for the specified
! * <code>alias</code> is an instance or subclass of the specified
! * <code>entryClass</code>.
*
* @param alias the alias name
* @param entryClass the entry class
*
! * @return true if the keystore <code>Entry</code> for the specified
! * <code>alias</code> is an instance or subclass of the
! * specified <code>entryClass</code>, false otherwise
*
* @since 1.5
*/
public boolean
engineEntryInstanceOf(String alias,
--- 558,577 ----
throw new KeyStoreException
("unsupported entry type: " + entry.getClass().getName());
}
/**
! * Determines if the keystore {@code Entry} for the specified
! * {@code alias} is an instance or subclass of the specified
! * {@code entryClass}.
*
* @param alias the alias name
* @param entryClass the entry class
*
! * @return true if the keystore {@code Entry} for the specified
! * {@code alias} is an instance or subclass of the
! * specified {@code entryClass}, false otherwise
*
* @since 1.5
*/
public boolean
engineEntryInstanceOf(String alias,