java.security

Class KeyStore


public class KeyStore
extends Object

Keystore represents an in-memory collection of keys and certificates. There are two types of entries:

Entries in a key store are referred to by their "alias": a simple unique string.

The structure and persistentence of the key store is not specified. Any method could be used to protect sensitive (private or secret) keys. Smart cards or integrated cryptographic engines could be used or the keystore could be simply stored in a file.

See Also:
Certificate, Key

Constructor Summary

KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type)
Creates an instance of KeyStore

Method Summary

Enumeration
aliases()
Generates a list of all the aliases in the keystore.
boolean
containsAlias(String alias)
Determines if the keystore contains the specified alias.
void
deleteEntry(String alias)
Deletes the entry for the specified entry.
Certificate
getCertificate(String alias)
Gets a Certificate for the specified alias.
String
getCertificateAlias(Certificate cert)
Determines if the keystore contains the specified certificate entry and returns the alias.
Certificate[]
getCertificateChain(String alias)
Gets a Certificate chain for the specified alias.
Date
getCreationDate(String alias)
Gets entry creation date for the specified alias.
static String
getDefaultType()
Returns the default KeyStore type.
static KeyStore
getInstance(String type)
Returns an instance of a KeyStore representing the specified type, from the first provider that implements it.
static KeyStore
getInstance(String type, String provider)
Returns an instance of a KeyStore representing the specified type, from the named provider.
static KeyStore
getInstance(String type, Provider provider)
Returns an instance of a KeyStore representing the specified type, from the specified provider.
Key
getKey(String alias, char[] password)
Returns the key associated with given alias using the supplied password.
Provider
getProvider()
Gets the provider that the class is from.
String
getType()
Returns the type of the KeyStore supported
boolean
isCertificateEntry(String alias)
Determines if the keystore contains a certificate entry for the specified alias.
boolean
isKeyEntry(String alias)
Determines if the keystore contains a key entry for the specified alias.
void
load(InputStream stream, char[] password)
Loads the keystore from the specified input stream and it uses the specified password to check for integrity if supplied.
void
setCertificateEntry(String alias, Certificate cert)
Assign the certificate to the alias in the keystore.
void
setKeyEntry(String alias, byte[] key, Certificate[] chain)
Assign the key to the alias in the keystore.
void
setKeyEntry(String alias, Key key, char[] password, Certificate[] chain)
Assign the key to the alias in the keystore, protecting it with the given password.
int
size()
Returns the number of entries in the keystore.
void
store(OutputStream stream, char[] password)
Stores the keystore in the specified output stream and it uses the specified key it keep it secure.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

KeyStore

protected KeyStore(KeyStoreSpi keyStoreSpi,
                   Provider provider,
                   String type)
Creates an instance of KeyStore
Parameters:
keyStoreSpi - A KeyStore engine to use
provider - A provider to use
type - The type of KeyStore

Method Details

aliases

public final Enumeration aliases()
            throws KeyStoreException
Generates a list of all the aliases in the keystore.
Returns:
an Enumeration of the aliases

containsAlias

public final boolean containsAlias(String alias)
            throws KeyStoreException
Determines if the keystore contains the specified alias.
Parameters:
alias - the alias name
Returns:
true if it contains the alias, false otherwise

deleteEntry

public final void deleteEntry(String alias)
            throws KeyStoreException
Deletes the entry for the specified entry.
Parameters:
alias - the alias name
Throws:
KeyStoreException - if it fails

getCertificate

public final Certificate getCertificate(String alias)
            throws KeyStoreException
Gets a Certificate for the specified alias. If there is a trusted certificate entry then that is returned. it there is a key entry with a certificate chain then the first certificate is return or else null.
Parameters:
alias - the alias name
Returns:
a Certificate or null if the alias does not exist or there is no certificate for the alias

getCertificateAlias

public final String getCertificateAlias(Certificate cert)
            throws KeyStoreException
Determines if the keystore contains the specified certificate entry and returns the alias. It checks every entry and for a key entry checks only the first certificate in the chain.
Parameters:
cert - Certificate to look for
Returns:
alias of first matching certificate, null if it does not exist.

getCertificateChain

public final Certificate[] getCertificateChain(String alias)
            throws KeyStoreException
Gets a Certificate chain for the specified alias.
Parameters:
alias - the alias name
Returns:
a chain of Certificates ( ordered from the user's certificate to the Certificate Authority's ) or null if the alias does not exist or there is no certificate chain for the alias ( the alias refers to a trusted certificate entry or there is no entry).

getCreationDate

public final Date getCreationDate(String alias)
            throws KeyStoreException
Gets entry creation date for the specified alias.
Parameters:
alias - the alias name

getDefaultType

public static final String getDefaultType()
Returns the default KeyStore type. This method looks up the type in <JAVA_HOME>/lib/security/java.security with the property "keystore.type" or if that fails then "gkr" .

getInstance

public static KeyStore getInstance(String type)
            throws KeyStoreException
Returns an instance of a KeyStore representing the specified type, from the first provider that implements it.
Parameters:
type - the type of keystore to create.
Returns:
a KeyStore repesenting the desired type.
Throws:
KeyStoreException - if the designated type of is not implemented by any provider, or the implementation could not be instantiated.
IllegalArgumentException - if type is null or is an empty string.

getInstance

public static KeyStore getInstance(String type,
                                   String provider)
            throws KeyStoreException,
                   NoSuchProviderException
Returns an instance of a KeyStore representing the specified type, from the named provider.
Parameters:
type - the type of keystore to create.
provider - the name of the provider to use.
Returns:
a KeyStore repesenting the desired type.
Throws:
KeyStoreException - if the designated type is not implemented by the given provider.
NoSuchProviderException - if the provider is not found.
IllegalArgumentException - if either type or provider is null or empty.

getInstance

public static KeyStore getInstance(String type,
                                   Provider provider)
            throws KeyStoreException
Returns an instance of a KeyStore representing the specified type, from the specified provider.
Parameters:
type - the type of keystore to create.
provider - the provider to use.
Returns:
a KeyStore repesenting the desired type.
Throws:
KeyStoreException - if the designated type is not implemented by the given provider.
IllegalArgumentException - if either type or provider is null, or if type is an empty string.
Since:
1.4

getKey

public final Key getKey(String alias,
                        char[] password)
            throws KeyStoreException,
                   NoSuchAlgorithmException,
                   UnrecoverableKeyException
Returns the key associated with given alias using the supplied password.
Parameters:
alias - an alias for the key to get
password - password to access key with
Returns:
the requested key, or null otherwise
Throws:
NoSuchAlgorithmException - if there is no algorithm for recovering the key
UnrecoverableKeyException - key cannot be reocovered (wrong password).

getProvider

public final Provider getProvider()
Gets the provider that the class is from.
Returns:
the provider of this class

getType

public final String getType()
Returns the type of the KeyStore supported
Returns:
A string with the type of KeyStore

isCertificateEntry

public final boolean isCertificateEntry(String alias)
            throws KeyStoreException
Determines if the keystore contains a certificate entry for the specified alias.
Parameters:
alias - the alias name
Returns:
true if it is a certificate entry, false otherwise

isKeyEntry

public final boolean isKeyEntry(String alias)
            throws KeyStoreException
Determines if the keystore contains a key entry for the specified alias.
Parameters:
alias - the alias name
Returns:
true if it is a key entry, false otherwise

load

public final void load(InputStream stream,
                       char[] password)
            throws IOException,
                   NoSuchAlgorithmException,
                   CertificateException
Loads the keystore from the specified input stream and it uses the specified password to check for integrity if supplied.
Parameters:
stream - the input stream to load the keystore from
password - the password to check the keystore integrity with
Throws:
IOException - if an I/O error occurs.
NoSuchAlgorithmException - the data integrity algorithm used cannot be found.
CertificateException - if any certificates could not be stored in the output stream.

setCertificateEntry

public final void setCertificateEntry(String alias,
                                      Certificate cert)
            throws KeyStoreException
Assign the certificate to the alias in the keystore. It will overwrite an existing entry.
Parameters:
alias - the alias name
cert - the certificate to add
Throws:
KeyStoreException - if it fails

setKeyEntry

public final void setKeyEntry(String alias,
                              byte[] key,
                              Certificate[] chain)
            throws KeyStoreException
Assign the key to the alias in the keystore. It will overwrite an existing entry and if the key is a PrivateKey, also add the certificate chain representing the corresponding public key.
Parameters:
alias - the alias name
key - the key to add
chain - the certificate chain for the corresponding public key
Throws:
KeyStoreException - if it fails

setKeyEntry

public final void setKeyEntry(String alias,
                              Key key,
                              char[] password,
                              Certificate[] chain)
            throws KeyStoreException
Assign the key to the alias in the keystore, protecting it with the given password. It will overwrite an existing entry and if the key is a PrivateKey, also add the certificate chain representing the corresponding public key.
Parameters:
alias - the alias name
key - the key to add
chain - the certificate chain for the corresponding public key
Throws:
KeyStoreException - if it fails

size

public final int size()
            throws KeyStoreException
Returns the number of entries in the keystore.

store

public final void store(OutputStream stream,
                        char[] password)
            throws KeyStoreException,
                   IOException,
                   NoSuchAlgorithmException,
                   CertificateException
Stores the keystore in the specified output stream and it uses the specified key it keep it secure.
Parameters:
stream - the output stream to save the keystore to
password - the password to protect the keystore integrity with
Throws:
IOException - if an I/O error occurs.
NoSuchAlgorithmException - the data integrity algorithm used cannot be found.
CertificateException - if any certificates could not be stored in the output stream.

KeyStore.java --- Key Store Class Copyright (C) 1999, 2002, 2003, 2004 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.