iaik.smime.ess.utils
Class KeyStoreDatabase

java.lang.Object
  extended by 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

This Javadoc may contain text parts from text parts from IETF Internet Standard specifications (see copyright note).

IAIK-CMS 6.0, (c) 2002 IAIK, (c) 2003, 2023 SIC