The `KeyStore` Class

The KeyStore class is an engine class that supplies well-defined interfaces to access and modify the information in a keystore.

This class represents an in-memory collection of keys and certificates. KeyStore manages two types of entries:

Key Entry

This type of keystore entry holds very sensitive cryptographic key information, which is stored in a protected format to prevent unauthorized access. Typically, a key stored in this type of entry is a secret key, or a private key accompanied by the certificate chain authenticating the corresponding public key.

Private keys and certificate chains are used by a given entity for self-authentication using digital signatures. For example, software distribution organizations digitally sign JAR files as part of releasing, or licensing software, or both.

Trusted Certificate Entry

This type of entry contains a single public key certificate belonging to another party. It is called a trusted certificate because the keystore owner trusts that the public key in the certificate indeed belongs to the identity identified by the subject (owner) of the certificate.

This type of entry can be used to authenticate other parties.

Each entry in a keystore is identified by an alias string. In the case of private keys and their associated certificate chains, these strings distinguish among the different ways in which the entity can authenticate itself. For example, the entity might authenticate itself using different certificate authorities, or using different public key algorithms.

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

The main KeyStore methods are described here.

Creating a `KeyStore` Object

As with all engine classes, the way to get a KeyStore object is to call the getInstance static factory method on the KeyStore class:

static KeyStore getInstance(String type)

A caller can optionally specify the name of a provider or the Provider class, which will guarantee that the implementation of the type requested is from the named provider:

static KeyStore getInstance(String type, String provider)
static KeyStore getInstance(String type, Provider provider)

Loading a Particular Keystore into Memory

Before a KeyStore object can be used, the actual keystore data must be loaded into memory using the load method:

final void load(InputStream stream, char[] password)

The optional password is used to check the integrity of the keystore data. If no password is supplied, no integrity check is performed.

To create an empty keystore, you pass null as the InputStream argument to the load method.

Getting a List of the Keystore Aliases

All keystore entries are accessed using unique aliases. The aliases method returns an enumeration of the alias names in the keystore:

final Enumeration aliases()

Determining Keystore Entry Types

As stated in The KeyStore Class, there are two different types of entries in a keystore.

The following methods determine whether the entry specified by the given alias is a key/certificate or a trusted certificate entry, respectively:

final boolean isKeyEntry(String alias)
final boolean isCertificateEntry(String alias)

Adding, Setting or Deleting Keystore Entries

The setCertificateEntry method assigns a certificate to a specified alias:

final void setCertificateEntry(String alias, Certificate cert)

If alias doesn't exist, a trusted certificate entry with that alias is created. If alias exists and identifies a trusted certificate entry, the certificate associated with it is replaced by cert.

The setKeyEntry methods add (if alias doesn't yet exist) or set key entries:

final void setKeyEntry(String alias,
 Key key, 
 char[] password,
 Certificate[] chain)

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

In the method with key as a byte array, it is the bytes for a key in protected format. For example, in the keystore implementation supplied by the IBMJCE provider, the key byte array is expected to contain a protected private key, encoded as an EncryptedPrivateKeyInfo as defined in the PKCS #8 standard. In the other method, the password is the password used to protect the key.

The deleteEntry method deletes an entry:

final void deleteEntry(String alias)

Getting Information from the Keystore

The getKey method returns the key associated with the given alias. The key is recovered using the given password:

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

The following methods return the certificate, or certificate chain, respectively, associated with the given alias:

final Certificate getCertificate(String alias)
final Certificate[] getCertificateChain(String alias)

You can determine the name (alias) of the first entry whose certificate matches a given certificate using the following method:

final String getCertificateAlias(Certificate cert)

Saving the KeyStore

The in-memory keystore can be saved using the store method:

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

The password is used to calculate an integrity checksum of the keystore data, which is appended to the keystore data.