Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Class java.security.KeyStore

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

public abstract class KeyStore
extends Object
This abstract class represents an in-memory collection of private keys and associated certificate chains, for use in self-authentication. These keys and certificate chains are used by a given entity when it authenticates itself using public key certificates.

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

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.