TokenKeyStoreSpi (IAIK PKCS#11 Provider API Documentation)

java.lang.Object
- java.security.KeyStoreSpi
- - iaik.pkcs.pkcs11.provider.TokenKeyStoreSpi

All Implemented Interfaces:

PKCS11EngineClass

Direct Known Subclasses:

TokenKeyStoreFastSpi
```
public class TokenKeyStoreSpi
extends java.security.KeyStoreSpi
implements PKCS11EngineClass
```
A key store implementation that uses the IAIK PKCS#11 wrapper. This key store is bound to a slot which is managed by a token manager. This key store updates its contents automatically if a token is removed, inserted or changed. If there is currently no token in the slot, the keystore is empty. It is also possible to insert keys and certificates into the key store if the underlying token is writable. All newly set keys and certificates become token objects; this means, they are stored permanently rather than only for the current session. Newly inserted private and secret keys also get their sensitive and private flag set per default.
Certificate chains are ordered with user-certificate first where used by methods of this class.

Author:

Karl Scheibelhofer

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.HashSet`	`aliases_` The collection of all aliases of this key store.
`protected java.util.Hashtable`	`certificateChainAliasToPkcs11ObjectsTable_` Provides the PKCS#11 objects that correspond to a certificate chain alias.
`protected java.util.Hashtable`	`certificateChains_` Hash table that holds the certificate chains that belong to the user's keys.
`protected iaik.pkcs.pkcs11.TokenInfo`	`infoOfRecentToken_` Stores the information of the token where we read the table contents.
`protected boolean`	`isUpToDate_` Falg that indicates that the key tables are up to date or if they need to be updated.
`static java.lang.String`	`KEY_STORE_TYPE` The type name of this key store.
`protected java.util.Hashtable`	`keyAliasToPkcs11ObjectTable_` Provides the PKCS#11 objects that correspond to the key aliases.
`protected java.util.Hashtable`	`keys_` The hash table holding all type of keys.
`protected byte[]`	`lastNewID_` The last new PKCS#11 object (key or certificate) ID generated.
`protected iaik.pkcs.pkcs11.Session`	`readSession_` The session to use for finding object; i.e.
`protected java.lang.String`	`supportProviderName_` The support provider to use for Hashing keys and to instantiate key factories for generating key specs.
`protected TokenManager`	`tokenManager_` The token manager this key store is associated with.
`protected java.util.Hashtable`	`trustedCertificateAliasToPkcs11ObjectTable_` Provides the PKCS#11 objects that correspond to the trusted certificate aliases.
`protected java.util.Hashtable`	`trustedCertificates_` Hash table that holds the certificates that do not belong to any key.
`protected iaik.pkcs.pkcs11.MechanismInfo[]`	`usedMechanismInfos_` The mechanism information is the same for all digest mechanisms.
`protected iaik.pkcs.pkcs11.Mechanism[]`	`usedMechanisms_` The list of used mechanisms.
`protected char[]`	`userPIN_` Contains the user PIN if it has been provided at the call to load.
`protected boolean`	`useUserSession_` Indicate that private (private flag!) keys are only read on demand.
`protected iaik.pkcs.pkcs11.Session`	`writeSession_` The session to use for writing objects; i.e.

Constructor Summary

Constructors
Constructor and Description
`TokenKeyStoreSpi()` Construct a new uninitialized keystore.
`TokenKeyStoreSpi(TokenManager tokenManager)` Construct a new keystore from the given PKCS#11 token.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`clearTables()` Clear all tables.
`protected boolean`	`contains(java.util.List arrays, byte[] other)`
`protected iaik.pkcs.pkcs11.objects.Object`	`createCertificate(java.security.cert.Certificate certificate, byte[] id, char[] label)` Create a certificate object on the token as token object and assign the given ID to it, if the certificate type supports the ID attribute.
`protected iaik.x509.X509Certificate[]`	`createCertificateChain(iaik.x509.X509Certificate userCertificate, java.util.Map subjectToCertificatesMap, char[] label, iaik.pkcs.pkcs11.provider.IdentityMap trustedCertificates)` Create a certificate chain that starts with the given user certificate.
`protected iaik.pkcs.pkcs11.objects.Key`	`createKeyCreationTemplate(iaik.pkcs.pkcs11.objects.Key baseKey)` Create a template based on the given key.
`protected java.security.spec.KeySpec`	`createKeySpec(java.security.Key key, java.lang.Class keySpecClass)` Create a key spec out of the given key.
`protected java.security.spec.KeySpec`	`createPrivateKeySpec(java.security.Key key)` Create a key spec out of the given key.
`protected java.security.spec.KeySpec`	`createPublicKeySpec(java.security.Key key)` Create a key spec out of the given key.
`protected java.security.spec.KeySpec`	`createSecretKeySpec(javax.crypto.SecretKey key)` Create a key spec out of the given key.
`protected java.lang.String`	`createUniqueAlias(iaik.pkcs.pkcs11.objects.Object pkcs11Object, java.util.Set usedAliases)` This method creates a alias for the given pkcs#11 object that does not already exist in this key store.
`protected void`	`deleteCertificate(java.lang.String alias)` Delete the certificate with the given alias.
`protected void`	`deleteChertificateChain(java.lang.String alias)` Delete the certificate chain with the given alias.
`protected void`	`deleteKey(java.lang.String alias)` Delete the key with the given alias.
`java.util.Enumeration`	`engineAliases()` Get all known aliases.
`boolean`	`engineContainsAlias(java.lang.String alias)` Checks, if this key store contains an entry with the given alias.
`void`	`engineDeleteEntry(java.lang.String alias)` Delete the entry with the given alias.
`java.security.cert.Certificate`	`engineGetCertificate(java.lang.String alias)` Get the certificate for the given alias.
`java.lang.String`	`engineGetCertificateAlias(java.security.cert.Certificate certificate)` Get the alias of the given certificate.
`java.security.cert.Certificate[]`	`engineGetCertificateChain(java.lang.String alias)` Get the certificate chain for the entry with the given alias.
`java.util.Date`	`engineGetCreationDate(java.lang.String alias)` Get the creation date of the entry with the given alias name.
`java.security.Key`	`engineGetKey(java.lang.String alias, char[] password)` Get the key that has the alias given as argument.
`boolean`	`engineIsCertificateEntry(java.lang.String alias)` Checks, if the alias refers to a trusted certificate entry.
`boolean`	`engineIsKeyEntry(java.lang.String alias)` Checks, if the alias refers to a key entry.
`void`	`engineLoad(java.io.InputStream in, char[] password)` Loads and initializes this key store.
`void`	`engineSetCertificateEntry(java.lang.String alias, java.security.cert.Certificate certificate)` Implements the corresponding method of the KeyStoreSpi class according to its specification.
`void`	`engineSetKeyEntry(java.lang.String alias, byte[] key, java.security.cert.Certificate[] certificateChain)` UNSUPPORTED.
`void`	`engineSetKeyEntry(java.lang.String alias, java.security.Key key, char[] password, java.security.cert.Certificate[] certificateChain)` Implements the corresponding method of the KeyStoreSpi class according to its specification.
`int`	`engineSize()` Returns the number of entries in this key store, keys and certificate entries.
`void`	`engineStore(java.io.OutputStream out, char[] password)` A call to this method, just sets the user PIN to a new value.
`protected void`	`ensureCurrentTables()` This method calls method update().
`protected void`	`ensureReadSession()` This method ensures that an appropriate session is open.
`protected void`	`ensureSupportProvider()` Ensure that the keystore support provider name is available in the `supportProviderName_` field.
`protected void`	`ensureWriteSession()` This method ensures that an appropriate session is open.
`protected void`	`finalize()` Try to close the session that this object opened.
`protected iaik.pkcs.pkcs11.objects.Key`	`findCoreespondingKey(iaik.pkcs.pkcs11.objects.Key key)` Find a key that corresponds to the given key; e.g.
`protected void`	`findKeysAndCertificateTables()` Find all keys and certificates on the token put them in the right tables.
`protected byte[]`	`generateNewID(byte[] suggestedID)` Generates a new ID that is not used by any existing object on the keystore token yet.
`protected iaik.pkcs.pkcs11.MechanismInfo`	`getMechanismFeaturesSupport(java.lang.String algorithmName)` Check, what features of the given algorithm the token supports.
`protected boolean`	`getReadProtectedKeyOnDemand()` This property causes this object to search for objects using only a not explicitly logged-in session.
`TokenManager`	`getTokenManager()` Get the token manager of the token that holds the contents of this key store.
`protected void`	`initialize()` Do the internal initialization.
`protected boolean`	`isEndUserCertificate(iaik.x509.X509Certificate certificate)` Check if the given certificate is a end-user certificate.
`boolean`	`isSupportedBy(TokenManager tokenManager)` Check, if the current token of the given token manager supports the required features for this engine class.
`protected boolean`	`isUpToDate()` Check, if the tables are up to date.
`protected boolean`	`loginSession()` Logs in the current session, if a login is required.
`protected void`	`logoutSession()` This method logs out the session of this key store.
`protected void`	`openReadSession()` Opens a session with the necessary rights for searching keys and certificates.
`protected void`	`openWriteSession()` Opens a session with the necessary rights for searching keys and certificates.
`protected java.lang.String`	`readProviderName(java.io.InputStream in)` Read the complete content of the stream and return the content as string.
`protected void`	`releaseSessions()` A call to this method signals that the sessions are no longer used.
`protected void`	`setKeyAttributes(iaik.pkcs.pkcs11.objects.PrivateKey keyTemplate, java.security.cert.X509Certificate certificate, iaik.pkcs.pkcs11.MechanismInfo supportedFeatures)` Inspect the certificate and the mechanisms supported by the token and set the attributes of the private key template accordingly.
`protected void`	`setKeyAttributes(iaik.pkcs.pkcs11.objects.PublicKey keyTemplate, java.security.cert.X509Certificate certificate, iaik.pkcs.pkcs11.MechanismInfo supportedFeatures)` Inspect the certificate and the mechanisms supported by the token and set the attributes of the public key template accordingly.
`protected void`	`setReadProtectedKeyOnDemand(boolean onDemand)` Setting this property causes this object to search for objects using only a not explicitly logged-in session.
`protected void`	`setUpToDate(boolean isUpToDate)` Set, if the tables are up to date.
`protected boolean`	`tokenChanged()` Check, if the token was changed.
`protected void`	`updateTables()` This method calls the appropriate methods to get all available keys and certificates and stores them in a hash table.
`protected void`	`writeProviderName(java.lang.String providerName, java.io.OutputStream out)` Write the provider name to the given output stream.

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
  - KEY_STORE_TYPE
```
public static final java.lang.String KEY_STORE_TYPE
```
    The type name of this key store.
    
    See Also:
    
    Constant Field Values
  - tokenManager_
```
protected TokenManager tokenManager_
```
    The token manager this key store is associated with.
  - readSession_
```
protected iaik.pkcs.pkcs11.Session readSession_
```
    The session to use for finding object; i.e. keys and certificates.
  - writeSession_
```
protected iaik.pkcs.pkcs11.Session writeSession_
```
    The session to use for writing objects; i.e. keys and certificates.
  - aliases_
```
protected java.util.HashSet aliases_
```
    The collection of all aliases of this key store.
  - keys_
```
protected java.util.Hashtable keys_
```
    The hash table holding all type of keys. Key is the alias.
  - certificateChains_
```
protected java.util.Hashtable certificateChains_
```
    Hash table that holds the certificate chains that belong to the user's keys. Key of this table is the alias of the key. If a certificate chain belongs to a key in the key table, they must use the same alias.
  - trustedCertificates_
```
protected java.util.Hashtable trustedCertificates_
```
    Hash table that holds the certificates that do not belong to any key. Key is the (KeyStore) alias of the certificate.
  - keyAliasToPkcs11ObjectTable_
```
protected java.util.Hashtable keyAliasToPkcs11ObjectTable_
```
    Provides the PKCS#11 objects that correspond to the key aliases.
  - certificateChainAliasToPkcs11ObjectsTable_
```
protected java.util.Hashtable certificateChainAliasToPkcs11ObjectsTable_
```
    Provides the PKCS#11 objects that correspond to a certificate chain alias.
  - trustedCertificateAliasToPkcs11ObjectTable_
```
protected java.util.Hashtable trustedCertificateAliasToPkcs11ObjectTable_
```
    Provides the PKCS#11 objects that correspond to the trusted certificate aliases.
  - isUpToDate_
```
protected boolean isUpToDate_
```
    Falg that indicates that the key tables are up to date or if they need to be updated.
  - useUserSession_
```
protected boolean useUserSession_
```
    Indicate that private (private flag!) keys are only read on demand.
  - infoOfRecentToken_
```
protected iaik.pkcs.pkcs11.TokenInfo infoOfRecentToken_
```
    Stores the information of the token where we read the table contents. For update requirement check.
  - lastNewID_
```
protected byte[] lastNewID_
```
    The last new PKCS#11 object (key or certificate) ID generated.
  - supportProviderName_
```
protected java.lang.String supportProviderName_
```
    The support provider to use for Hashing keys and to instantiate key factories for generating key specs.
  - usedMechanisms_
```
protected iaik.pkcs.pkcs11.Mechanism[] usedMechanisms_
```
    The list of used mechanisms.
  - usedMechanismInfos_
```
protected iaik.pkcs.pkcs11.MechanismInfo[] usedMechanismInfos_
```
    The mechanism information is the same for all digest mechanisms.
  - userPIN_
```
protected char[] userPIN_
```
    Contains the user PIN if it has been provided at the call to load.
- Constructor Detail
  - TokenKeyStoreSpi
```
public TokenKeyStoreSpi()
```
    Construct a new uninitialized keystore. The application must call load(InputStream, char[]).
  - TokenKeyStoreSpi
```
public TokenKeyStoreSpi(TokenManager tokenManager)
```
    Construct a new keystore from the given PKCS#11 token.
    
    Parameters:
    
    tokenManager - The token manager for logging in the user and getting configuration data.
    
    Preconditions:
    
    (tokenManager < > null)
- Method Detail
  - engineAliases
```
public java.util.Enumeration engineAliases()
```
    Get all known aliases.
    
    Specified by:
    
    engineAliases in class java.security.KeyStoreSpi
    
    Returns:
    
    An enumeration of all aliases.
    
    Postconditions:
    
    (result < > null)
  - engineContainsAlias
```
public boolean engineContainsAlias(java.lang.String alias)
```
    Checks, if this key store contains an entry with the given alias.
    
    Specified by:
    
    engineContainsAlias in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias to look for.
    
    Returns:
    
    True, if there is an entry with the given alias.
    
    See Also:
    
    KeyStoreSpi.engineContainsAlias(String)
  - engineDeleteEntry
```
public void engineDeleteEntry(java.lang.String alias)
                       throws java.security.KeyStoreException
```
    Delete the entry with the given alias. If the given entry is a key entry with a certificate chain, this method only deletes those certificate objects from the token which's PKCS#11 label is equal to the alias of the entry. This behavior should avoid unintentional deletion of certificate entries that were only used to create a chain when reading the key store but have not been set using this provider.
    
    Specified by:
    
    engineDeleteEntry in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias of the element to delete.
    
    Throws:
    
    java.security.KeyStoreException - If the entry cannot be deleted.
    
    See Also:
    
    KeyStoreSpi.engineDeleteEntry(String)
  - engineGetCertificate
```
public java.security.cert.Certificate engineGetCertificate(java.lang.String alias)
```
    Get the certificate for the given alias.
    
    Specified by:
    
    engineGetCertificate in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias of the entry.
    
    Returns:
    
    The certificate of the entry. The end-user certificate, if the alias is the alias of a private key entry. null, if there is no certificate or no such entry.
    
    See Also:
    
    KeyStoreSpi.engineGetCertificate(String)
  - engineGetCertificateAlias
```
public java.lang.String engineGetCertificateAlias(java.security.cert.Certificate certificate)
```
    Get the alias of the given certificate.
    
    Specified by:
    
    engineGetCertificateAlias in class java.security.KeyStoreSpi
    
    Parameters:
    
    certificate - The certificate to look up the alias for.
    
    Returns:
    
    The alias of the certificate or null, if there is no such certificate.
    
    See Also:
    
    KeyStoreSpi.engineGetCertificateAlias(java.security.cert.Certificate)
    
    Preconditions:
    
    certificate <> null
  - engineGetCertificateChain
```
public java.security.cert.Certificate[] engineGetCertificateChain(java.lang.String alias)
```
    Get the certificate chain for the entry with the given alias. Currently, this method returns only chains that contain the end-user certificate only.
    
    Specified by:
    
    engineGetCertificateChain in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias of the key entry to get the chain from.
    
    Returns:
    
    The certificate chain of the given entry or null if there is no such entry or the entry has no certificate chain.
    
    See Also:
    
    KeyStoreSpi.engineGetCertificateChain(String)
    
    Postconditions:
    
    (result < > null)
    
    Preconditions:
    
    (alias < > null)
  - engineGetCreationDate
```
public java.util.Date engineGetCreationDate(java.lang.String alias)
```
    Get the creation date of the entry with the given alias name. This method is currently not supported. Just returns null.
    
    Specified by:
    
    engineGetCreationDate in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias of the entry to get the creation date.
    
    Returns:
    
    The creation date.
    
    See Also:
    
    KeyStoreSpi.engineGetCreationDate(String)
    
    Postconditions:
    
    result == null
  - engineGetKey
```
public java.security.Key engineGetKey(java.lang.String alias,
                                      char[] password)
                               throws java.security.NoSuchAlgorithmException,
                                      java.security.UnrecoverableKeyException
```
    Get the key that has the alias given as argument. By now, this implementation does not use the given password.
    
    Specified by:
    
    engineGetKey in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias of the wanted key.
    
    password - The password used to protect the key.
    
    Returns:
    
    The key with the given alias or null, if there is no such key.
    
    Throws:
    
    java.security.NoSuchAlgorithmException - If the key cannot be constructed, because its algorithm is not known.
    
    java.security.UnrecoverableKeyException - If the key cannot be recovered.
    
    See Also:
    
    KeyStoreSpi.engineGetKey(String, char[])
  - engineIsCertificateEntry
```
public boolean engineIsCertificateEntry(java.lang.String alias)
```
    Checks, if the alias refers to a trusted certificate entry.
    
    Specified by:
    
    engineIsCertificateEntry in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias name to check.
    
    Returns:
    
    True, if the alias is a trusted certificate entry.
    
    See Also:
    
    KeyStoreSpi.engineIsCertificateEntry(String)
  - engineIsKeyEntry
```
public boolean engineIsKeyEntry(java.lang.String alias)
```
    Checks, if the alias refers to a key entry.
    
    Specified by:
    
    engineIsKeyEntry in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias name to check.
    
    Returns:
    
    True, if the alias is a key entry.
    
    See Also:
    
    KeyStoreSpi.engineIsKeyEntry(String)
  - engineLoad
```
public void engineLoad(java.io.InputStream in,
                       char[] password)
                throws java.io.IOException,
                       java.lang.UnsupportedOperationException
```
    Loads and initializes this key store. The user PIN may be provided as the password. If the application provides the PIN like this, the keystore will not prompt the password by other means. Please note that the keystore will keep a reference to the password object if it is provided.
    
    Specified by:
    
    engineLoad in class java.security.KeyStoreSpi
    
    Parameters:
    
    in - The stream to load from.
    
    password - The user PIN (or password) for the token.
    
    Throws:
    
    java.io.IOException - If the keystore cannot be loaded.
    
    java.lang.UnsupportedOperationException - If getting the provider instance fails.
    
    See Also:
    
    KeyStoreSpi.engineLoad(InputStream, char[])
  - engineSetCertificateEntry
```
public void engineSetCertificateEntry(java.lang.String alias,
                                      java.security.cert.Certificate certificate)
                               throws java.security.KeyStoreException
```
    Implements the corresponding method of the KeyStoreSpi class according to its specification. Stores the certificate on the underlying PKCS#11 token as token object not as session object; this means it remains on the token after token removal. It tries to set as many attributes in the PKCS#11 certificate object as possible. However, it does not use any attributes of version 2.10 or 2.11 of the PKCS#11 standard to ensure compatibility. This implementation supports X.509 public key certificates and X.509 attribute certificates of the class iaik.x509.attr.AttributeCertificate.
    
    Specified by:
    
    engineSetCertificateEntry in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias to use for the certificate.
    
    certificate - The certificate to load onto the token.
    
    Throws:
    
    java.security.KeyStoreException - If storing the certificate fails for some reason.
    
    See Also:
    
    KeyStoreSpi.engineSetCertificateEntry(String, java.security.cert.Certificate)
    
    Preconditions:
    
    (alias < > null) and (certificate <> null)
  - engineSetKeyEntry
```
public void engineSetKeyEntry(java.lang.String alias,
                              java.security.Key key,
                              char[] password,
                              java.security.cert.Certificate[] certificateChain)
                       throws java.security.KeyStoreException
```
    Implements the corresponding method of the KeyStoreSpi class according to its specification. Stores the key and the certificates on the underlying PKCS#11 token as token objects not as session objects; this means, they remains on the token after token removal. The user certificate gets the same ID as the provided key. The remaining certificates get a new ID and are added as trusted certificates. It tries to set as many attributes in the PKCS#11 key and certificate objects as possible. However, it does not use any attributes of version 2.10 or 2.11 of the PKCS#11 standard to ensure compatibility. This implementation supports RSA, DSA and DH keys and X.509 public key certificates.
    
    Specified by:
    
    engineSetKeyEntry in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - The alias for the new entry.
    
    key - The key of this new key entry.
    
    password - This parameter is ignored.
    
    certificateChain - The certificate chain associated .
    
    Throws:
    
    java.security.KeyStoreException - If creating the new key and certificate entry failed.
    
    See Also:
    
    KeyStoreSpi.engineSetKeyEntry(String, java.security.Key, char[], java.security.cert.Certificate[])
    
    Preconditions:
    
    (alias < > null) and (key <> null)
  - engineSetKeyEntry
```
public void engineSetKeyEntry(java.lang.String alias,
                              byte[] key,
                              java.security.cert.Certificate[] certificateChain)
                       throws java.security.KeyStoreException
```
    UNSUPPORTED. Just throws KeyStoreException.
    
    Specified by:
    
    engineSetKeyEntry in class java.security.KeyStoreSpi
    
    Parameters:
    
    alias - .
    
    key - .
    
    certificateChain - .
    
    Throws:
    
    java.security.KeyStoreException - Always throws this exception.
    
    See Also:
    
    KeyStoreSpi.engineSetKeyEntry(String, byte[], java.security.cert.Certificate[])
  - engineSize
```
public int engineSize()
```
    Returns the number of entries in this key store, keys and certificate entries. This equals the number of aliases in this key store.
    
    Specified by:
    
    engineSize in class java.security.KeyStoreSpi
    
    Returns:
    
    The number of entries in this key store.
    
    See Also:
    
    KeyStoreSpi.engineSize()
  - engineStore
```
public void engineStore(java.io.OutputStream out,
                        char[] password)
                 throws java.io.IOException,
                        java.security.NoSuchAlgorithmException,
                        java.security.cert.CertificateException
```
    A call to this method, just sets the user PIN to a new value. If an output stream is provided, the provider name is written to it; i.e. this output can be used for loading a key store of this type. If a password is given, the method tries to set this password as the new user PIN. If no password is provided, the method will try to use other means to set the new password.
    
    Specified by:
    
    engineStore in class java.security.KeyStoreSpi
    
    Parameters:
    
    out - If provided, the provider name is written to it.
    
    password - The new user PIN, or null to leave the user.
    
    Throws:
    
    java.io.IOException - If writing the key store fails.
    
    java.security.NoSuchAlgorithmException - If a required algorithm is unavailable.
    
    java.security.cert.CertificateException - If handling a certificate fails.
    
    See Also:
    
    KeyStoreSpi.engineStore(OutputStream, char[])
  - getTokenManager
```
public TokenManager getTokenManager()
```
    Get the token manager of the token that holds the contents of this key store.
    
    Returns:
    
    The token manager of this key store.
  - isSupportedBy
```
public boolean isSupportedBy(TokenManager tokenManager)
```
    Check, if the current token of the given token manager supports the required features for this engine class.
    
    Specified by:
    
    isSupportedBy in interface PKCS11EngineClass
    
    Parameters:
    
    tokenManager - The token manager. Used to get information about the current token.
    
    Returns:
    
    True, if this engine class can be used with the currently present token of the given token manager.
    
    Preconditions:
    
    (tokenManager < > null)
  - deleteKey
```
protected void deleteKey(java.lang.String alias)
                  throws iaik.pkcs.pkcs11.TokenException
```
    Delete the key with the given alias.
    
    Parameters:
    
    alias - The alias of the key.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If deleting the PKCS#11 objects fails.
  - deleteChertificateChain
```
protected void deleteChertificateChain(java.lang.String alias)
                                throws iaik.pkcs.pkcs11.TokenException
```
    Delete the certificate chain with the given alias.
    
    Parameters:
    
    alias - The alias of the certificate chain.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If deleting the PKCS#11 objects fails.
  - deleteCertificate
```
protected void deleteCertificate(java.lang.String alias)
                          throws iaik.pkcs.pkcs11.TokenException
```
    Delete the certificate with the given alias.
    
    Parameters:
    
    alias - The alias of the certificate.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If deleting the PKCS#11 objects fails.
  - createCertificate
```
protected iaik.pkcs.pkcs11.objects.Object createCertificate(java.security.cert.Certificate certificate,
                                                            byte[] id,
                                                            char[] label)
                                                     throws java.security.KeyStoreException
```
    Create a certificate object on the token as token object and assign the given ID to it, if the certificate type supports the ID attribute. X.509 public key certificates support the ID attribute, X.509 attribute certificates do not. The id parameter may be null, in which case the method will generate a new unique ID for the certificate if the certificate type supports IDs. This implementation supports X.509 public key certificates and X.509 attribute certificates of the class iaik.x509.attr.AttributeCertificate.
    
    Parameters:
    
    certificate - The certificate to store on the token.
    
    id - The ID to use for the certificate or null, to generate a new unique ID.
    
    label - The label of the new certificate object.
    
    Returns:
    
    The PKCS#11 object of the newly create PKCS#11 certificate object.
    
    Throws:
    
    java.security.KeyStoreException - If creating the certificate failed.
    
    Preconditions:
    
    (certificate < > null)
  - findCoreespondingKey
```
protected iaik.pkcs.pkcs11.objects.Key findCoreespondingKey(iaik.pkcs.pkcs11.objects.Key key)
                                                     throws iaik.pkcs.pkcs11.TokenException
```
    Find a key that corresponds to the given key; e.g. if the given key is a RSA private key, search for a RSA public key with the same modulus. This implementation handles RSA, DSA, ECDSA, DH and KEA private and public keys. If the given key is a private key, this method returns a public key and vice versa.
    
    Parameters:
    
    key - The key for which we try to find a corresponding key.
    
    Returns:
    
    The corresponding key, or null, if we could not find a corresponding key. However, this does not guarantee that there is no such key.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If searching for keys fails.
  - getMechanismFeaturesSupport
```
protected iaik.pkcs.pkcs11.MechanismInfo getMechanismFeaturesSupport(java.lang.String algorithmName)
                                                              throws iaik.pkcs.pkcs11.TokenException
```
    Check, what features of the given algorithm the token supports. Supported algorithms are: RSA, DSA, ECDSA, DH, KEA. The returned mechanism info is an OR combination of all mechanism info structures that the current token supports for the given algorithm. This method takes only mechanisms into account which take public or private keys as input parameter; i.e. sign, verify, encrypt, decrypt, wrap, unwrap, sign recover, verify recover, derive. It does not include key-pair generation or domain parameter generation.
    
    Parameters:
    
    algorithmName - The name of the algorithm.
    
    Returns:
    
    All features that can be used with public or private keys of the given algorithm. Returns null, if there is no mechanism of this algorithm supported.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If getting the required information from the token fails.
  - setKeyAttributes
```
protected void setKeyAttributes(iaik.pkcs.pkcs11.objects.PrivateKey keyTemplate,
                                java.security.cert.X509Certificate certificate,
                                iaik.pkcs.pkcs11.MechanismInfo supportedFeatures)
                         throws iaik.x509.X509ExtensionException,
                                java.security.cert.CertificateException
```
    Inspect the certificate and the mechanisms supported by the token and set the attributes of the private key template accordingly.
    
    Parameters:
    
    keyTemplate - The key templates where the attributes shall be set.
    
    certificate - The certificate from which we gain the key-usage information. May be null.
    
    supportedFeatures - The features supported by this token for the algorithm of the given key. May be null.
    
    Throws:
    
    iaik.x509.X509ExtensionException - If getting the key-usage extension fails.
    
    java.security.cert.CertificateException - If getting the key-usage extension fails.
    
    Preconditions:
    
    (keyTemplate < > null)
  - setKeyAttributes
```
protected void setKeyAttributes(iaik.pkcs.pkcs11.objects.PublicKey keyTemplate,
                                java.security.cert.X509Certificate certificate,
                                iaik.pkcs.pkcs11.MechanismInfo supportedFeatures)
                         throws iaik.x509.X509ExtensionException,
                                java.security.cert.CertificateException
```
    Inspect the certificate and the mechanisms supported by the token and set the attributes of the public key template accordingly.
    
    Parameters:
    
    keyTemplate - The key templates where the attributes shall be set.
    
    certificate - The certificate from which we gain the key-usage information. May be null.
    
    supportedFeatures - The features supported by this token for the algorithm of the given key. May be null.
    
    Throws:
    
    iaik.x509.X509ExtensionException - If getting the key-usage extension fails.
    
    java.security.cert.CertificateException - If getting the key-usage extension fails.
    
    Preconditions:
    
    (keyTemplate < > null)
  - createPrivateKeySpec
```
protected java.security.spec.KeySpec createPrivateKeySpec(java.security.Key key)
                                                   throws java.security.NoSuchProviderException,
                                                          java.security.NoSuchAlgorithmException,
                                                          java.security.spec.InvalidKeySpecException,
                                                          java.security.KeyStoreException
```
    Create a key spec out of the given key.
    
    Parameters:
    
    key - The key we need a key spec for.
    
    Returns:
    
    The key spec.
    
    Throws:
    
    java.security.NoSuchProviderException - If the secondary provider is unavailable.
    
    java.security.NoSuchAlgorithmException - If for the key algorithm is no factory in the secondary provider.
    
    java.security.spec.InvalidKeySpecException - If the required key spec class is unsupported by the secondary provider.
    
    java.security.KeyStoreException - If this method cannot convert this key.
    
    Postconditions:
    
    (result < > null)
  - createPublicKeySpec
```
protected java.security.spec.KeySpec createPublicKeySpec(java.security.Key key)
                                                  throws java.security.NoSuchProviderException,
                                                         java.security.NoSuchAlgorithmException,
                                                         java.security.spec.InvalidKeySpecException,
                                                         java.security.KeyStoreException
```
    Create a key spec out of the given key.
    
    Parameters:
    
    key - The key we need a key spec for.
    
    Returns:
    
    The key spec.
    
    Throws:
    
    java.security.NoSuchProviderException - If the secondary provider is unavailable.
    
    java.security.NoSuchAlgorithmException - If for the key algorithm is no factory in the secondary provider.
    
    java.security.spec.InvalidKeySpecException - If the required key spec class is unsupported by the secondary provider.
    
    java.security.KeyStoreException - If this method cannot convert this key.
    
    Postconditions:
    
    (result < > null)
  - createKeySpec
```
protected java.security.spec.KeySpec createKeySpec(java.security.Key key,
                                                   java.lang.Class keySpecClass)
                                            throws java.security.NoSuchProviderException,
                                                   java.security.NoSuchAlgorithmException,
                                                   java.security.spec.InvalidKeySpecException,
                                                   java.security.KeyStoreException
```
    Create a key spec out of the given key.
    
    Parameters:
    
    key - The key we need a key spec for.
    
    keySpecClass - The class object of the expected return value.
    
    Returns:
    
    The key spec.
    
    Throws:
    
    java.security.NoSuchProviderException - If the secondary provider is unavailable.
    
    java.security.NoSuchAlgorithmException - If for the key algorithm is no factory in the secondary provider.
    
    java.security.spec.InvalidKeySpecException - If the required key spec class is unsupported by the secondary provider.
    
    java.security.KeyStoreException - If this method cannot convert this key.
    
    Postconditions:
    
    (result < > null)
  - createSecretKeySpec
```
protected java.security.spec.KeySpec createSecretKeySpec(javax.crypto.SecretKey key)
                                                  throws java.security.NoSuchProviderException,
                                                         java.security.NoSuchAlgorithmException,
                                                         java.security.spec.InvalidKeySpecException,
                                                         java.security.KeyStoreException
```
    Create a key spec out of the given key.
    
    Parameters:
    
    key - The key we need a key spec for.
    
    Returns:
    
    The key spec.
    
    Throws:
    
    java.security.NoSuchProviderException - If the secondary provider is unavailable.
    
    java.security.NoSuchAlgorithmException - If for the key algorithm is no factory in the secondary provider.
    
    java.security.spec.InvalidKeySpecException - If the required key spec class is unsupported by the secondary provider.
    
    java.security.KeyStoreException - If this method cannot convert this key.
    
    Postconditions:
    
    (result < > null)
  - createKeyCreationTemplate
```
protected iaik.pkcs.pkcs11.objects.Key createKeyCreationTemplate(iaik.pkcs.pkcs11.objects.Key baseKey)
```
    Create a template based on the given key. Depending on the type of key this method sets the attributes of the key template that it may be used as a template for key creation. This consists mainly of setting certain attributes as not present, which are not allowed to be set in the object template when creating a key. All allowed attributes are copied from the given base key.
    
    Parameters:
    
    baseKey - The key that serves as a basis for the template.
    
    Returns:
    
    A new key template suitable as input to a object creation function.
    
    Postconditions:
    
    (result < > null)
    
    Preconditions:
    
    (baseKey < > null)
  - generateNewID
```
protected byte[] generateNewID(byte[] suggestedID)
                        throws iaik.pkcs.pkcs11.TokenException
```
    Generates a new ID that is not used by any existing object on the keystore token yet. This method uses the writeSession_ session to check, if an ID is already used.
    
    Parameters:
    
    suggestedID - This is the suggested ID that will be tried first. If it is unique (unused), it will be used. Otherwise, it will be incremented until it becomes unique.
    
    Returns:
    
    A new ID that is not used by any existing object on the keystore token yet.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If checking if an ID is already used fails.
    
    Postconditions:
    
    (result < > null)
  - ensureCurrentTables
```
protected void ensureCurrentTables()
                            throws IAIKPkcs11Exception
```
    This method calls method update().
    
    Throws:
    
    IAIKPkcs11Exception - If the update fails.
  - ensureReadSession
```
protected void ensureReadSession()
                          throws iaik.pkcs.pkcs11.TokenException,
                                 IAIKPkcs11Exception
```
    This method ensures that an appropriate session is open. If the token changed meanwhile, this method disposes the old session and opens a new one.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If accessing the token fails.
    
    IAIKPkcs11Exception - If an error occurred in the provider.
  - ensureWriteSession
```
protected void ensureWriteSession()
                           throws iaik.pkcs.pkcs11.TokenException,
                                  IAIKPkcs11Exception
```
    This method ensures that an appropriate session is open. If the token changed meanwhile, this method disposes the old session and opens a new one.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If accessing the token fails.
    
    IAIKPkcs11Exception - If an error occurred in the provider.
  - releaseSessions
```
protected void releaseSessions()
```
    A call to this method signals that the sessions are no longer used. Before the read or write session is available once again, the ensureReadSession or ensureWriteSession method must be called.
  - createUniqueAlias
```
protected java.lang.String createUniqueAlias(iaik.pkcs.pkcs11.objects.Object pkcs11Object,
                                             java.util.Set usedAliases)
```
    This method creates a alias for the given pkcs#11 object that does not already exist in this key store. It uses the object's label for creating the alias and maybe also the object handle, if the label does not provide an unique alias.
    
    Parameters:
    
    pkcs11Object - For this pkcs#11 object this method creates an alias.
    
    usedAliases - This is the set of already used aliases.
    
    Returns:
    
    A alias name that does not exist in this key store.
    
    Postconditions:
    
    (engineContainsAlias ( result) == false)
    
    Preconditions:
    
    (pkcs11Object < > null)
  - contains
```
protected boolean contains(java.util.List arrays,
                           byte[] other)
```
  - findKeysAndCertificateTables
```
protected void findKeysAndCertificateTables()
                                     throws iaik.pkcs.pkcs11.TokenException,
                                            java.security.KeyStoreException
```
    Find all keys and certificates on the token put them in the right tables.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If a search or read operation fails.
    
    java.security.KeyStoreException - If there are illegal contents in the key store.
  - initialize
```
protected void initialize()
```
    Do the internal initialization. This requires that the tokenManager_ variable has been set correctly.
  - isEndUserCertificate
```
protected boolean isEndUserCertificate(iaik.x509.X509Certificate certificate)
                                throws java.security.cert.CertificateException
```
    Check if the given certificate is a end-user certificate.
    
    Parameters:
    
    certificate - The certificate to check.
    
    Returns:
    
    True, if the certificate is a end-user certificate.
    
    Throws:
    
    java.security.cert.CertificateException - If inspecting the certificate fails.
    
    Preconditions:
    
    (certificate < > null)
  - createCertificateChain
```
protected iaik.x509.X509Certificate[] createCertificateChain(iaik.x509.X509Certificate userCertificate,
                                                             java.util.Map subjectToCertificatesMap,
                                                             char[] label,
                                                             iaik.pkcs.pkcs11.provider.IdentityMap trustedCertificates)
```
    Create a certificate chain that starts with the given user certificate. The available certificates are given as the values of the Map. The key to the map is the RFC2253 string of the certifcate's subject. The certificates in the map are all s.
    
    Parameters:
    
    userCertificate - The user certificate.
    
    subjectToCertificatesMap - The map; key is the RFC 2253 subject string, value is an iaik.x509.X509Certificate.
    
    Returns:
    
    The certificate chain.
    
    Preconditions:
    
    (userCertificate < > null) and (subjectToCertificatesMap <> null)
  - getReadProtectedKeyOnDemand
```
protected boolean getReadProtectedKeyOnDemand()
```
    This property causes this object to search for objects using only a not explicitly logged-in session. This may result in using a public session, in which the find operation will only find public objects. The key store will assume an existing private key for each end-user certificate on the token. It will log-in the session, when the application tries to get this corresponding key. However, this may result in the situation that private keys without certificate are not listed in the keystore, before the session is logged in.
    
    Returns:
    
    True, if the key store shall not explicitly log-in the session for search keys and certificates. It will log-in only, if the application tries to access such a key.
  - setReadProtectedKeyOnDemand
```
protected void setReadProtectedKeyOnDemand(boolean onDemand)
```
    Setting this property causes this object to search for objects using only a not explicitly logged-in session. This may result in using a public session, in which the find operation will only find public objects. The key store will assume an existing private key for each end-user certificate on the token. It will log-in the session, when the application tries to get this corresponding key. However, this may result in the situation that private keys without certificate are not listed in the keystore, before the session is logged in.
    
    Parameters:
    
    onDemand - True, if the key store shall not explicitly log-in the session for search keys and certificates. It will log-in only, if the application tries to access such a key.
  - openReadSession
```
protected void openReadSession()
```
    Opens a session with the necessary rights for searching keys and certificates. This will be a read-only session.
    
    Throws:
    
    IAIKPkcs11Exception - If opening the session or logging in the user fails.
  - openWriteSession
```
protected void openWriteSession()
```
    Opens a session with the necessary rights for searching keys and certificates. This will be a read-write session.
    
    Throws:
    
    IAIKPkcs11Exception - If opening the session or logging in the user fails.
  - readProviderName
```
protected java.lang.String readProviderName(java.io.InputStream in)
                                     throws java.io.IOException
```
    Read the complete content of the stream and return the content as string. UTF-8 encoding assumed.
    
    Parameters:
    
    in - The stream that provides the characters of the string.
    
    Returns:
    
    The content of the stream as string.
    
    Throws:
    
    java.io.IOException - If reading the stream fails.
    
    Postconditions:
    
    (result < > null)
    
    Preconditions:
    
    (in < > null)
  - writeProviderName
```
protected void writeProviderName(java.lang.String providerName,
                                 java.io.OutputStream out)
                          throws java.io.IOException
```
    Write the provider name to the given output stream. UTF-8 encoding is used.
    
    Parameters:
    
    providerName - The provider's name.
    
    out - The stream for writing the provider name.
    
    Throws:
    
    java.io.IOException - If writing the name fails.
    
    Preconditions:
    
    (providerName < > null) and (out <> null)
  - loginSession
```
protected boolean loginSession()
```
    Logs in the current session, if a login is required.
    
    Returns:
    
    True, if this call did actually call the login method of the underlying PKCS#11 module, false, if the user was already logged in or a login is not required by the token.
    
    Throws:
    
    IAIKPkcs11Exception - If opening the session or logging in the user fails.
  - logoutSession
```
protected void logoutSession()
```
    This method logs out the session of this key store. If the key store has no cached session, it will request the TokenManager to logout using any session. Attention! This causes all sessions of this token to be logged out. Any currently active operations on this token like signing may be interrupted.
  - clearTables
```
protected void clearTables()
```
    Clear all tables.
  - ensureSupportProvider
```
protected void ensureSupportProvider()
```
    Ensure that the keystore support provider name is available in the supportProviderName_ field.
  - updateTables
```
protected void updateTables()
```
    This method calls the appropriate methods to get all available keys and certificates and stores them in a hash table.
  - isUpToDate
```
protected boolean isUpToDate()
                      throws iaik.pkcs.pkcs11.TokenException
```
    Check, if the tables are up to date.
    
    Parameters:
    
    token - token object to be used to get token specific information, if null token is directly accessed to get information
    
    Returns:
    
    True if the tables are up to date, false otherwise.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If token access fails.
  - setUpToDate
```
protected void setUpToDate(boolean isUpToDate)
```
    Set, if the tables are up to date. If false, invalidate the content of this keystore. This causes the tables to update on next request.
    
    Parameters:
    
    isUpToDate - If true, the tables are up to date, if false, the tables need to be updated.
  - tokenChanged
```
protected boolean tokenChanged()
                        throws iaik.pkcs.pkcs11.TokenException
```
    Check, if the token was changed. This includes removing or inserting a token.
    
    Returns:
    
    True if the token was changed, false otherwise.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If token access fails.
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Try to close the session that this object opened.
    
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable - If the close fails.

IAIK JavaSecurity Website https://jce.iaik.tugraz.at/

IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2023 IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved. Version 1.9.4

Class TokenKeyStoreSpi

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.security.KeyStoreSpi

Methods inherited from class java.lang.Object

Field Detail

KEY_STORE_TYPE

tokenManager_

readSession_

writeSession_

aliases_

keys_

certificateChains_

trustedCertificates_

keyAliasToPkcs11ObjectTable_

certificateChainAliasToPkcs11ObjectsTable_

trustedCertificateAliasToPkcs11ObjectTable_

isUpToDate_

useUserSession_

infoOfRecentToken_

lastNewID_

supportProviderName_

usedMechanisms_

usedMechanismInfos_

userPIN_

Constructor Detail

TokenKeyStoreSpi

TokenKeyStoreSpi

Method Detail

engineAliases

engineContainsAlias

engineDeleteEntry

engineGetCertificate

engineGetCertificateAlias

engineGetCertificateChain

engineGetCreationDate

engineGetKey

engineIsCertificateEntry

engineIsKeyEntry

engineLoad

engineSetCertificateEntry

engineSetKeyEntry

engineSetKeyEntry

engineSize

engineStore

getTokenManager

isSupportedBy

deleteKey

deleteChertificateChain

deleteCertificate

createCertificate

findCoreespondingKey

getMechanismFeaturesSupport

setKeyAttributes

setKeyAttributes

createPrivateKeySpec

createPublicKeySpec

createKeySpec

createSecretKeySpec

createKeyCreationTemplate

generateNewID

ensureCurrentTables

ensureReadSession

ensureWriteSession

releaseSessions

createUniqueAlias

contains

findKeysAndCertificateTables

initialize

isEndUserCertificate

createCertificateChain

getReadProtectedKeyOnDemand

setReadProtectedKeyOnDemand

openReadSession

openWriteSession

readProviderName

writeProviderName

loginSession

logoutSession