Class java.security.KeyStore

java.lang.Object
    |
    +----java.security.KeyStore

public abstract class KeyStore

extends Object

Applications for this authentication include software distribution organizations which sign JAR files as part of releasing and/or licensing software.

Each private key, and associated certificate chain, is identified by an "alias" string. These strings distinguish among the different ways in which the entity may authenticate itself. For example, the entity may authenticate itself using different certificate authorities, or using different public key algorithms.

This abstract class also manages trusted keys, which are used to authenticate other parties.

Whether keystores are persistent, and the mechanisms used by the keystore if it is persistent, are not specified here. This allows use of a variety of techniques for protecting private keys. Smart cards or other integrated cryptographic engines (SafeKeyper) are one option, and simpler mechanisms such as files with encrypted private keys may also be used (in a variety of formats).

In-memory instances of this class should be protected as strongly as the private keys to which they provide access.

Since:

JDK1.2

Method Summary
Enumeration	aliases() Lists the alias names.
boolean	containsAlias(String alias) Checks if alias exists.
void	deleteEntry(String alias) Deletes the entry identified by alias.
Certificate	getCertificate(String alias) Returns the certificate associated with the given alias.
String	getCertificateAlias(Certificate cert) Returns the (alias) name of the first entry whose certificate matches the given certificate.
Certificate[]	getCertificateChain(String alias) Returns the certificate chain associated with the given alias.
Date	getCreationDate(String alias) Returns the creation date of the entry identified by the given alias.
static KeyStore	getInstance() Returns a new KeyStore object of the type configured in the security properties file for keystore.
PrivateKey	getPrivateKey(String alias, String password) Returns the private key associated with the given alias.
boolean	isCertificateEntry(String alias) Returns true if the entry identified by the given alias is a certificate entry, and false otherwise.
boolean	isKeyEntry(String alias) Returns true if the entry identified by the given alias is a private key entry, and false otherwise.
void	load(InputStream stream, String password) Loads the keystore from an input stream.
void	setCertificateEntry(String alias, Certificate cert) Assigns a certificate to the given alias.
void	setKeyEntry(String alias, PrivateKey key, String password, Certificate[] chain) Assigns a private key and certificate chain to the given alias.
void	setKeyEntry(String alias, byte[] key, Certificate[] chain) Assigns a protected private key and certificate chain to the given alias.
int	size() Retrieves the number of elements in this keystore.
void	store(OutputStream stream, String password) Stores the keystore data into an output stream.

 

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Method Detail

getInstance

public static final KeyStore getInstance() throws KeyStoreException

Returns a new KeyStore object of the type configured in the security properties file for keystore. If the security properties file does not contain an entry for keystore, an instance of the default KeyStore implementation (sun.security.tools.JavaKeyStore) is returned.

Returns:

the new KeyStore object

Throws:

KeyStoreException - if the KeyStore object cannot be created

getPrivateKey

public abstract PrivateKey getPrivateKey(String alias,
                                         String password) throws NoSuchAlgorithmException, UnrecoverableKeyException

Returns the private key associated with the given alias. The private key is recovered using the given password.

Parameters:

alias - the alias name

password - the password for recovering the key

Returns:

the private key, or null if the given alias does not exist, or the given alias does not have a private key

Throws:

NoSuchAlgorithmException - if the algorithm for recovering the private key could not be found

UnrecoverableKeyException - if the private key could not be recovered

getCertificateChain

public abstract Certificate[] getCertificateChain(String alias)

Returns the certificate chain associated with the given alias.

Parameters:

alias - the alias name

Returns:

the certificate chain (ordered with the user's certificate first and the root certificate authority last), or null if the given alias does not exist

getCertificate

public abstract Certificate getCertificate(String alias)

Returns the certificate associated with the given alias.

Parameters:

alias - the alias name

Returns:

the certificate, or null if the given alias does not exist

getCreationDate

public abstract Date getCreationDate(String alias)

Returns the creation date of the entry identified by the given alias.

Parameters:

alias - the alias name

Returns:

the creation date of this entry, or null if the given alias does not exist

setKeyEntry

public abstract void setKeyEntry(String alias,
                                 PrivateKey key,
                                 String password,
                                 Certificate[] chain) throws KeyStoreException

Assigns a private key and certificate chain to the given alias. The alias may already exist, in which case the private key and certificate chain associated with it are replaced by the private key and certificate chain provided in this call. The private key is protected with the given password.

Parameters:

alias - the alias name

key - the private key to be associated with the alias

password - the password to protect the private key

chain - the certificate chain to be associated with the alias

Throws:

KeyStoreException - if the private key cannot be protected, or this operation failed for some other reason

setKeyEntry

public abstract void setKeyEntry(String alias,
                                 byte[] key,
                                 Certificate[] chain) throws KeyStoreException

Assigns a protected private key and certificate chain to the given alias. The alias may already exist, in which case the private key and certificate chain associated with it are replaced by the private key and certificate chain provided in this call.

Parameters:

alias - the alias name

key - the protected private key to be associated with the alias

chain - the certificate chain to be associated with the alias

Throws:

KeyStoreException - if this operation failed

setCertificateEntry

public abstract void setCertificateEntry(String alias,
                                         Certificate cert) throws KeyStoreException

Assigns a certificate to the given alias. The alias may already exist, in which case the certificate associated with it is replaced by the certificate provided in this call.

Parameters:

alias - the alias name

cert - the certificate to be added

Throws:

KeyStoreException - if the given alias identifies a private key entry, or this operation failed for some other reason

deleteEntry

public abstract void deleteEntry(String alias) throws KeyStoreException

Deletes the entry identified by alias.

Parameters:

alias - the alias name

Throws:

KeyStoreException - if the entry could not be removed

aliases

public abstract Enumeration aliases()

Lists the alias names.

Returns:

enumeration of the alias names

containsAlias

public abstract boolean containsAlias(String alias)

Checks if alias exists.

Parameters:

alias - the alias name

Returns:

true if the alias exists, false otherwise

size

public abstract int size()

Retrieves the number of elements in this keystore.

Returns:

the number of elements in this keystore

isKeyEntry

public abstract boolean isKeyEntry(String alias)

Returns true if the entry identified by the given alias is a private key entry, and false otherwise.

Returns:

true if the entry identified by the given alias is a private key entry, false otherwise.

isCertificateEntry

public abstract boolean isCertificateEntry(String alias)

Returns true if the entry identified by the given alias is a certificate entry, and false otherwise.

Returns:

true if the entry identified by the given alias is a certificate entry, false otherwise.

getCertificateAlias

public abstract String getCertificateAlias(Certificate cert)

Returns the (alias) name of the first entry whose certificate matches the given certificate.

Parameters:

cert - the certificate to compare against

Returns:

the (alias) name of the first entry with matching certificate, or null if there is no such entry

store

public abstract void store(OutputStream stream,
                           String password) throws IOException, NoSuchAlgorithmException, CertificateException

Stores the keystore data into an output stream. An integrity check is created using the given password, and appended to the stream. Such streams would typically come from a file or a URL.

Parameters:

stream - the stream to which an encrypted keystore will be written.

password - the password to generate the integrity check

Throws:

IOException - if there was an I/O problem with data

NoSuchAlgorithmException - if the appropriate data integrity algorithm could not be found

CertificateException - if any of the certificates included in the keystore data could not be stored

load

public abstract void load(InputStream stream,
                          String password) throws IOException, NoSuchAlgorithmException, CertificateException

Loads the keystore from an input stream. The integrity of the keystore data is checked using the given password. Such streams would typically come from a file or a URL.

Parameters:

stream - the input stream holding an encrypted keystore

password - the password used to check the integrity of the keystore data

Throws:

IOException - if there was an I/O or format problem with data

NoSuchAlgorithmException - if the appropriate data integrity algorithm could not be found

CertificateException - if any of the certificates included in the keystore data could not be loaded