com.entrust.toolkit.credentials

Class EntrustKeyStoreSpi

java.lang.Object

java.security.KeyStoreSpi

com.entrust.toolkit.credentials.EntrustKeyStoreSpi

public class EntrustKeyStoreSpi
extends java.security.KeyStoreSpi

The EntrustKeyStoreSpi class provides a common interface for the user to work with a variety of credentials.

Create a key store as follows:

     KeyStore.getInstance("Entrust");
     Load(InputStream input, char[] password);
 

The InputStream argument must be set to one of the following:

• A KeyStore ini file
• An epf file
• A pkcs12 file

Example:

     // Create a key store ini file using the KSIniFileCreator class

     KeyStore entrustKeyStore = KeyStore.getInstance("Entrust");
     char[] pwd = ...;
     FileInputStream input = new FileInputStream("C:\\ksIniFile.kst");
     entrust.load(input, pwd);

     // Retrieve keys and certificates from the key store
     Certificate verificationCert = entrustKeyStore.getCertificate("signing");
     Certificate encryptionCert   = entrustKeyStore.getCertificate("encryption");
     Certificate caCert           = entrustKeyStore.getCertificate("CA");

     PrivateKey signingKey        = entrustKeyStore.getKey("signing", null);
     PrivateKey decryptionKey     = entrustKeyStore.getKey("encryption", null);
 

When an Entrust key store is loaded from an Entrust key store INI file, a User object is automatically created and logged in. In the case were the user's credentials reside on a Cryptoki device, a PKCS11 connection is also created and opened. Once the key store is no longer needed, the user SHOULD be logged off and the PKCS11 connection SHOULD be closed (if one was opened) - this is called the close routine. Unfortunately the KeyStore API does not provide any methods to invoke a close routine.

The close routine can be invoked though a special usage of the engineStore(OutputStream, char[]) method. When the key store was loaded from an Entrust key store INI file, and the store method is called with "close" as the password, the close routine is invoked.

 entrustKeyStore.store(null, EntrustKeyStoreSpi.CLOSE_KEY_STORE);
 

Once this is done, the key store SHOULD no longer be used. In case a designer forgets to call the close routine manually, it will also be invoked in the finalizer when a PKCS11 connection is used, but this is not guaranteed to ever be run.

For compatibility with keystores created using Release 5.1 of the Toolkit, it is still possible to retrieve keys and certificates using the "RSA" alias. The aliases "signing" and "encryption" can also be used. If a key store is instantiated using the getInstance() method, only the aliases "signing" and "encryption" are supported — the alias "RSA" cannot be used in this case.

Field Summary

Fields

Modifier and Type	Field and Description
static char[]	CLOSE_KEY_STORE A special indicator designed to be used as the password parameter in the engineStore(OutputStream, char[]) method to indicate that the key store should be closed.
static boolean	DEBUG

Constructor Summary

Constructors

Modifier	Constructor and Description
	EntrustKeyStoreSpi() Creates an empty key store — initialized by the load method.
protected	EntrustKeyStoreSpi(User user, boolean clientMode) This constructor is used only by the EntrustKeyStore class.

Method Summary

Methods

Modifier and Type	Method and Description
java.util.Enumeration	engineAliases() Returns all aliases that have matching keys or certificates.
boolean	engineContainsAlias(java.lang.String name) Determines whether the given alias maps to a key or to a certificate.
void	engineDeleteEntry(java.lang.String name) Deletes only those certificates from the read/write certificate store (if they are available).
java.security.cert.Certificate	engineGetCertificate(java.lang.String name) Returns the certificate corresponding to the specified alias.
java.lang.String	engineGetCertificateAlias(java.security.cert.Certificate cert) Returns the certificate alias corresponding to the given certificate.
java.security.cert.Certificate[]	engineGetCertificateChain(java.lang.String name) Returns the certificate chain corresponding to the specified alias.
java.util.Date	engineGetCreationDate(java.lang.String name) The key store does not contain the information regarding the creation date of each entry, the following is returned for each case.
java.security.Key	engineGetKey(java.lang.String name, char[] password) Returns the key corresponding to the specified alias.
boolean	engineIsCertificateEntry(java.lang.String name) Determines whether the given alias maps to a certificate.
boolean	engineIsKeyEntry(java.lang.String name) Determines whether the given alias maps to a key.
void	engineLoad(java.io.InputStream input, char[] password) Reads an Entrust Profile from the specified input stream.
void	engineSetCertificateEntry(java.lang.String name, java.security.cert.Certificate c) Adds certificates to the Entrust key store.
void	engineSetKeyEntry(java.lang.String name, byte[] key, java.security.cert.Certificate[] certChain) Adding keys to the Entrust key store is not permitted.
void	engineSetKeyEntry(java.lang.String name, java.security.Key key, java.security.cert.Certificate[] certChain) Adding keys to the Entrust key store is not permitted.
void	engineSetKeyEntry(java.lang.String name, java.security.Key key, char[] pass, java.security.cert.Certificate[] c) Adding keys to the Entrust key store is not permitted.
int	engineSize() Returns the number of entries in a key store.
void	engineStore(java.io.OutputStream output, char[] password) Write the read-write certificate store to the given output stream.
protected void	finalize() When using a cryptoki device, make sure the device is closed otherwise exceptions are thrown.
User	getUser() Returns the User object wrapped by this key store.

Methods inherited from class java.security.KeyStoreSpi

engineEntryInstanceOf, engineGetEntry, engineLoad, engineSetEntry, engineStore

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG

public static final boolean DEBUG

See Also:

Constant Field Values

CLOSE_KEY_STORE

public static final char[] CLOSE_KEY_STORE

A special indicator designed to be used as the password parameter in the engineStore(OutputStream, char[]) method to indicate that the key store should be closed. It should be used with key stores that were loaded from an Entrust key store INI file to log-off the internally created user, and close an internally created PKCS11 connection. Following this call, the key store should no longer be used.

Constructor Detail

EntrustKeyStoreSpi

public EntrustKeyStoreSpi()

Creates an empty key store — initialized by the load method.

EntrustKeyStoreSpi

protected EntrustKeyStoreSpi(User user,
                  boolean clientMode)

This constructor is used only by the EntrustKeyStore class.

The constructor allows a key store to be initialized with a User object, so that the user has to log in only once for both the key source and the verification source.

Parameters:

user - a logged-in User object

clientMode - false if this class is intended to be used with an SSL server — true if intended to be used with a client. This argument determines whether the signing or encryption key pair is used (encryption for server, signing for client).

Method Detail

getUser

public User getUser()

Returns the User object wrapped by this key store.

Returns:

A logged in User object.

engineLoad

public void engineLoad(java.io.InputStream input,
              char[] password)
                throws java.security.cert.CertificateException,
                       java.io.IOException

Reads an Entrust Profile from the specified input stream.

Specified by:

engineLoad in class java.security.KeyStoreSpi

Parameters:

input - the stream from which to read the profile

password - the password protecting the profile. It will be wiped.

Throws:

java.security.cert.CertificateException

java.io.IOException

engineStore

public void engineStore(java.io.OutputStream output,
               char[] password)
                 throws java.io.IOException,
                        java.security.cert.CertificateException

Write the read-write certificate store to the given output stream. (Does nothing if the read-write certificate store does not exist).

If the key store is loaded through a key store ini file, the output and password arguments are ignored, and only the read/write credential store is written to the files specified in the key store ini file.

If the key store is loaded from an epf file or from a p12 file, the read-write certificate store is written to the given output stream.

Specified by:

engineStore in class java.security.KeyStoreSpi

Parameters:

output - ignored if the key store has been loaded from a key store ini file. In this case, only the changed read/write certificate store is written to the files specified by the ini file. If the key store has been loaded from memory, only the read-write certificate stores are written to the given output stream in p12 format.

password - Ignored if the key store has been loaded from a key store ini file. In this case, the password specified in the ini file is used. If the key store has been loaded from memory, the given password is used to protect the certificate stores.

Throws:

java.io.IOException - thrown if the key store has been loaded from memory, and the given output stream is null

java.security.cert.CertificateException - thrown if there is an error in writing the key store information

engineGetCertificateAlias

public java.lang.String engineGetCertificateAlias(java.security.cert.Certificate cert)

Returns the certificate alias corresponding to the given certificate.

The aliases are searched in the following order:

1. Check for encryption, verification and CA certificate of the logged in user and return the appropriate alias, — "verificationCertificate", "encryptionCertificate" or "CA"
2. Search the read/write certificate store (if available) for the given certificate
3. Search the read-only certificate store (if available) for the given certificate

If the certificate is not found, the method returns null.

Note

The implementation in Release 5.1 of the Toolkit always returned "RSA" if the certificate was found.

Specified by:

engineGetCertificateAlias in class java.security.KeyStoreSpi

Parameters:

cert - the cert for which the alias is to be returned

Returns:

the alias of the given certificate, or null if the certificate cannot be found

engineIsCertificateEntry

public boolean engineIsCertificateEntry(java.lang.String name)

Determines whether the given alias maps to a certificate.

Searches the certificate in the following order:

1. Returns true if name is "verificationCertificate", "encryptionCertificate", "CA", "ROOTCA" or "SUBCA{1..N}" and the appropriate certificate is available
2. To maintain the compatibility with the applications built using release 6.0 and 6.1 of the Toolkit, return true if name is "signing" or "encryption".
3. Returns true if name is "RSA" and the appropriate certificate is available. "RSA" is checked only if the key store was created with the EntrustKeyStore constructor. This is done to maintain compatibility with release 5.1.
4. Returns true if name found in read/write certificate store (if available)
5. Returns true if name found in read-only certificate store (if available)

Note

In Release 5.1 of the Toolkit, the only alias used was "RSA".

Specified by:

engineIsCertificateEntry in class java.security.KeyStoreSpi

Parameters:

name - the alias to check against matching certificates

Returns:

true if certificate is found, otherwise false

engineIsKeyEntry

public boolean engineIsKeyEntry(java.lang.String name)

Determines whether the given alias maps to a key.

Searches the key in the following order:

1. Returns true if name is "signingKey" or "decryptionKey" and the appropriate key is available
2. To maintain the compatibility with the applications built using release 6.0 and 6.1 of the Toolkit, return true if name is "signing" or "encryption".
3. Returns true if name is "RSA" and the appropriate key is available

"RSA" is checked only if the key store was created with the EntrustKeyStore constructor. This is done to maintain compatibility with applications created using release 5.1 of the Toolkit

Note

In Release 5.1 of the Toolkit, the only alias used was "RSA".

Specified by:

engineIsKeyEntry in class java.security.KeyStoreSpi

Parameters:

name - the alias to check against matching keys

Returns:

true if key is found, otherwise false

engineSize

public int engineSize()

Returns the number of entries in a key store.

The number is calculated as follows:

• Count signing/encryption private keys and certificates (maximum = 4)
• Count CA certificates if available
• Count entries in read/write certificate stores (if available)
• Count entries in read-only certificate stores (if available)

The certificates in the directory (if available) are disregarded.

Note

Applications built using Release 5.1 of the Toolkit always return 1.

Specified by:

engineSize in class java.security.KeyStoreSpi

Returns:

the number of certificates in this key store

engineContainsAlias

public boolean engineContainsAlias(java.lang.String name)

Determines whether the given alias maps to a key or to a certificate.

Refer to the documentation for the engineIsCertificateEntry and engineIsKeyEntry methods.

Note

In Release 5.1 of the Toolkit, return value is true only if name is "RSA".

Specified by:

engineContainsAlias in class java.security.KeyStoreSpi

Parameters:

name - the alias to check against matching keys or certificates

Returns:

true if entry exists, otherwise false

engineAliases

public java.util.Enumeration engineAliases()

Returns all aliases that have matching keys or certificates.

The Enumeration return value contains the following:

• The aliases "signingKey", "decryptionKey", "verificationCertificate", "encryptionCertificate", "CA", "ROOTCA" and possibly "SUBCA{1..N}" depending on how many CA's are in the hierarchy. Note: It is possible CA and ROOTCA will refer to the same certificate if the User is not in a hierarchy.
• The aliases of the read/write certificate stores (if available)
• The aliases of the read-only certificate stores (if available)

The aliases of the certificates in the directory (if available) are disregarded.

Note

In Release 5.1 of the Toolkit, the method returned a vector containing only the string "RSA".

Specified by:

engineAliases in class java.security.KeyStoreSpi

Returns:

an Enumeration containing the aliases

engineDeleteEntry

public void engineDeleteEntry(java.lang.String name)
                       throws java.security.KeyStoreException

Deletes only those certificates from the read/write certificate store (if they are available).

The method deletes entrys in all read/write certificate stores containing an appropriate entry.

Deleting keys from the Entrust key store is not permitted.

Note

In Release 5.1 of the Toolkit, the method always throws an exception because certificate stores do not exist in applications built with that release of the Toolkit.

Specified by:

engineDeleteEntry in class java.security.KeyStoreSpi

Throws:

KeyStoreException - thrown if entry does not exist or cannot be deleted

java.security.KeyStoreException

engineSetKeyEntry

public void engineSetKeyEntry(java.lang.String name,
                     byte[] key,
                     java.security.cert.Certificate[] certChain)
                       throws java.security.KeyStoreException

Adding keys to the Entrust key store is not permitted.

Specified by:

engineSetKeyEntry in class java.security.KeyStoreSpi

Throws:

KeyStoreException - thrown if this method is called

java.security.KeyStoreException

engineSetKeyEntry

public void engineSetKeyEntry(java.lang.String name,
                     java.security.Key key,
                     java.security.cert.Certificate[] certChain)
                       throws java.security.KeyStoreException

Adding keys to the Entrust key store is not permitted.

Throws:

KeyStoreException - thrown if this method is called

java.security.KeyStoreException

engineGetCertificate

public java.security.cert.Certificate engineGetCertificate(java.lang.String name)

Returns the certificate corresponding to the specified alias.

The certificate is searched in the following order:

1. Search for aliases — if name is "verificationCertificate", "encryptionCertificate","CA","ROOTCA" or "SUBCA{1.N}" the appropriate certificate is returned if available.

   Note

   To maintain the compatibility with the applications built using release 6.0 and 6.1 of the Toolkit, the appropriate certificate is returned if name is "signing" or "encryption".

   If the key store was instantiated with the EntrustKeyStore constructor and the name is "RSA", the appropriate certificate is returned if available. This is done to maintain compatibility with applications build using release 5.1 of the Toolkit.

2. Search the certificate in the read/write certificate store
3. Search the certificate in the read-only certificate store

If the certificate is not found, null is returned.

Note

In Release 5.1 of the Toolkit, the only alias used was "RSA".

Specified by:

engineGetCertificate in class java.security.KeyStoreSpi

Parameters:

name - the alias of the certificate being searched for

Returns:

the certificate if found, otherwise null

engineGetKey

public java.security.Key engineGetKey(java.lang.String name,
                             char[] password)

Returns the key corresponding to the specified alias.

The key is searched as follows:

If the name is "signingKey" or "decryptionKey", the appropriate key is returned if available.

Note

To maintain the compatibility with the applications built using release 6.0 and 6.1 of the Toolkit, the appropriate key is returned if name is "signing" or "encryption".

If the key store was instantiated with the EntrustKeyStore constructor and the name is "RSA", the appropriate key is returned if available. This is done to maintain compatibility with applications built using release 5.1 of the Toolkit.

Note

In release 5.1 of the Toolkit, the only alias used was "RSA".

Specified by:

engineGetKey in class java.security.KeyStoreSpi

Parameters:

name - the alias of the key being searched for

password - ignored

Returns:

signing key or decryption key if available, otherwise null

engineGetCertificateChain

public java.security.cert.Certificate[] engineGetCertificateChain(java.lang.String name)

Returns the certificate chain corresponding to the specified alias.

The certificate chain is searched as follows:

If the name is "CA", the CA certificate chain is returned. The first element of the array is the immediate CA certificate and the last element is the top level trusted root certificate.

If the name is "signingKey", "decryptionKey", "verificationCertificate" or "encryptionCertificate", the appropriate certificate chain is returned if available.

Note

To maintain the compatibility with the applications built using release 6.0 and 6.1 of the Toolkit, the appropriate certificate chain is returned if name is "signing" or "encryption".

If the key store was instantiated with the EntrustKeyStore constructor and the name is "RSA", the appropriate certificate chain is returned if available. This is done to maintain compatibility with applications built using release 5.1 of the Toolkit.

Note

In release 5.1 of the Toolkit, the only alias used was "RSA".

Specified by:

engineGetCertificateChain in class java.security.KeyStoreSpi

Parameters:

name - the alias to be searched for

Returns:

a chain containing the encryption/verification cert as the first entry followed by the CA cert chain.

engineSetCertificateEntry

public void engineSetCertificateEntry(java.lang.String name,
                             java.security.cert.Certificate c)
                               throws java.security.KeyStoreException

Adds certificates to the Entrust key store.

If the key store is loaded from a key store ini file, this method adds certicates to the key store only if a read/write certificate store is available. If an entry already exists in the read/write certificate store with the given alias, the entry is overwritten.

If the key store is loaded from a source other than a key store ini file, and no read/write certificate store exists, a new read/write store will be created.

Specified by:

engineSetCertificateEntry in class java.security.KeyStoreSpi

Parameters:

name - the alias name

c - the certificate

Throws:

KeyStoreException - thrown if the key store is loaded from an ini file and no read/write certificate store is available

java.security.KeyStoreException

engineSetKeyEntry

public void engineSetKeyEntry(java.lang.String name,
                     java.security.Key key,
                     char[] pass,
                     java.security.cert.Certificate[] c)
                       throws java.security.KeyStoreException

Adding keys to the Entrust key store is not permitted.

Specified by:

engineSetKeyEntry in class java.security.KeyStoreSpi

Throws:

KeyStoreException - thrown if this method is called

java.security.KeyStoreException

engineGetCreationDate

public java.util.Date engineGetCreationDate(java.lang.String name)

The key store does not contain the information regarding the creation date of each entry, the following is returned for each case. This method returns the notBefore date if the entry of the given name is a X509 certificate; the current date if the entry is of some other type of certificate or is a key; null if no entry is found with the given name.

Specified by:

engineGetCreationDate in class java.security.KeyStoreSpi

Returns:

a Date if the entry is found; null if no entry is found.

finalize

protected void finalize()
                 throws java.lang.Throwable

When using a cryptoki device, make sure the device is closed otherwise exceptions are thrown. For other credential readers do not close to help in the case where a customer has incorrectly used multiple keystore objects link to the same set of credentials (Entrust Profile).

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable