IAIK PKCS#11 Provider API Documentation
version 1.6

iaik.pkcs.pkcs11.provider
Class TokenKeyStoreSpi

java.lang.Object
  extended by java.security.KeyStoreSpi
      extended by 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
static java.lang.String KEY_STORE_TYPE
          The type name of this key store.
 
Constructor Summary
TokenKeyStoreSpi()
          Construct a new uninitialized keystore.
TokenKeyStoreSpi(TokenManager tokenManager)
          Construct a new keystore from the given PKCS#11 token.
 
Method Summary
 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.
 TokenManager getTokenManager()
          Get the token manager of the token that holds the contents of this key store.
 boolean isSupportedBy(TokenManager tokenManager)
          Check, if the current token of the given token manager supports the required features for this engine class.
 
Methods inherited from class java.security.KeyStoreSpi
engineEntryInstanceOf, engineGetEntry, engineLoad, engineSetEntry, engineStore
 
Methods inherited from class java.lang.Object
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
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)
Preconditions
(alias <> null)
Postconditions
(result <> 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)

IAIK PKCS#11 Provider API Documentation
version 1.6

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

IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2004, IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved.
version 1.6