iaik.smime.ess.utils
Class KeyStoreDatabase

java.lang.Object
  iaik.smime.ess.utils.KeyStoreDatabase

All Implemented Interfaces:

CertificateDatabase, KeyDatabase

public class KeyStoreDatabase
extends java.lang.Object
implements KeyDatabase

Simple, Java KeyStore based key and certificate data base.

This class provides a very simple implementation of an ESS Util KeyDatabase. It reads certificates and keys from a Java KeyStore and allows to search for its entries based on their CertificateIdentifier (IssuerAndSerialNumber, SubjectKeyID or RecipientKeyIdentifier). Since keys/certificates are accessed by using their CeritifcateIdentifier, any key entry of the KeyStore must be accompanied by a certificate (chain); only private key entries are supported. Furthermore the KeyStore main password must be used for any key entry (i.e. any key entry must be protected by the same password). After initializing this KeyStoreDatabase from a KeyStore, an application may search for a key or certificate entry based on the corresponding IssuerAndSerialNumber, SubjectKeyID or RecipientKeyIdentifier e.g.:

 // initialize the KeyStoreDatabase from a KeyStore read from a file
 FileInputStream fis = ...;
 char[] password = ...;
 String keyStoreType = "IAIKKeyStore";
 String provider = "IAIK";
 KeyStoreDatabase ksdb = new KeyStoreDatabase();
 ksdb.init(fis, password, keyStoreType, provider);
 // search for a key entry and the corresponding certificate chain:
 IssuerAndSerialNumber iasn = ...;
 PrivateKey privateKey = ksdb.getKey(iasn);
 X509Certificate[] certChain = ksdb.getCertificateChain(iasn);
 ...
 // search for a sole certificate entry
 IssuerAndSerialNumber iasn1 = ...;
 X509Certificate cert = ksdb.getCertificate(iasn);
 

This KeyStore database internally only uses X509Certificate implementations of the IAIK provider; however, the KeyStore database may be initialized with a KeyStore of any provider, or may be stored to a KeyStore of any provider.

Note that for fast key access and for usage with the MLA handler utility this class reads all keys from the KeyStore during initialization and maintains them in memory. If you want to keep the keys in the KeyStore and do not want to access/decrypt them before actually using them you may use an EncryptedKeyStoreDatabase and specify the password when actually getting a key. However, when using a KeyDatabase with the MLA handler utility the MLA calls the password-less getKey() method which pops up a PWD dialog to ask for the key protection password if the KeyDatabase is an EncryptedKeyStoreDatabase.

Field Summary

protected java.util.Hashtable	certBase_ Repository holding certificate entries read from a KeyStore.
protected java.util.Hashtable	keyBase_ Repository holding private key and corresponding certificate entries read from a KeyStore.
protected TrustVerifier	trustVerifier_ Internal TrustVerifier.

Constructor Summary

KeyStoreDatabase()
Creates a new and empty KeyStoreDatabase.

Method Summary

void	addCertificate(java.security.cert.Certificate certificate, java.lang.String alias) Adds a certificate.
void	addKey(java.io.InputStream pkcs12Stream, char[] password, java.lang.String alias) Adds a key entry from an input stream from which a PKCS#12 object is read.
void	addKey(java.security.Key key, java.security.cert.Certificate[] certChain, java.lang.String alias) Adds a (private) key and the corresponding certificate chain.
void	addKey(PKCS12 pkcs12, char[] password, java.lang.String alias) Adds a key entry from the given PKCS#12 object.
X509Certificate[]	getAllCertificates() Gets all certificate entries.
KeyAndCertificate[]	getAllKeys() Gets all key entries and corresponding certificates.
X509Certificate	getCertificate(CertificateIdentifier certID) Gets the certificate belonging to the given certificate identifier.
X509Certificate[]	getCertificateChain(CertificateIdentifier certID) Gets the certificate chain belonging to the given certificate identifier.
java.security.Key	getKey(KeyIdentifier keyID) Gets the key belonging to the given key identifier.
int	getNumberOfCertificateEntries() Gets the number of (sole) certificate entries of this KeyStoreDatabase.
int	getNumberOfKeyEntries() Gets the number of key entries of this KeyStoreDatabase.
int	getSize() Gets the size of this KeyStoreDatabase.
TrustVerifier	getTrustVerifier() Gets the TrustVerifier, if set for this KeyStoreDatabase.
void	init(java.io.InputStream is, char[] password, java.lang.String keyStoreType, java.lang.String provider) Initializes this KeyStoreDatabase from an input stream supplying an encoded KeyStore.
void	init(java.security.KeyStore keyStore, char[] password) Initializes this KeyStoreDatabase from the given KeyStore.
void	reset() Resets key and certificate database.
void	setTrustVerifier(TrustVerifier trustVerifier) Sets an TrustVerifier for this KeyStoreDatabase.
void	store(java.io.OutputStream os, char[] password, java.lang.String keyStoreType, java.lang.String keyStoreProvider) Writes the contents of this KeyStore database to the given output stream using a KeyStore of requested format and provider.
java.lang.String	toString() Gets a String representation of this KeyStoreDatabase.
java.lang.String	toString(boolean detailed) Gets a String representation of this KeyStoreDatabase.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

keyBase_

protected java.util.Hashtable keyBase_

Repository holding private key and corresponding certificate entries read from a KeyStore.

certBase_

protected java.util.Hashtable certBase_

Repository holding certificate entries read from a KeyStore.

trustVerifier_

protected TrustVerifier trustVerifier_

Internal TrustVerifier. If set it will be consulted when searching for a particular key, certificate or certificate chain to only return entries that are trusted by the trust verifier.

Constructor Detail

KeyStoreDatabase

public KeyStoreDatabase()

Creates a new and empty KeyStoreDatabase.

Method Detail

init

public void init(java.io.InputStream is,
                 char[] password,
                 java.lang.String keyStoreType,
                 java.lang.String provider)
          throws java.io.IOException,
                 KeyStoreDatabaseException

Initializes this KeyStoreDatabase from an input stream supplying an encoded KeyStore.

Parameters:

is - the input stream from where to read the KeyStore

password - the password protecting the KeyStore and any included key entry

keyStoreType - the KeyStore type (e.g. "IAIKKeyStore")

provider - the JCA provider supporting a KeyStore implementation of the requested type; maybe null for search the installed providers

Throws:

java.io.IOException - if an error occurs when reading from the stream

KeyStoreDatabaseException - if an error occurs when loading the KeyStore (e.g. a KeyStore of requested type is not available,...) and initializing this KeyStore database from the KeyStore (e.g. a key entry is not a private key or is not accompanied by a certificate (chain))

init

public void init(java.security.KeyStore keyStore,
                 char[] password)
          throws KeyStoreDatabaseException

Initializes this KeyStoreDatabase from the given KeyStore. The KeyStore already has to be loaded.

Parameters:

keyStore - the (already loaded) KeyStore

password - the password protecting any included key entry

Throws:

KeyStoreDatabaseException - if an error occurs when and initializing this KeyStore database from the KeyStore (e.g. a key entry is not a private key or is not accompanied by a certificate (chain))

addKey

public void addKey(java.security.Key key,
                   java.security.cert.Certificate[] certChain,
                   java.lang.String alias)
            throws KeyStoreDatabaseException

Adds a (private) key and the corresponding certificate chain.

Parameters:

key - the (private) key to be added

certChain - the certificate chain that belongs to the private key

alias - the (KeyStore) alias of the entry

Throws:

KeyStoreDatabaseException - if a problem occurs when adding the key entry (e.g. the given key is not private key or no certificate chain is supplied)

addKey

public void addKey(java.io.InputStream pkcs12Stream,
                   char[] password,
                   java.lang.String alias)
            throws java.io.IOException,
                   KeyStoreDatabaseException

Adds a key entry from an input stream from which a PKCS#12 object is read.

Parameters:

pkcs12Stream - the input stream from which to read the PKCS#12 object

password - the password to decrypt the PKCS#12 object

alias - the alias for adding the key to the database (if null, the friendlyName attribute of the PKCS#12 keyBag is used as alias; if set)

Throws:

java.io.IOException - if an error occurs when reading from the stream

KeyStoreDatabaseException - if a problem occurs when adding the key entry (e.g. the PKCS#12 object cannot be decrypted)

addKey

public void addKey(PKCS12 pkcs12,
                   char[] password,
                   java.lang.String alias)
            throws KeyStoreDatabaseException

Adds a key entry from the given PKCS#12 object.

Parameters:

pkcs12 - the key supplying PKCS#12 object

password - the password to decrypt the PKCS#12 object

alias - the alias for adding the key to the database (if null, the friendlyName attribute of the PKCS#12 keyBag is used as alias; if set)

Throws:

KeyStoreDatabaseException - if a problem occurs when adding the key entry (e.g. the PKCS#12 object cannot be decrypted)

addCertificate

public void addCertificate(java.security.cert.Certificate certificate,
                           java.lang.String alias)
                    throws KeyStoreDatabaseException

Adds a certificate.

Parameters:

certificate - the certificate to be added

alias - the (KeyStore) alias of the entry

Throws:

KeyStoreDatabaseException - if a problem occurs when adding the certificate (e.g. when converting the certificate to an IAIK X509Certificate)

reset

public void reset()

Resets key and certificate database. All entries are cleared.

getCertificateChain

public X509Certificate[] getCertificateChain(CertificateIdentifier certID)
                                      throws KeyStoreDatabaseException

Gets the certificate chain belonging to the given certificate identifier. This methods searches for a corresponding certificate chain. This means that not only sole certificate entries are searched but also certificates that have been imported when adding a key entry.

Specified by:

getCertificateChain in interface CertificateDatabase

Parameters:

certID - the certificate identifier identifying the entity to which the requested certificate key belongs to

Returns:

the certificate chain belonging to the entity identified by the given certificate identifier (the entity certificate has to be located at index 0 of the returned array); or null if no certificates for the given identifier are found

Throws:

KeyStoreDatabaseException - if the given certID is not an IssuerAndSerialNumber, SubjectKeyID or RecipientKeyIdentifier

getCertificate

public X509Certificate getCertificate(CertificateIdentifier certID)
                               throws KeyStoreDatabaseException

Gets the certificate belonging to the given certificate identifier. This methods searches the whole underlying KeyStore for a corresponding certificate. This means that not only sole certificate entries are searched but also certificates that have been imported to the base KeyStore when adding a key entry to it.

Specified by:

getCertificate in interface CertificateDatabase

Parameters:

certID - the certificate identifier identifying the entity to which the requested certificate key belongs to

Returns:

the certificate belonging to the entity identified by the given certificate identifier; or null if no certificate for the given identifier are found

Throws:

KeyStoreDatabaseException - if the given certID is not an IssuerAndSerialNumber, SubjectKeyID or RecipientKeyIdentifier

getKey

public java.security.Key getKey(KeyIdentifier keyID)
                         throws KeyStoreDatabaseException

Gets the key belonging to the given key identifier.

Specified by:

getKey in interface KeyDatabase

Parameters:

keyID - the key identifier identifying the entity to which the requested key belongs to

Returns:

the key belonging to the given key identifier or null if there is no key for this identifier

Throws:

KeyStoreDatabaseException - if the given certID is not an IssuerAndSerialNumber, SubjectKeyID or RecipientKeyIdentifier

getAllKeys

public KeyAndCertificate[] getAllKeys()

Gets all key entries and corresponding certificates.

Returns:

an array of KeyAndCertificate objects; each of them holding a private key and its corresponding certificate (chain)

getAllCertificates

public X509Certificate[] getAllCertificates()

Gets all certificate entries. Only certificate entries are searched, no key entries.

Returns:

an array of certificates that are included in this KeyStoreDatabase

getSize

public int getSize()

Gets the size of this KeyStoreDatabase.

Returns:

the number of entries included in this KeyStoreDatabase

getNumberOfKeyEntries

public int getNumberOfKeyEntries()

Gets the number of key entries of this KeyStoreDatabase.

Returns:

the number of key entries included in this KeyStoreDatabase

getNumberOfCertificateEntries

public int getNumberOfCertificateEntries()

Gets the number of (sole) certificate entries of this KeyStoreDatabase. This method does not count certificates that have been imported to the KeyStore when adding a key entry to it.

Returns:

the number of (sole) certificate entries included in this KeyStoreDatabase

setTrustVerifier

public void setTrustVerifier(TrustVerifier trustVerifier)

Sets an TrustVerifier for this KeyStoreDatabase. If a TrustVerifier is set by this method it will be consulted anytime when searching for a particular key, certificate or certificate chain to only return entries that are trusted by the trust verifier.

Parameters:

trustVerifier - the TrustVerifier if to be used by this KeyStoreDatabase

getTrustVerifier

public TrustVerifier getTrustVerifier()

Gets the TrustVerifier, if set for this KeyStoreDatabase. If a TrustVerifier has been set it will be consulted anytime when searching for a particular key, certificate or certificate chain to only return entries that are trusted by the trust verifier.

Returns:

the TrustVerifier to be used by this KeyStoreDatabase, or null if no TrustVerifier has been set

store

public void store(java.io.OutputStream os,
                  char[] password,
                  java.lang.String keyStoreType,
                  java.lang.String keyStoreProvider)
           throws KeyStoreDatabaseException,
                  java.security.NoSuchProviderException,
                  java.security.NoSuchAlgorithmException,
                  java.io.IOException

Writes the contents of this KeyStore database to the given output stream using a KeyStore of requested format and provider.

Throws:

KeyStoreDatabaseException

java.security.NoSuchProviderException

java.security.NoSuchAlgorithmException

java.io.IOException

toString

public java.lang.String toString()

Gets a String representation of this KeyStoreDatabase.

Overrides:

toString in class java.lang.Object

Returns:

a String representation of this KeyStoreDatabase

toString

public java.lang.String toString(boolean detailed)

Gets a String representation of this KeyStoreDatabase.

Parameters:

detailed - whether to give some more detailed information

Returns:

a String representation of this KeyStoreDatabase