All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class sun.security.ssl.KeyStore

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

public final class KeyStore
extends Object
This class supports an in-memory collection of private keys and their associated X.509 certificate chains, for use in self-authentication. It also supports an external form of that data, which encrypts the private keys to prevent unauthorized access.

These keys and certificate chains are used by a given entity when it authenticates itself using X.509 public key certificates. Applications for this authentication include SSL (clients and servers) and software distributors which sign JAR files.

A Keystore instance is typically used as follows:

  1. An authentication context is created. It may be initialized with the passphrase used to encrypt the keys; or that may be prompted for, as needed.
  2. The KeyStore is created, and is given that context.
  3. An input stream may be used to load the keys and certificate chains into the keystore. This uses the passphrase from the authentication context to decrypt the private keys and verify that the keystore has not been tampered with.
  4. The keystore may be accessed or modified in memory.
  5. An output stream may be stored with the certificates and encrypted private keys. Again, this uses the passphrase from the authentication context to encrypt keys and store data used to verify integrity of the keystore.

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


Each private key, and associated X.509 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 being authenticate itself using different certificate authorities, or using different public key algorithms. (Common algorithms include RSA, DSS/DSA, and Diffie-Hellman.)

It is useful to replace the certificate chain and private key which are associated with an alias. This kind of operation is commonly used to load a new certificate chain issued by a certificate authority, perhaps to replace one which has expired (or been revoked) or to stop using a temporary self-signed certificate.


Notable differences from the models encouraged by the interfaces in java.security.IdentityScope, called out here purely for expository purposes, include:


Notes:


Variable Index

 o magic
 o version

Constructor Index

 o KeyStore(AuthContext, Object)
Constructs a new keystore, which will encrypt and decrypt private keys using a passphrase found in the authentication context.

Method Index

 o deleteAlias(String)
Deletes the named alias, including both its private key and the associated X.509 certificate chain.
 o getCertificateChain(String)
Returns the certificate chain associated with the given alias for this identity.
 o getPrivateKey(String)
Returns the private key associated with the given alias for this identity.
 o listAliases()
Lists the alias names.
 o load(InputStream)
Loads the keystore from the indicated binary data stream, decrypting private keys using the passphrase provided in the authentication context from the constructor.
 o replaceAlias(String, PrivateKey, X509Cert[])
Replaces the existing alias values with new ones; or creates a new alias with the given values
 o size()
Says how many aliases there are.
 o store(OutputStream)
Stores the keystore data into the indicated binary data stream encrypting private keys using a passphrase found in the context provided to the constructor for this keystore.

Variables

 o magic
  public final static int magic
 o version
  public final static int version

Constructors

 o KeyStore
  public KeyStore(AuthContext context,
                  Object index)
Constructs a new keystore, which will encrypt and decrypt private keys using a passphrase found in the authentication context. The authentication context is used, rather than the passphrase, so that references to the passphrase can be easily controlled. Data is provided to (or taken from) this keystore using regular streams.

Both authentication contexts and the indices to them must be treated as security-sensitive data. If your code is able to call this constructor, it is because you are highly trusted in the first place ... being able to use this class to access private keys is a consequence of that trust.

Parameters:
context - holds passphrase used to encrypt/decrypt private keys
index - identifies the part of the context holding the passphrase

Methods

 o getCertificateChain
  public X509Cert[] getCertificateChain(String alias)
Returns the certificate chain associated with the given alias for this identity.

Parameters:
alias - the name of the certificate chain and private key
Returns:
the certificate chain, ordered with CAs at the end
 o getPrivateKey
  public PrivateKey getPrivateKey(String alias)
Returns the private key associated with the given alias for this identity.

Parameters:
alias - the name of the certificate chain and private key
Returns:
the private key
 o deleteAlias
  public void deleteAlias(String alias)
Deletes the named alias, including both its private key and the associated X.509 certificate chain.

Parameters:
alias - the name of the certificate chain and private key
 o replaceAlias
  public void replaceAlias(String alias,
                           PrivateKey key,
                           X509Cert chain[])
Replaces the existing alias values with new ones; or creates a new alias with the given values

Parameters:
alias - the name of the certificate chain and private key
key - the private key
Returns:
the certificate chain
 o listAliases
  public Enumeration listAliases()
Lists the alias names.

Returns:
enumeration of the alias names
 o size
  public int size()
Says how many aliases there are.

Returns:
number of aliases
 o store
  public void store(OutputStream arg) throws IOException, NoSuchAlgorithmException
Stores the keystore data into the indicated binary data stream encrypting private keys using a passphrase found in the context provided to the constructor for this keystore. Such streams would typically come from a file or a URL.

Parameters:
arg - stream to which an encrypted keystore will be written.
Throws: IOException
if there was an I/O problem with data
Throws: NoSuchAlgorithmException
if the appropriate hash or cipher algorithm could not be found.
 o load
  public void load(InputStream arg) throws IOException, NoSuchAlgorithmException
Loads the keystore from the indicated binary data stream, decrypting private keys using the passphrase provided in the authentication context from the constructor. Such streams would typically come from a file or a URL.

Parameters:
arg - input stream holding an encrypted keystore.
Throws: IOException
if there was an I/O or format problem with data
Throws: NoSuchAlgorithmException
if the appropriate hash or cipher algorithm could not be found.

All Packages  Class Hierarchy  This Package  Previous  Next  Index