Keystore for IBMPKCS11Impl

Certain PKCS#11 operations, such as accessing private keys, require a login using a Personal Identification Number, or PIN, before the operations can proceed. The most common type of operations that require login are those that deals with keys on the hardware device. In a Java™ application, such operations often involve first loading the keystore. This provider supports one keystore: PKCS11IMPLKS. This keystore is not a standard flat file keystore. This keystore reads certificates and keys off of the hardware device. It can store the certificates and keys on the hardware device either permanently as token objects or temporarily that will exist for only the length of provider initialization. See details on IBM® PKCS11 Impl Provider's KeyStore requirements on the underlying native PKCS#11 library in Appendix B.

When accessing the PKCS#11 token as a keystore via the java.security.KeyStore class, you can supply the PIN in the password input parameter to the load method, similar to how applications initialize a keystore prior to SDK 5.0. The PIN will then be used by the IBM PKCS#11 provider for logging into the token. Here is an example:

char[] pin = ...; 
KeyStore ks = KeyStore.getInstance("PKCS11IMPLKS", provider);
ks.load(null, pin);

For an application that wants to accommodate PKCS#11 tokens more dynamically, such as Smartcards being inserted and removed, you may want to use the KeyStore.load(KeyStore.LoadStoreParameter) method. Alternatively, you can use the new KeyStore.Builder class to decouple the configuration from KeyStore. Here is an example of how to initialize the builder for a PKCS#11 keystore with a callback handler:

KeyStore.CallbackHandlerProtection protection = new 
KeyStore.CallbackHandlerProtection(handler);
KeyStore.Builder builder = KeyStore.Builder.newInstance("PKCS11",  
provider, 
protection);

The IBMPKCS11Impl provider supports password call back. For the initial access, it will prompt for a password. It prompts only once if the user continues to use the same card. If the user logouts, then logins again using a different card, the builder will prompt for a password for the new card using the previously configured callback handler. Note that if the user removes the card without explicitly logouts, the behavior is not predicted.