java.security
Class KeyStore

java.lang.Object
  extended by java.security.KeyStore

public class KeyStore
extends Object

Keystore represents an in-memory collection of keys and certificates. There are two types of entries:

Key Entry

This type of keystore entry store sensitive crytographic key information in a protected format.Typically this is a secret key or a private key with a certificate chain.

Trusted Ceritificate Entry

This type of keystore entry contains a single public key certificate belonging to annother entity. It is called trusted because the keystore owner trusts that the certificates belongs to the subject (owner) of the certificate.

Entries in a key store are referred to by their "alias": a simple unique string.

The structure and persistentence of the key store is not specified. Any method could be used to protect sensitive (private or secret) keys. Smart cards or integrated cryptographic engines could be used or the keystore could be simply stored in a file.

See Also:
Certificate, Key

Constructor Summary
protected KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type)
          Creates an instance of KeyStore
 
Method Summary
 Enumeration<String> aliases()
          Generates a list of all the aliases in the keystore.
 boolean containsAlias(String alias)
          Determines if the keystore contains the specified alias.
 void deleteEntry(String alias)
          Deletes the entry for the specified entry.
 Certificate getCertificate(String alias)
          Gets a Certificate for the specified alias.
 String getCertificateAlias(Certificate cert)
          Determines if the keystore contains the specified certificate entry and returns the alias.
 Certificate[] getCertificateChain(String alias)
          Gets a Certificate chain for the specified alias.
 Date getCreationDate(String alias)
          Gets entry creation date for the specified alias.
static String getDefaultType()
          Returns the default KeyStore type.
static KeyStore getInstance(String type)
          Returns an instance of a KeyStore representing the specified type, from the first provider that implements it.
static KeyStore getInstance(String type, Provider provider)
          Returns an instance of a KeyStore representing the specified type, from the specified provider.
static KeyStore getInstance(String type, String provider)
          Returns an instance of a KeyStore representing the specified type, from the named provider.
 Key getKey(String alias, char[] password)
          Returns the key associated with given alias using the supplied password.
 Provider getProvider()
          Gets the provider that the class is from.
 String getType()
          Returns the type of the KeyStore supported
 boolean isCertificateEntry(String alias)
          Determines if the keystore contains a certificate entry for the specified alias.
 boolean isKeyEntry(String alias)
          Determines if the keystore contains a key entry for the specified alias.
 void load(InputStream stream, char[] password)
          Loads the keystore from the specified input stream and it uses the specified password to check for integrity if supplied.
 void setCertificateEntry(String alias, Certificate cert)
          Assign the certificate to the alias in the keystore.
 void setKeyEntry(String alias, byte[] key, Certificate[] chain)
          Assign the key to the alias in the keystore.
 void setKeyEntry(String alias, Key key, char[] password, Certificate[] chain)
          Assign the key to the alias in the keystore, protecting it with the given password.
 int size()
          Returns the number of entries in the keystore.
 void store(OutputStream stream, char[] password)
          Stores the keystore in the specified output stream and it uses the specified key it keep it secure.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

KeyStore

protected KeyStore(KeyStoreSpi keyStoreSpi,
                   Provider provider,
                   String type)
Creates an instance of KeyStore

Parameters:
keyStoreSpi - A KeyStore engine to use
provider - A provider to use
type - The type of KeyStore
Method Detail

getInstance

public static KeyStore getInstance(String type)
                            throws KeyStoreException
Returns an instance of a KeyStore representing the specified type, from the first provider that implements it.

Parameters:
type - the type of keystore to create.
Returns:
a KeyStore repesenting the desired type.
Throws:
KeyStoreException - if the designated type of is not implemented by any provider, or the implementation could not be instantiated.
IllegalArgumentException - if type is null or is an empty string.

getInstance

public static KeyStore getInstance(String type,
                                   String provider)
                            throws KeyStoreException,
                                   NoSuchProviderException
Returns an instance of a KeyStore representing the specified type, from the named provider.

Parameters:
type - the type of keystore to create.
provider - the name of the provider to use.
Returns:
a KeyStore repesenting the desired type.
Throws:
KeyStoreException - if the designated type is not implemented by the given provider.
NoSuchProviderException - if the provider is not found.
IllegalArgumentException - if either type or provider is null or empty.

getInstance

public static KeyStore getInstance(String type,
                                   Provider provider)
                            throws KeyStoreException
Returns an instance of a KeyStore representing the specified type, from the specified provider.

Parameters:
type - the type of keystore to create.
provider - the provider to use.
Returns:
a KeyStore repesenting the desired type.
Throws:
KeyStoreException - if the designated type is not implemented by the given provider.
IllegalArgumentException - if either type or provider is null, or if type is an empty string.
Since:
1.4

getDefaultType

public static final String getDefaultType()
Returns the default KeyStore type. This method looks up the type in <JAVA_HOME>/lib/security/java.security with the property "keystore.type" or if that fails then "gkr" .


getProvider

public final Provider getProvider()
Gets the provider that the class is from.

Returns:
the provider of this class

getType

public final String getType()
Returns the type of the KeyStore supported

Returns:
A string with the type of KeyStore

getKey

public final Key getKey(String alias,
                        char[] password)
                 throws KeyStoreException,
                        NoSuchAlgorithmException,
                        UnrecoverableKeyException
Returns the key associated with given alias using the supplied password.

Parameters:
alias - an alias for the key to get
password - password to access key with
Returns:
the requested key, or null otherwise
Throws:
NoSuchAlgorithmException - if there is no algorithm for recovering the key
UnrecoverableKeyException - key cannot be reocovered (wrong password).
KeyStoreException

getCertificateChain

public final Certificate[] getCertificateChain(String alias)
                                        throws KeyStoreException
Gets a Certificate chain for the specified alias.

Parameters:
alias - the alias name
Returns:
a chain of Certificates ( ordered from the user's certificate to the Certificate Authority's ) or null if the alias does not exist or there is no certificate chain for the alias ( the alias refers to a trusted certificate entry or there is no entry).
Throws:
KeyStoreException

getCertificate

public final Certificate getCertificate(String alias)
                                 throws KeyStoreException
Gets a Certificate for the specified alias. If there is a trusted certificate entry then that is returned. it there is a key entry with a certificate chain then the first certificate is return or else null.

Parameters:
alias - the alias name
Returns:
a Certificate or null if the alias does not exist or there is no certificate for the alias
Throws:
KeyStoreException

getCreationDate

public final Date getCreationDate(String alias)
                           throws KeyStoreException
Gets entry creation date for the specified alias.

Parameters:
alias - the alias name
Throws:
KeyStoreException

setKeyEntry

public final void setKeyEntry(String alias,
                              Key key,
                              char[] password,
                              Certificate[] chain)
                       throws KeyStoreException
Assign the key to the alias in the keystore, protecting it with the given password. It will overwrite an existing entry and if the key is a PrivateKey, also add the certificate chain representing the corresponding public key.

Parameters:
alias - the alias name
key - the key to add
chain - the certificate chain for the corresponding public key
Throws:
KeyStoreException - if it fails

setKeyEntry

public final void setKeyEntry(String alias,
                              byte[] key,
                              Certificate[] chain)
                       throws KeyStoreException
Assign the key to the alias in the keystore. It will overwrite an existing entry and if the key is a PrivateKey, also add the certificate chain representing the corresponding public key.

Parameters:
alias - the alias name
key - the key to add
chain - the certificate chain for the corresponding public key
Throws:
KeyStoreException - if it fails

setCertificateEntry

public final void setCertificateEntry(String alias,
                                      Certificate cert)
                               throws KeyStoreException
Assign the certificate to the alias in the keystore. It will overwrite an existing entry.

Parameters:
alias - the alias name
cert - the certificate to add
Throws:
KeyStoreException - if it fails

deleteEntry

public final void deleteEntry(String alias)
                       throws KeyStoreException
Deletes the entry for the specified entry.

Parameters:
alias - the alias name
Throws:
KeyStoreException - if it fails

aliases

public final Enumeration<String> aliases()
                                  throws KeyStoreException
Generates a list of all the aliases in the keystore.

Returns:
an Enumeration of the aliases
Throws:
KeyStoreException

containsAlias

public final boolean containsAlias(String alias)
                            throws KeyStoreException
Determines if the keystore contains the specified alias.

Parameters:
alias - the alias name
Returns:
true if it contains the alias, false otherwise
Throws:
KeyStoreException

size

public final int size()
               throws KeyStoreException
Returns the number of entries in the keystore.

Throws:
KeyStoreException

isKeyEntry

public final boolean isKeyEntry(String alias)
                         throws KeyStoreException
Determines if the keystore contains a key entry for the specified alias.

Parameters:
alias - the alias name
Returns:
true if it is a key entry, false otherwise
Throws:
KeyStoreException

isCertificateEntry

public final boolean isCertificateEntry(String alias)
                                 throws KeyStoreException
Determines if the keystore contains a certificate entry for the specified alias.

Parameters:
alias - the alias name
Returns:
true if it is a certificate entry, false otherwise
Throws:
KeyStoreException

getCertificateAlias

public final String getCertificateAlias(Certificate cert)
                                 throws KeyStoreException
Determines if the keystore contains the specified certificate entry and returns the alias. It checks every entry and for a key entry checks only the first certificate in the chain.

Parameters:
cert - Certificate to look for
Returns:
alias of first matching certificate, null if it does not exist.
Throws:
KeyStoreException

store

public final void store(OutputStream stream,
                        char[] password)
                 throws KeyStoreException,
                        IOException,
                        NoSuchAlgorithmException,
                        CertificateException
Stores the keystore in the specified output stream and it uses the specified key it keep it secure.

Parameters:
stream - the output stream to save the keystore to
password - the password to protect the keystore integrity with
Throws:
IOException - if an I/O error occurs.
NoSuchAlgorithmException - the data integrity algorithm used cannot be found.
CertificateException - if any certificates could not be stored in the output stream.
KeyStoreException

load

public final void load(InputStream stream,
                       char[] password)
                throws IOException,
                       NoSuchAlgorithmException,
                       CertificateException
Loads the keystore from the specified input stream and it uses the specified password to check for integrity if supplied.

Parameters:
stream - the input stream to load the keystore from
password - the password to check the keystore integrity with
Throws:
IOException - if an I/O error occurs.
NoSuchAlgorithmException - the data integrity algorithm used cannot be found.
CertificateException - if any certificates could not be stored in the output stream.