java.security

Class 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, String provider) Returns an instance of a `KeyStore` representing the specified type, from the named provider.
static KeyStore	getInstance(String type, Provider provider) Returns an instance of a `KeyStore` representing the specified type, from the specified 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, Key key, char[] password, Certificate[] chain) Assign the key to the alias in the keystore, protecting it with the given password.
void	setKeyEntry(String alias, byte[] key, Certificate[] chain) Assign the key to the alias in the keystore.
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.

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

aliases

public final Enumeration<String> aliases()

Generates a list of all the aliases in the keystore.

Returns: an Enumeration of the aliases

containsAlias

public final boolean containsAlias(String alias)

Determines if the keystore contains the specified alias.

Parameters: alias the alias name

Returns: true if it contains the alias, false otherwise

deleteEntry

public final void deleteEntry(String alias)

Deletes the entry for the specified entry.

Parameters: alias the alias name

Throws: KeyStoreException if it fails

getCertificate

public final Certificate getCertificate(String alias)

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

getCertificateAlias

public final String getCertificateAlias(Certificate cert)

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.

getCertificateChain

public final Certificate[] getCertificateChain(String alias)

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).

getCreationDate

public final Date getCreationDate(String alias)

Gets entry creation date for the specified alias.

Parameters: alias the alias name

UNKNOWN: the entry creation date or null

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" .

getInstance

public static KeyStore getInstance(String type)

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)

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)

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

getKey

public final Key getKey(String alias, char[] password)

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).

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

isCertificateEntry

public final boolean isCertificateEntry(String alias)

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

isKeyEntry

public final boolean isKeyEntry(String alias)

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

load

public final 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.

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.

setCertificateEntry

public final void setCertificateEntry(String alias, Certificate cert)

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

setKeyEntry

public final 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. 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

UNKNOWN: the password to protect with

setKeyEntry

public final void setKeyEntry(String alias, byte[] key, Certificate[] chain)

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

size

public final int size()

Returns the number of entries in the keystore.

UNKNOWN: the number of keystore entries.

store

public final void store(OutputStream stream, char[] password)

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