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:
- 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.
- The KeyStore is created, and is given that context.
- 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.
- The keystore may be accessed or modified in memory.
- 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:
- It's a simpler model, including only the features needed to
support X.509 authentication frameworks. This simplifies the work
involved in key management for most applications, because there
is no need to handle error cases such as being given a non-X509
certificate in the chain.
- This is used to hold all of the keys associated with a
single identity. Effectively, it only holds
Signer
objects enhanced to (a) hold chains of X509
certificate chains, and (b) to securely encrypt private keys in
external representations.
Notes:
- It'd be useful to associate attributes with these aliases.
For example, a flag enabling or disabling use of the cert chain, or
other annotations. (Useful for user interfacing, and policy options.)
- The file format may later be updated to use PKCS #12.
-
magic
-
-
version
-
-
KeyStore(AuthContext, Object)
- Constructs a new keystore, which will encrypt and decrypt private
keys using a passphrase found in the authentication context.
-
deleteAlias(String)
- Deletes the named alias, including both its private key and
the associated X.509 certificate chain.
-
getCertificateChain(String)
- Returns the certificate chain associated with the given alias
for this identity.
-
getPrivateKey(String)
- Returns the private key associated with the given alias
for this identity.
-
listAliases()
- Lists the alias names.
-
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.
-
replaceAlias(String, PrivateKey, X509Cert[])
- Replaces the existing alias values with new ones; or creates a
new alias with the given values
-
size()
- Says how many aliases there are.
-
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.
magic
public final static int magic
version
public final static int version
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
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
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
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
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
listAliases
public Enumeration listAliases()
- Lists the alias names.
- Returns:
- enumeration of the alias names
size
public int size()
- Says how many aliases there are.
- Returns:
- number of aliases
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.
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