com.ibm.crypto.pkcs11impl.provider
Class PKCS11KeyStore

java.lang.Object
  extended by java.security.KeyStoreSpi
      extended by com.ibm.crypto.pkcs11impl.provider.PKCS11KeyStore

public final class PKCS11KeyStore
extends java.security.KeyStoreSpi

This class provides the keystore implementation of PKCS #11.

See Also:
KeyStoreSpi

Constructor Summary
PKCS11KeyStore()
          Creates an instance of this class
PKCS11KeyStore(java.security.Provider provider)
          Creates an instance of this class
 
Method Summary
 java.util.Enumeration engineAliases()
          Lists all the alias names of this keystore.
 boolean engineContainsAlias(java.lang.String alias)
          Checks if the given alias exists in this keystore.
 void engineDeleteEntry(java.lang.String alias)
          Deletes the entry identified by the given alias from this keystore and the token.
 java.security.cert.Certificate engineGetCertificate(java.lang.String alias)
          Returns the certificate associated with the given alias.
 java.lang.String engineGetCertificateAlias(java.security.cert.Certificate cert)
          Returns the (alias) name of the first keystore entry whose certificate matches the given certificate.
 java.security.cert.Certificate[] engineGetCertificateChain(java.lang.String alias)
          Returns the certificate chain associated with the given alias.
 java.util.Date engineGetCreationDate(java.lang.String alias)
          This method is suppose to return the creation date of the entry identified by the given alias.
 java.security.KeyStore.Entry engineGetEntry(java.lang.String alias, java.security.KeyStore.ProtectionParameter protParam)
          Get a KeyStore.Entry for the specified alias
 java.security.Key engineGetKey(java.lang.String alias, char[] password)
          Returns the key associated with the given alias.
 boolean engineIsCertificateEntry(java.lang.String alias)
          Returns true if the entry identified by the given alias is a trusted certificate entry, and false otherwise.
 boolean engineIsKeyEntry(java.lang.String alias)
          Returns true if the entry identified by the given alias is a key entry, and false otherwise.
 void engineLoad(java.io.InputStream stream, char[] password)
          Loads the keystore from the session associated with the IBMPKCS11Impl provider.
 void engineLoad(java.security.KeyStore.LoadStoreParameter param)
          Loads the keystore from the session associated with the IBMPKCS11Impl provider.
 void engineSetCertificateEntry(java.lang.String alias, java.security.cert.Certificate cert)
          Assigns the given certificate to the given alias.
 void engineSetEntry(java.lang.String alias, java.security.KeyStore.Entry entry, java.security.KeyStore.ProtectionParameter protParam)
          Save a KeyStore.Entry under the specified alias.
 void engineSetKeyEntry(java.lang.String alias, byte[] key, java.security.cert.Certificate[] chain)
          Assigns the given key (that has already been protected) to the given alias.
 void engineSetKeyEntry(java.lang.String alias, java.security.Key key, char[] password, java.security.cert.Certificate[] chain)
          Assigns the given key to the given alias.
 int engineSize()
          Retrieves the number of entries in this keystore.
 void engineStore(java.io.OutputStream stream, char[] password)
          Stores this keystore to the given output stream, and protects its integrity with the given password.
 
Methods inherited from class java.security.KeyStoreSpi
engineEntryInstanceOf, engineStore
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PKCS11KeyStore

public PKCS11KeyStore()
Creates an instance of this class


PKCS11KeyStore

public PKCS11KeyStore(java.security.Provider provider)
Creates an instance of this class

Method Detail

engineGetKey

public java.security.Key engineGetKey(java.lang.String alias,
                                      char[] password)
                               throws java.security.NoSuchAlgorithmException,
                                      java.security.UnrecoverableKeyException
Returns the key associated with the given alias.

Specified by:
engineGetKey in class java.security.KeyStoreSpi
Parameters:
alias - the alias name
password - is not used by this key store.
Returns:
the requested key, or null if the given alias does not exist or does not identify a key entry.
Throws:
java.security.NoSuchAlgorithmException - if the algorithm for recovering the key cannot be found
java.security.UnrecoverableKeyException - if the key cannot be recovered (e.g., the given password is wrong).

engineGetCertificateChain

public java.security.cert.Certificate[] engineGetCertificateChain(java.lang.String alias)
Returns the certificate chain associated with the given alias.

Specified by:
engineGetCertificateChain in class java.security.KeyStoreSpi
Parameters:
alias - the alias name
Returns:
the certificate chain (ordered with the user's certificate first and the root certificate authority last), or null if the given alias does not exist or does not contain a certificate chain (i.e., the given alias identifies either a trusted certificate entry or a key entry without a certificate chain).

engineGetCertificate

public java.security.cert.Certificate engineGetCertificate(java.lang.String alias)
Returns the certificate associated with the given alias.

If the given alias name identifies a trusted certificate entry, the certificate associated with that entry is returned. If the given alias name identifies a key entry, the first element of the certificate chain of that entry is returned, or null if that entry does not have a certificate chain.

Specified by:
engineGetCertificate in class java.security.KeyStoreSpi
Parameters:
alias - the alias name
Returns:
the certificate, or null if the given alias does not exist or does not contain a certificate.

engineGetEntry

public java.security.KeyStore.Entry engineGetEntry(java.lang.String alias,
                                                   java.security.KeyStore.ProtectionParameter protParam)
                                            throws java.security.KeyStoreException,
                                                   java.security.NoSuchAlgorithmException,
                                                   java.security.UnrecoverableEntryException
Get a KeyStore.Entry for the specified alias

Overrides:
engineGetEntry in class java.security.KeyStoreSpi
Parameters:
alias - get the KeyStore.Entry for this alias
protParam - this must be null
Returns:
the KeyStore.Entry for the specified alias, or null if there is no such entry
Throws:
java.security.KeyStoreException - if the operation failed
java.security.NoSuchAlgorithmException - if the algorithm for recovering the entry cannot be found
java.security.UnrecoverableEntryException - if the specified protParam were insufficient or invalid
Since:
1.5

engineSetEntry

public void engineSetEntry(java.lang.String alias,
                           java.security.KeyStore.Entry entry,
                           java.security.KeyStore.ProtectionParameter protParam)
                    throws java.security.KeyStoreException
Save a KeyStore.Entry under the specified alias.

If an entry already exists for the specified alias, it is overridden.

This KeyStore implementation only supports the standard entry types, This implementation does not support a protection Parameter, it will be ignored. The password will be the one associated with the token.

Entries are immediately stored on the token.

see engineSetKeyEntry and engineSetCertificateEntry for more information on adding keys and certificates using this keystore.

Overrides:
engineSetEntry in class java.security.KeyStoreSpi
Parameters:
alias - save the KeyStore.Entry under this alias
entry - the Entry to save
protParam - this must be null
Throws:
java.security.KeyStoreException - if this operation fails
Since:
1.5

engineGetCreationDate

public java.util.Date engineGetCreationDate(java.lang.String alias)
This method is suppose to return the creation date of the entry identified by the given alias. However, this is not supported and always returns a date of January 1, 1970, 00:00:00 GMT

Specified by:
engineGetCreationDate in class java.security.KeyStoreSpi
Parameters:
alias - the alias name
Returns:
Always returns January 1, 1970, 00:00:00 GMT

engineSetKeyEntry

public void engineSetKeyEntry(java.lang.String alias,
                              java.security.Key key,
                              char[] password,
                              java.security.cert.Certificate[] chain)
                       throws java.security.KeyStoreException
Assigns the given key to the given alias.

If the given key is of type java.security.PrivateKey, it must be accompanied by a certificate chain certifying the corresponding public key.

If a key entry already exists with that alias than that key entry will be replaced with the new one.

If the key is already a PKCS11 session key than this function will try and make the key a token key. Basically save the key on the card permanently.

If the key to be associated with alias is not a PKCS11Key than the code will try to translate the key to a PKCS11Key using the KeyFactory for than type of key. Therefore, if a configuration file was used to initialize the provider than attributes from that will be used to import the key to the card. If not, than the key will be created as a session key only and not be actually stored on the token permanently.

Note: The certificates in the certificate chain are not added or deleted from the token. This should be done using certificate entries.

Specified by:
engineSetKeyEntry in class java.security.KeyStoreSpi
Parameters:
alias - the alias name
key - the key to be associated with the alias
password - this parameter has no meaning currently for PKCS11 and there is not used.
chain - the certificate chain for the corresponding public key (only required if the given key is of type java.security.PrivateKey).
Throws:
java.security.KeyStoreException - if the given key cannot be protected, or this operation fails for some other reason

engineSetKeyEntry

public void engineSetKeyEntry(java.lang.String alias,
                              byte[] key,
                              java.security.cert.Certificate[] chain)
                       throws java.security.KeyStoreException
Assigns the given key (that has already been protected) to the given alias. This key store does not not support this method and a KeyStoreException is always thrown if this method is called.

Specified by:
engineSetKeyEntry in class java.security.KeyStoreSpi
Parameters:
alias - the alias name
key - the key (in protected format) to be associated with the alias
chain - the certificate chain for the corresponding public key (only useful if the protected key is of type java.security.PrivateKey).
Throws:
java.security.KeyStoreException - is always thrown.

engineSetCertificateEntry

public void engineSetCertificateEntry(java.lang.String alias,
                                      java.security.cert.Certificate cert)
                               throws java.security.KeyStoreException
Assigns the given certificate to the given alias.

If a trusted certificate entry already exists with that alias than that entry may be replaced with the new one. To make sure that this keystore matchs, what is currently associated with the token than use load to reload the key store.

Note: This method will add the certificate to the token as a token object.

Specified by:
engineSetCertificateEntry in class java.security.KeyStoreSpi
Parameters:
alias - the alias name
cert - the certificate
Throws:
java.security.KeyStoreException - if the given alias already exists and does not identify a trusted certificate entry, or this operation fails for some other reason.

engineDeleteEntry

public void engineDeleteEntry(java.lang.String alias)
                       throws java.security.KeyStoreException
Deletes the entry identified by the given alias from this keystore and the token.

Specified by:
engineDeleteEntry in class java.security.KeyStoreSpi
Parameters:
alias - the alias name
Throws:
java.security.KeyStoreException - if the entry cannot be removed.

engineAliases

public java.util.Enumeration engineAliases()
Lists all the alias names of this keystore.

Specified by:
engineAliases in class java.security.KeyStoreSpi
Returns:
enumeration of the alias names

engineContainsAlias

public boolean engineContainsAlias(java.lang.String alias)
Checks if the given alias exists in this keystore.

Specified by:
engineContainsAlias in class java.security.KeyStoreSpi
Parameters:
alias - the alias name
Returns:
true if the alias exists, false otherwise

engineSize

public int engineSize()
Retrieves the number of entries in this keystore.

Specified by:
engineSize in class java.security.KeyStoreSpi
Returns:
the number of entries in this keystore

engineIsKeyEntry

public boolean engineIsKeyEntry(java.lang.String alias)
Returns true if the entry identified by the given alias is a key entry, and false otherwise.

Specified by:
engineIsKeyEntry in class java.security.KeyStoreSpi
Returns:
true if the entry identified by the given alias is a key entry, false otherwise.

engineIsCertificateEntry

public boolean engineIsCertificateEntry(java.lang.String alias)
Returns true if the entry identified by the given alias is a trusted certificate entry, and false otherwise.

Specified by:
engineIsCertificateEntry in class java.security.KeyStoreSpi
Returns:
true if the entry identified by the given alias is a trusted certificate entry, false otherwise.

engineGetCertificateAlias

public java.lang.String engineGetCertificateAlias(java.security.cert.Certificate cert)
Returns the (alias) name of the first keystore entry whose certificate matches the given certificate.

This method attempts to match the given certificate with each keystore entry. If the entry being considered is a trusted certificate entry, the given certificate is compared to that entry's certificate. If the entry being considered is a key entry, the given certificate is compared to the first element of that entry's certificate chain (if a chain exists).

Specified by:
engineGetCertificateAlias in class java.security.KeyStoreSpi
Parameters:
cert - the certificate to match with.
Returns:
the (alias) name of the first entry with matching certificate, or null if no such entry exists in this keystore.

engineStore

public void engineStore(java.io.OutputStream stream,
                        char[] password)
                 throws java.io.IOException,
                        java.security.NoSuchAlgorithmException,
                        java.security.cert.CertificateException
Stores this keystore to the given output stream, and protects its integrity with the given password.

This method is not supported by this key store and will always throw a IOException

Specified by:
engineStore in class java.security.KeyStoreSpi
Parameters:
stream - the output stream to which this keystore is written.
password - the password to generate the keystore integrity check
Throws:
java.io.IOException - always thrown
java.security.NoSuchAlgorithmException - is here for compatability.
java.security.cert.CertificateException - is here for compatability.

engineLoad

public void engineLoad(java.security.KeyStore.LoadStoreParameter param)
                throws java.io.IOException,
                       java.security.NoSuchAlgorithmException,
                       java.security.cert.CertificateException
Loads the keystore from the session associated with the IBMPKCS11Impl provider. This loads all private keys, secret keys and certificates.

Overrides:
engineLoad in class java.security.KeyStoreSpi
Parameters:
stream - this parameter is not used by the method and can be any value
password - this parameter is not used by the method and can be any value
Throws:
java.io.IOException - if there is an I/O or format problem with the keystore data
java.security.NoSuchAlgorithmException - if the algorithm used to check the integrity of the keystore cannot be found
java.security.cert.CertificateException - if any of the certificates in the keystore could not be loaded

engineLoad

public void engineLoad(java.io.InputStream stream,
                       char[] password)
                throws java.io.IOException,
                       java.security.NoSuchAlgorithmException,
                       java.security.cert.CertificateException
Loads the keystore from the session associated with the IBMPKCS11Impl provider. This loads all private keys, secret keys and certificates.

Specified by:
engineLoad in class java.security.KeyStoreSpi
Parameters:
stream - this parameter is not used by the method and can be any value
password - this parameter is not used by the method and can be any value
Throws:
java.io.IOException - if there is an I/O or format problem with the keystore data
java.security.NoSuchAlgorithmException - if the algorithm used to check the integrity of the keystore cannot be found
java.security.cert.CertificateException - if any of the certificates in the keystore could not be loaded