iaik.smime.ess.utils
Class EncryptedKeyStoreDatabase

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

All Implemented Interfaces:

CertificateDatabase, KeyDatabase

public class EncryptedKeyStoreDatabase
extends java.lang.Object
implements KeyDatabase

Simple, Java KeyStore based key and certificate data base that keeps the keys encrypted in the base KeyStore.

This class provides a very simple implementation of an ESS Util KeyDatabase. It allows to access (search for) certificates and keys 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. After initializing this EncryptedKeyStoreDatabase from a KeyStore, an application may search for a key or certificate entry based on the corresponding IssuerAndSerialNumber, SubjectKeyID or RecipientKeyIdentifier.
In contrast to the KeyStoreDatabase utility which (for fast key access and for usage with the MLA handler utility) reads all keys from the KeyStore and maintains them in memory an EncryptedKeyStoreDatabase keeps the keys in the KeyStore. Therefore the key protection password has to be specified when actually getting a key, e.g.:

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

Note that this KeyDatabase implementation also provides a password-less getKey() method allowing to use an EncryptedKeyDatabase with the MLA handler utility. Anytime method getKey() is called (by the MLA) a PWD dialog pops up to ask for the key protection password. An application may override method promptPassword() to implement an alternative way to ask for the password.

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.

Constructor Summary

EncryptedKeyStoreDatabase()
Creates a new and empty KeyStoreDatabase.

Method Summary

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.
java.security.Key	getKey(KeyIdentifier keyID, char[] password) 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.
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.
protected char[]	promptPassword() Prompts for a password.
void	reset() Resets key and certificate database.
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

Constructor Detail

EncryptedKeyStoreDatabase

public EncryptedKeyStoreDatabase()

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))

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,
                                char[] password)
                         throws KeyStoreDatabaseException

Gets the key belonging to the given key identifier.

Parameters:

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

password - the key protection password

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 or the key entry cannot be decrypted

getKey

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

Gets the key belonging to the given key identifier.

When using this method to get the key a PWD dialog pops up to ask for the key protection password.

An application may override method promptPassword() to implement an alternative way to ask for the password, or may use method getKey(KeyIdentifier keyID, char[] password) to immediately provide the password when getting a key.

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 or the key entry cannot be decrypted

promptPassword

protected char[] promptPassword()

Prompts for a password.

This method is called by method getKey() when getting a key from the base KeyStore. This method uses a PWD dialog to ask for the password. An application may override this method to implement an alternative way to ask for the password, or may use method getKey(KeyIdentifier keyID, char[] password) to immediately provide the password when getting a key.

Returns:

the password

getSize

public int getSize()
            throws java.security.KeyStoreException

Gets the size of this KeyStoreDatabase.

Returns:

the number of entries included in this KeyStoreDatabase

Throws:

java.security.KeyStoreException - when the size of the KeyStore cannot be determined

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

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