src/share/classes/java/security/KeyStore.java
Print this page
*** 39,71 ****
/**
* This class represents a storage facility for cryptographic
* keys and certificates.
*
! * <p> A <code>KeyStore</code> manages different types of entries.
! * Each type of entry implements the <code>KeyStore.Entry</code> interface.
! * Three basic <code>KeyStore.Entry</code> implementations are provided:
*
* <ul>
* <li><b>KeyStore.PrivateKeyEntry</b>
! * <p> This type of entry holds a cryptographic <code>PrivateKey</code>,
* which is optionally stored in a protected format to prevent
* unauthorized access. It is also accompanied by a certificate chain
* for the corresponding public key.
*
* <p> Private keys and certificate chains are used by a given entity for
* self-authentication. Applications for this authentication include software
* distribution organizations which sign JAR files as part of releasing
* and/or licensing software.
*
* <li><b>KeyStore.SecretKeyEntry</b>
! * <p> This type of entry holds a cryptographic <code>SecretKey</code>,
* which is optionally stored in a protected format to prevent
* unauthorized access.
*
* <li><b>KeyStore.TrustedCertificateEntry</b>
! * <p> This type of entry contains a single public key <code>Certificate</code>
* belonging to another party. It is called a <i>trusted certificate</i>
* because the keystore owner trusts that the public key in the certificate
* indeed belongs to the identity identified by the <i>subject</i> (owner)
* of the certificate.
*
--- 39,71 ----
/**
* This class represents a storage facility for cryptographic
* keys and certificates.
*
! * <p> A {@code KeyStore} manages different types of entries.
! * Each type of entry implements the {@code KeyStore.Entry} interface.
! * Three basic {@code KeyStore.Entry} implementations are provided:
*
* <ul>
* <li><b>KeyStore.PrivateKeyEntry</b>
! * <p> This type of entry holds a cryptographic {@code PrivateKey},
* which is optionally stored in a protected format to prevent
* unauthorized access. It is also accompanied by a certificate chain
* for the corresponding public key.
*
* <p> Private keys and certificate chains are used by a given entity for
* self-authentication. Applications for this authentication include software
* distribution organizations which sign JAR files as part of releasing
* and/or licensing software.
*
* <li><b>KeyStore.SecretKeyEntry</b>
! * <p> This type of entry holds a cryptographic {@code SecretKey},
* which is optionally stored in a protected format to prevent
* unauthorized access.
*
* <li><b>KeyStore.TrustedCertificateEntry</b>
! * <p> This type of entry contains a single public key {@code Certificate}
* belonging to another party. It is called a <i>trusted certificate</i>
* because the keystore owner trusts that the public key in the certificate
* indeed belongs to the identity identified by the <i>subject</i> (owner)
* of the certificate.
*
*** 119,130 ****
* try (FileInputStream fis = new FileInputStream("keyStoreName")) {
* ks.load(fis, password);
* }
* </pre>
*
! * To create an empty keystore using the above <code>load</code> method,
! * pass <code>null</code> as the <code>InputStream</code> argument.
*
* <p> Once the keystore has been loaded, it is possible
* to read existing entries from the keystore, or to write new entries
* into the keystore:
* <pre>
--- 119,130 ----
* try (FileInputStream fis = new FileInputStream("keyStoreName")) {
* ks.load(fis, password);
* }
* </pre>
*
! * To create an empty keystore using the above {@code load} method,
! * pass {@code null} as the {@code InputStream} argument.
*
* <p> Once the keystore has been loaded, it is possible
* to read existing entries from the keystore, or to write new entries
* into the keystore:
* <pre>
*** 154,166 ****
* (as is shown in the sample code above),
* different passwords or other protection parameters
* may also be used.
*
* <p> Every implementation of the Java platform is required to support
! * the following standard <code>KeyStore</code> type:
* <ul>
! * <li><tt>PKCS12</tt></li>
* </ul>
* This type is described in the <a href=
* "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyStore">
* KeyStore section</a> of the
* Java Cryptography Architecture Standard Algorithm Name Documentation.
--- 154,166 ----
* (as is shown in the sample code above),
* different passwords or other protection parameters
* may also be used.
*
* <p> Every implementation of the Java platform is required to support
! * the following standard {@code KeyStore} type:
* <ul>
! * <li>{@code PKCS12}</li>
* </ul>
* This type is described in the <a href=
* "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyStore">
* KeyStore section</a> of the
* Java Cryptography Architecture Standard Algorithm Name Documentation.
*** 199,209 ****
// Has this keystore been initialized (loaded)?
private boolean initialized = false;
/**
! * A marker interface for <code>KeyStore</code>
* {@link #load(KeyStore.LoadStoreParameter) load}
* and
* {@link #store(KeyStore.LoadStoreParameter) store}
* parameters.
*
--- 199,209 ----
// Has this keystore been initialized (loaded)?
private boolean initialized = false;
/**
! * A marker interface for {@code KeyStore}
* {@link #load(KeyStore.LoadStoreParameter) load}
* and
* {@link #store(KeyStore.LoadStoreParameter) store}
* parameters.
*
*** 363,385 ****
}
/**
* A marker interface for keystore protection parameters.
*
! * <p> The information stored in a <code>ProtectionParameter</code>
* object protects the contents of a keystore.
* For example, protection parameters may be used to check
* the integrity of keystore data, or to protect the
* confidentiality of sensitive keystore data
! * (such as a <code>PrivateKey</code>).
*
* @since 1.5
*/
public static interface ProtectionParameter { }
/**
! * A password-based implementation of <code>ProtectionParameter</code>.
*
* @since 1.5
*/
public static class PasswordProtection implements
ProtectionParameter, javax.security.auth.Destroyable {
--- 363,385 ----
}
/**
* A marker interface for keystore protection parameters.
*
! * <p> The information stored in a {@code ProtectionParameter}
* object protects the contents of a keystore.
* For example, protection parameters may be used to check
* the integrity of keystore data, or to protect the
* confidentiality of sensitive keystore data
! * (such as a {@code PrivateKey}).
*
* @since 1.5
*/
public static interface ProtectionParameter { }
/**
! * A password-based implementation of {@code ProtectionParameter}.
*
* @since 1.5
*/
public static class PasswordProtection implements
ProtectionParameter, javax.security.auth.Destroyable {
*** 390,403 ****
private volatile boolean destroyed = false;
/**
* Creates a password parameter.
*
! * <p> The specified <code>password</code> is cloned before it is stored
! * in the new <code>PasswordProtection</code> object.
*
! * @param password the password, which may be <code>null</code>
*/
public PasswordProtection(char[] password) {
this.password = (password == null) ? null : password.clone();
this.protectionAlgorithm = null;
this.protectionParameters = null;
--- 390,403 ----
private volatile boolean destroyed = false;
/**
* Creates a password parameter.
*
! * <p> The specified {@code password} is cloned before it is stored
! * in the new {@code PasswordProtection} object.
*
! * @param password the password, which may be {@code null}
*/
public PasswordProtection(char[] password) {
this.password = (password == null) ? null : password.clone();
this.protectionAlgorithm = null;
this.protectionParameters = null;
*** 474,484 ****
* If a clone of the array is created it is the caller's
* responsibility to zero out the password information
* after it is no longer needed.
*
* @see #destroy()
! * @return the password, which may be <code>null</code>
* @exception IllegalStateException if the password has
* been cleared (destroyed)
*/
public synchronized char[] getPassword() {
if (destroyed) {
--- 474,484 ----
* If a clone of the array is created it is the caller's
* responsibility to zero out the password information
* after it is no longer needed.
*
* @see #destroy()
! * @return the password, which may be {@code null}
* @exception IllegalStateException if the password has
* been cleared (destroyed)
*/
public synchronized char[] getPassword() {
if (destroyed) {
*** 544,554 ****
}
}
/**
! * A marker interface for <code>KeyStore</code> entry types.
*
* @since 1.5
*/
public static interface Entry {
--- 544,554 ----
}
}
/**
! * A marker interface for {@code KeyStore} entry types.
*
* @since 1.5
*/
public static interface Entry {
*** 588,598 ****
public String getValue();
}
}
/**
! * A <code>KeyStore</code> entry that holds a <code>PrivateKey</code>
* and corresponding certificate chain.
*
* @since 1.5
*/
public static final class PrivateKeyEntry implements Entry {
--- 588,598 ----
public String getValue();
}
}
/**
! * A {@code KeyStore} entry that holds a {@code PrivateKey}
* and corresponding certificate chain.
*
* @since 1.5
*/
public static final class PrivateKeyEntry implements Entry {
*** 600,631 ****
private final PrivateKey privKey;
private final Certificate[] chain;
private final Set<Attribute> attributes;
/**
! * Constructs a <code>PrivateKeyEntry</code> with a
! * <code>PrivateKey</code> and corresponding certificate chain.
*
! * <p> The specified <code>chain</code> is cloned before it is stored
! * in the new <code>PrivateKeyEntry</code> object.
*
! * @param privateKey the <code>PrivateKey</code>
! * @param chain an array of <code>Certificate</code>s
* representing the certificate chain.
* The chain must be ordered and contain a
! * <code>Certificate</code> at index 0
* corresponding to the private key.
*
* @exception NullPointerException if
! * <code>privateKey</code> or <code>chain</code>
! * is <code>null</code>
* @exception IllegalArgumentException if the specified chain has a
* length of 0, if the specified chain does not contain
! * <code>Certificate</code>s of the same type,
! * or if the <code>PrivateKey</code> algorithm
! * does not match the algorithm of the <code>PublicKey</code>
! * in the end entity <code>Certificate</code> (at index 0)
*/
public PrivateKeyEntry(PrivateKey privateKey, Certificate[] chain) {
this(privateKey, chain, Collections.<Attribute>emptySet());
}
--- 600,631 ----
private final PrivateKey privKey;
private final Certificate[] chain;
private final Set<Attribute> attributes;
/**
! * Constructs a {@code PrivateKeyEntry} with a
! * {@code PrivateKey} and corresponding certificate chain.
*
! * <p> The specified {@code chain} is cloned before it is stored
! * in the new {@code PrivateKeyEntry} object.
*
! * @param privateKey the {@code PrivateKey}
! * @param chain an array of {@code Certificate}s
* representing the certificate chain.
* The chain must be ordered and contain a
! * {@code Certificate} at index 0
* corresponding to the private key.
*
* @exception NullPointerException if
! * {@code privateKey} or {@code chain}
! * is {@code null}
* @exception IllegalArgumentException if the specified chain has a
* length of 0, if the specified chain does not contain
! * {@code Certificate}s of the same type,
! * or if the {@code PrivateKey} algorithm
! * does not match the algorithm of the {@code PublicKey}
! * in the end entity {@code Certificate} (at index 0)
*/
public PrivateKeyEntry(PrivateKey privateKey, Certificate[] chain) {
this(privateKey, chain, Collections.<Attribute>emptySet());
}
*** 697,738 ****
this.attributes =
Collections.unmodifiableSet(new HashSet<>(attributes));
}
/**
! * Gets the <code>PrivateKey</code> from this entry.
*
! * @return the <code>PrivateKey</code> from this entry
*/
public PrivateKey getPrivateKey() {
return privKey;
}
/**
! * Gets the <code>Certificate</code> chain from this entry.
*
* <p> The stored chain is cloned before being returned.
*
! * @return an array of <code>Certificate</code>s corresponding
* to the certificate chain for the public key.
* If the certificates are of type X.509,
* the runtime type of the returned array is
! * <code>X509Certificate[]</code>.
*/
public Certificate[] getCertificateChain() {
return chain.clone();
}
/**
! * Gets the end entity <code>Certificate</code>
* from the certificate chain in this entry.
*
! * @return the end entity <code>Certificate</code> (at index 0)
* from the certificate chain in this entry.
* If the certificate is of type X.509,
* the runtime type of the returned certificate is
! * <code>X509Certificate</code>.
*/
public Certificate getCertificate() {
return chain[0];
}
--- 697,738 ----
this.attributes =
Collections.unmodifiableSet(new HashSet<>(attributes));
}
/**
! * Gets the {@code PrivateKey} from this entry.
*
! * @return the {@code PrivateKey} from this entry
*/
public PrivateKey getPrivateKey() {
return privKey;
}
/**
! * Gets the {@code Certificate} chain from this entry.
*
* <p> The stored chain is cloned before being returned.
*
! * @return an array of {@code Certificate}s corresponding
* to the certificate chain for the public key.
* If the certificates are of type X.509,
* the runtime type of the returned array is
! * {@code X509Certificate[]}.
*/
public Certificate[] getCertificateChain() {
return chain.clone();
}
/**
! * Gets the end entity {@code Certificate}
* from the certificate chain in this entry.
*
! * @return the end entity {@code Certificate} (at index 0)
* from the certificate chain in this entry.
* If the certificate is of type X.509,
* the runtime type of the returned certificate is
! * {@code X509Certificate}.
*/
public Certificate getCertificate() {
return chain[0];
}
*** 765,791 ****
}
}
/**
! * A <code>KeyStore</code> entry that holds a <code>SecretKey</code>.
*
* @since 1.5
*/
public static final class SecretKeyEntry implements Entry {
private final SecretKey sKey;
private final Set<Attribute> attributes;
/**
! * Constructs a <code>SecretKeyEntry</code> with a
! * <code>SecretKey</code>.
*
! * @param secretKey the <code>SecretKey</code>
*
! * @exception NullPointerException if <code>secretKey</code>
! * is <code>null</code>
*/
public SecretKeyEntry(SecretKey secretKey) {
if (secretKey == null) {
throw new NullPointerException("invalid null input");
}
--- 765,791 ----
}
}
/**
! * A {@code KeyStore} entry that holds a {@code SecretKey}.
*
* @since 1.5
*/
public static final class SecretKeyEntry implements Entry {
private final SecretKey sKey;
private final Set<Attribute> attributes;
/**
! * Constructs a {@code SecretKeyEntry} with a
! * {@code SecretKey}.
*
! * @param secretKey the {@code SecretKey}
*
! * @exception NullPointerException if {@code secretKey}
! * is {@code null}
*/
public SecretKeyEntry(SecretKey secretKey) {
if (secretKey == null) {
throw new NullPointerException("invalid null input");
}
*** 817,829 ****
this.attributes =
Collections.unmodifiableSet(new HashSet<>(attributes));
}
/**
! * Gets the <code>SecretKey</code> from this entry.
*
! * @return the <code>SecretKey</code> from this entry
*/
public SecretKey getSecretKey() {
return sKey;
}
--- 817,829 ----
this.attributes =
Collections.unmodifiableSet(new HashSet<>(attributes));
}
/**
! * Gets the {@code SecretKey} from this entry.
*
! * @return the {@code SecretKey} from this entry
*/
public SecretKey getSecretKey() {
return sKey;
}
*** 848,875 ****
return "Secret key entry with algorithm " + sKey.getAlgorithm();
}
}
/**
! * A <code>KeyStore</code> entry that holds a trusted
! * <code>Certificate</code>.
*
* @since 1.5
*/
public static final class TrustedCertificateEntry implements Entry {
private final Certificate cert;
private final Set<Attribute> attributes;
/**
! * Constructs a <code>TrustedCertificateEntry</code> with a
! * trusted <code>Certificate</code>.
*
! * @param trustedCert the trusted <code>Certificate</code>
*
* @exception NullPointerException if
! * <code>trustedCert</code> is <code>null</code>
*/
public TrustedCertificateEntry(Certificate trustedCert) {
if (trustedCert == null) {
throw new NullPointerException("invalid null input");
}
--- 848,875 ----
return "Secret key entry with algorithm " + sKey.getAlgorithm();
}
}
/**
! * A {@code KeyStore} entry that holds a trusted
! * {@code Certificate}.
*
* @since 1.5
*/
public static final class TrustedCertificateEntry implements Entry {
private final Certificate cert;
private final Set<Attribute> attributes;
/**
! * Constructs a {@code TrustedCertificateEntry} with a
! * trusted {@code Certificate}.
*
! * @param trustedCert the trusted {@code Certificate}
*
* @exception NullPointerException if
! * {@code trustedCert} is {@code null}
*/
public TrustedCertificateEntry(Certificate trustedCert) {
if (trustedCert == null) {
throw new NullPointerException("invalid null input");
}
*** 901,913 ****
this.attributes =
Collections.unmodifiableSet(new HashSet<>(attributes));
}
/**
! * Gets the trusted <code>Certficate</code> from this entry.
*
! * @return the trusted <code>Certificate</code> from this entry
*/
public Certificate getTrustedCertificate() {
return cert;
}
--- 901,913 ----
this.attributes =
Collections.unmodifiableSet(new HashSet<>(attributes));
}
/**
! * Gets the trusted {@code Certficate} from this entry.
*
! * @return the trusted {@code Certificate} from this entry
*/
public Certificate getTrustedCertificate() {
return cert;
}
*** 1127,1139 ****
}
/**
* 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
--- 1127,1139 ----
}
/**
* 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
*** 1157,1169 ****
}
/**
* 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
* followed by zero or more certificate authorities), or null if the given alias
--- 1157,1169 ----
}
/**
* 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
* followed by zero or more certificate authorities), or null if the given alias
*** 1183,1201 ****
/**
* 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
* is returned.
*
* @param alias the alias name
*
--- 1183,1201 ----
/**
* 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
* is returned.
*
* @param alias the alias name
*
*** 1236,1246 ****
/**
* 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
--- 1236,1246 ----
/**
* 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
*** 1249,1259 ****
* @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 keystore has not been initialized
* (loaded), the given key cannot be protected, or this operation fails
* for some other reason
*/
--- 1249,1259 ----
* @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 keystore has not been initialized
* (loaded), the given key cannot be protected, or this operation fails
* for some other reason
*/
*** 1276,1300 ****
/**
* 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. If the
! * underlying keystore implementation is of type <code>jks</code>,
! * <code>key</code> must be encoded as an
! * <code>EncryptedPrivateKeyInfo</code> as defined in the PKCS #8 standard.
*
* <p>If the given alias already exists, the keystore information
* associated with it is overridden by the given key (and possibly
* certificate chain).
*
* @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 the keystore has not been initialized
* (loaded), or if this operation fails for some other reason.
*/
public final void setKeyEntry(String alias, byte[] key,
--- 1276,1300 ----
/**
* 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. If the
! * underlying keystore implementation is of type {@code jks},
! * {@code key} must be encoded as an
! * {@code EncryptedPrivateKeyInfo} as defined in the PKCS #8 standard.
*
* <p>If the given alias already exists, the keystore information
* associated with it is overridden by the given key (and possibly
* certificate chain).
*
* @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 the keystore has not been initialized
* (loaded), or if this operation fails for some other reason.
*/
public final void setKeyEntry(String alias, byte[] key,
*** 1309,1321 ****
/**
* Assigns the given trusted 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
--- 1309,1321 ----
/**
* Assigns the given trusted 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
*** 1404,1416 ****
return keyStoreSpi.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 entry, false otherwise.
--- 1404,1416 ----
return keyStoreSpi.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 entry, false otherwise.
*** 1427,1439 ****
return keyStoreSpi.engineIsKeyEntry(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.
--- 1427,1439 ----
return keyStoreSpi.engineIsKeyEntry(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.
*** 1454,1472 ****
* 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.
*
--- 1454,1472 ----
* 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.
*
*** 1509,1526 ****
}
keyStoreSpi.engineStore(stream, password);
}
/**
! * Stores this keystore using the given <code>LoadStoreParameter</code>.
*
! * @param param the <code>LoadStoreParameter</code>
* that specifies how to store the keystore,
! * which may be <code>null</code>
*
* @exception IllegalArgumentException if the given
! * <code>LoadStoreParameter</code>
* input is not recognized
* @exception KeyStoreException if the keystore has not been initialized
* (loaded)
* @exception IOException if there was an I/O problem with data
* @exception NoSuchAlgorithmException if the appropriate data integrity
--- 1509,1526 ----
}
keyStoreSpi.engineStore(stream, password);
}
/**
! * Stores this keystore using the given {@code LoadStoreParameter}.
*
! * @param param the {@code LoadStoreParameter}
* that specifies how to store the keystore,
! * which may be {@code null}
*
* @exception IllegalArgumentException if the given
! * {@code LoadStoreParameter}
* input is not recognized
* @exception KeyStoreException if the keystore has not been initialized
* (loaded)
* @exception IOException if there was an I/O problem with data
* @exception NoSuchAlgorithmException if the appropriate data integrity
*** 1547,1574 ****
* or to check the integrity of the keystore data.
* If a password is not given for integrity checking,
* then integrity checking is not performed.
*
* <p>In order to create an empty keystore, or if the keystore cannot
! * be initialized from a stream, pass <code>null</code>
! * as the <code>stream</code> argument.
*
* <p> Note that if this keystore has already been loaded, it is
* reinitialized and loaded again from the given input stream.
*
* @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
*/
--- 1547,1574 ----
* or to check the integrity of the keystore data.
* If a password is not given for integrity checking,
* then integrity checking is not performed.
*
* <p>In order to create an empty keystore, or if the keystore cannot
! * be initialized from a stream, pass {@code null}
! * as the {@code stream} argument.
*
* <p> Note that if this keystore has already been loaded, it is
* reinitialized and loaded again from the given input stream.
*
* @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
*/
*** 1578,1605 ****
keyStoreSpi.engineLoad(stream, password);
initialized = true;
}
/**
! * Loads this keystore using the given <code>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>LoadStoreParameter</code>
* that specifies how to load the keystore,
! * which may be <code>null</code>
*
* @exception IllegalArgumentException if the given
! * <code>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
*
--- 1578,1605 ----
keyStoreSpi.engineLoad(stream, password);
initialized = true;
}
/**
! * Loads this keystore using the given {@code 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 LoadStoreParameter}
* that specifies how to load the keystore,
! * which may be {@code null}
*
* @exception IllegalArgumentException if the given
! * {@code 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
*
*** 1612,1641 ****
keyStoreSpi.engineLoad(param);
initialized = true;
}
/**
! * Gets a keystore <code>Entry</code> for the specified alias
* with the specified protection parameter.
*
! * @param alias get the keystore <code>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 keystore <code>Entry</code> for the specified alias,
! * or <code>null</code> if there is no such entry
*
* @exception NullPointerException if
! * <code>alias</code> is <code>null</code>
* @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)
* @exception KeyStoreException if the keystore has not been initialized
* (loaded).
* @see #setEntry(String, KeyStore.Entry, KeyStore.ProtectionParameter)
*
--- 1612,1641 ----
keyStoreSpi.engineLoad(param);
initialized = true;
}
/**
! * Gets a keystore {@code Entry} for the specified alias
* with the specified protection parameter.
*
! * @param alias get the keystore {@code Entry} for this alias
! * @param protParam the {@code ProtectionParameter}
! * used to protect the {@code Entry},
! * which may be {@code null}
*
! * @return the keystore {@code Entry} for the specified alias,
! * or {@code null} if there is no such entry
*
* @exception NullPointerException if
! * {@code alias} is {@code null}
* @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)
* @exception KeyStoreException if the keystore has not been initialized
* (loaded).
* @see #setEntry(String, KeyStore.Entry, KeyStore.ProtectionParameter)
*
*** 1653,1678 ****
}
return keyStoreSpi.engineGetEntry(alias, protParam);
}
/**
! * Saves a keystore <code>Entry</code> under the specified alias.
* The 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 keystore <code>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 NullPointerException if
! * <code>alias</code> or <code>entry</code>
! * is <code>null</code>
* @exception KeyStoreException if the keystore has not been initialized
* (loaded), or if this operation fails for some other reason
*
* @see #getEntry(String, KeyStore.ProtectionParameter)
*
--- 1653,1678 ----
}
return keyStoreSpi.engineGetEntry(alias, protParam);
}
/**
! * Saves a keystore {@code Entry} under the specified alias.
* The 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 keystore {@code 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 NullPointerException if
! * {@code alias} or {@code entry}
! * is {@code null}
* @exception KeyStoreException if the keystore has not been initialized
* (loaded), or if this operation fails for some other reason
*
* @see #getEntry(String, KeyStore.ProtectionParameter)
*
*** 1689,1712 ****
}
keyStoreSpi.engineSetEntry(alias, entry, protParam);
}
/**
! * 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
*
* @exception NullPointerException if
! * <code>alias</code> or <code>entryClass</code>
! * is <code>null</code>
* @exception KeyStoreException if the keystore has not been
* initialized (loaded)
*
* @since 1.5
*/
--- 1689,1712 ----
}
keyStoreSpi.engineSetEntry(alias, entry, protParam);
}
/**
! * 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
*
* @exception NullPointerException if
! * {@code alias} or {@code entryClass}
! * is {@code null}
* @exception KeyStoreException if the keystore has not been
* initialized (loaded)
*
* @since 1.5
*/
*** 1762,1772 ****
public abstract KeyStore getKeyStore() throws KeyStoreException;
/**
* Returns the ProtectionParameters that should be used to obtain
* the {@link KeyStore.Entry Entry} with the given alias.
! * The <code>getKeyStore</code> method must be invoked before this
* method may be called.
*
* @return the ProtectionParameters that should be used to obtain
* the {@link KeyStore.Entry Entry} with the given alias.
* @param alias the alias of the KeyStore entry
--- 1762,1772 ----
public abstract KeyStore getKeyStore() throws KeyStoreException;
/**
* Returns the ProtectionParameters that should be used to obtain
* the {@link KeyStore.Entry Entry} with the given alias.
! * The {@code getKeyStore} method must be invoked before this
* method may be called.
*
* @return the ProtectionParameters that should be used to obtain
* the {@link KeyStore.Entry Entry} with the given alias.
* @param alias the alias of the KeyStore entry
*** 1780,1792 ****
throws KeyStoreException;
/**
* Returns a new Builder that encapsulates the given KeyStore.
* The {@linkplain #getKeyStore} method of the returned object
! * will return <code>keyStore</code>, the {@linkplain
* #getProtectionParameter getProtectionParameter()} method will
! * return <code>protectionParameters</code>.
*
* <p> This is useful if an existing KeyStore object needs to be
* used with Builder-based APIs.
*
* @return a new Builder object
--- 1780,1792 ----
throws KeyStoreException;
/**
* Returns a new Builder that encapsulates the given KeyStore.
* The {@linkplain #getKeyStore} method of the returned object
! * will return {@code keyStore}, the {@linkplain
* #getProtectionParameter getProtectionParameter()} method will
! * return {@code protectionParameters}.
*
* <p> This is useful if an existing KeyStore object needs to be
* used with Builder-based APIs.
*
* @return a new Builder object
*** 1830,1862 ****
/**
* Returns a new Builder object.
*
* <p>The first call to the {@link #getKeyStore} method on the returned
! * builder will create a KeyStore of type <code>type</code> and call
* its {@link KeyStore#load load()} method.
! * The <code>inputStream</code> argument is constructed from
! * <code>file</code>.
! * If <code>protection</code> is a
! * <code>PasswordProtection</code>, the password is obtained by
! * calling the <code>getPassword</code> method.
! * Otherwise, if <code>protection</code> is a
! * <code>CallbackHandlerProtection</code>, the password is obtained
* by invoking the CallbackHandler.
*
* <p>Subsequent calls to {@link #getKeyStore} return the same object
* as the initial call. If the initial call to failed with a
* KeyStoreException, subsequent calls also throw a
* KeyStoreException.
*
! * <p>The KeyStore is instantiated from <code>provider</code> if
* non-null. Otherwise, all installed providers are searched.
*
* <p>Calls to {@link #getProtectionParameter getProtectionParameter()}
* will return a {@link KeyStore.PasswordProtection PasswordProtection}
* object encapsulating the password that was used to invoke the
! * <code>load</code> method.
*
* <p><em>Note</em> that the {@link #getKeyStore} method is executed
* within the {@link AccessControlContext} of the code invoking this
* method.
*
--- 1830,1862 ----
/**
* Returns a new Builder object.
*
* <p>The first call to the {@link #getKeyStore} method on the returned
! * builder will create a KeyStore of type {@code type} and call
* its {@link KeyStore#load load()} method.
! * The {@code inputStream} argument is constructed from
! * {@code file}.
! * If {@code protection} is a
! * {@code PasswordProtection}, the password is obtained by
! * calling the {@code getPassword} method.
! * Otherwise, if {@code protection} is a
! * {@code CallbackHandlerProtection}, the password is obtained
* by invoking the CallbackHandler.
*
* <p>Subsequent calls to {@link #getKeyStore} return the same object
* as the initial call. If the initial call to failed with a
* KeyStoreException, subsequent calls also throw a
* KeyStoreException.
*
! * <p>The KeyStore is instantiated from {@code provider} if
* non-null. Otherwise, all installed providers are searched.
*
* <p>Calls to {@link #getProtectionParameter getProtectionParameter()}
* will return a {@link KeyStore.PasswordProtection PasswordProtection}
* object encapsulating the password that was used to invoke the
! * {@code load} method.
*
* <p><em>Note</em> that the {@link #getKeyStore} method is executed
* within the {@link AccessControlContext} of the code invoking this
* method.
*
*** 2011,2031 ****
/**
* Returns a new Builder object.
*
* <p>Each call to the {@link #getKeyStore} method on the returned
! * builder will return a new KeyStore object of type <code>type</code>.
* Its {@link KeyStore#load(KeyStore.LoadStoreParameter) load()}
* method is invoked using a
! * <code>LoadStoreParameter</code> that encapsulates
! * <code>protection</code>.
*
! * <p>The KeyStore is instantiated from <code>provider</code> if
* non-null. Otherwise, all installed providers are searched.
*
* <p>Calls to {@link #getProtectionParameter getProtectionParameter()}
! * will return <code>protection</code>.
*
* <p><em>Note</em> that the {@link #getKeyStore} method is executed
* within the {@link AccessControlContext} of the code invoking this
* method.
*
--- 2011,2031 ----
/**
* Returns a new Builder object.
*
* <p>Each call to the {@link #getKeyStore} method on the returned
! * builder will return a new KeyStore object of type {@code type}.
* Its {@link KeyStore#load(KeyStore.LoadStoreParameter) load()}
* method is invoked using a
! * {@code LoadStoreParameter} that encapsulates
! * {@code protection}.
*
! * <p>The KeyStore is instantiated from {@code provider} if
* non-null. Otherwise, all installed providers are searched.
*
* <p>Calls to {@link #getProtectionParameter getProtectionParameter()}
! * will return {@code protection}.
*
* <p><em>Note</em> that the {@link #getKeyStore} method is executed
* within the {@link AccessControlContext} of the code invoking this
* method.
*