EntrustKeyStoreSpi ("Entrust Authority Security Toolkit for the Java Platform")

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

All Methods Instance Methods Concrete 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)
    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

Class EntrustKeyStoreSpi

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.security.KeyStoreSpi

Methods inherited from class java.lang.Object

Field Detail

DEBUG

CLOSE_KEY_STORE

Constructor Detail

EntrustKeyStoreSpi

EntrustKeyStoreSpi

Method Detail

getUser

engineLoad

engineStore

engineGetCertificateAlias

engineIsCertificateEntry

engineIsKeyEntry

engineSize

engineContainsAlias

engineAliases

engineDeleteEntry

engineSetKeyEntry

engineSetKeyEntry

engineGetCertificate

engineGetKey

engineGetCertificateChain

engineSetCertificateEntry

engineSetKeyEntry

engineGetCreationDate

finalize