Initialization

The IBMPKCS11Impl provider must be initialized using one of three different methods. Otherwise, the provider will not have any algorithms associated with it and will not be able to do anything. The three methods are Java™ Preferences, a JAAS Login Module, and the Direct method. If the provider is in the list but not initialized and you explicitly call the IBMPKCS11Impl provider than you will get a NoSuchAlgorithmException exception. If you don't specify a provider then you will get the first provider in the list that supports that algorithm, which will not be the IBMPKCS11Impl provider. The direct method of initialization has two types one using a DLL and slot and the other using configuration file. The configuration file method is the preferred method for this release. The other methods using a JAAS Login module and Preferences are not covered here since 5.0 or later applications should not use them.

The last way, which is the preferred way for this release, is by using a configuration file. There are sample configuration files provided with the documentation that should be used for the hardware device that you are using. Here is a basic configuration file:

name = foo
library=C:/WINNT/system32/foo.dll
description=the Foo hardware device config.

slotListIndex = 0

You must use a fully qualified path in your configuration file.

Here is code that makes use of the previous configuration file:

com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl p1 = null;

// create new provider from the fooconfig configuration file
p1 = new com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl("d:/fooconfig");

//The name of the provider based on the value from the config file.
String provName = "IBMPKCS11Impl-foo";

try {
    //Add provider to provider list
    Security.addProvider(p1);

    //The next set of code uses the NullPrompter class to pass the password
    //into the provider to pass to the hardware device.
    String pswd = "PASSWORD";
    char [] passwd = new char[pswd.length()];
    pswd.getChars(0,pswd.length(),passwd,0);
    NullPrompter np = new NullPrompter(passwd);
    p1.login(null, np);

} catch (Exception ex) {
    ex.printStackTrace();
    System.out.println("Unexpected exception0: " + ex.getMessage());
    return;
}


public class NullPrompter implements javax.security.auth.callback.CallbackHandler 
{
   private String userName;
   private char[] authenticator;

   private NullPrompter() { // hide the null constructor, since we're not prompting!
   }

   public NullPrompter(String userName, char authenticator[]) {
     this.userName = userName;
     this.authenticator = authenticator;
   }

   public void nukeEm() {
      this.userName = null;
      for (int i = 0; i < authenticator.length; i++)
            authenticator[i] = ' ';
   }

   public void handle(Callback[] callbacks)
     throws IOException, UnsupportedCallbackException {
       for (int i = 0; i < callbacks.length; i++) {
          if (callbacks[i] instanceof TextOutputCallback) {
          }
          else if (callbacks[i] instanceof TextInputCallback) {
            ((TextInputCallback)callbacks[i]).setText(userName);
          }
          else if (callbacks[i] instanceof PasswordCallback) {
            ((PasswordCallback)callbacks[i]).setPassword(authenticator);
          } else {
            throw new UnsupportedCallbackException
            (callbacks[i], "Unrecognized Callback");
          }
       }
   }
}

Since 1.4.2, the IBMJSSE2 provider is able to be configured to use hardware cryptographic accelerators for potential performance improvement and to use hardware cryptographic cards as keystores for greater flexibility in key and trust management.

In 5.0 or later, in order to be compatible with Oracle's PKCS#11 support, a configuration file will now be required, even for code which ran successfully without one in 1.4.2. This configuration file is specific to each hardware device and JSSE. See the sample configuration file specific to the hardware device you are using.

Here is same basic configuration file shown before, but for JSSE. Note that the MD5 and SHA1 operations must be turned off for JSSE. Make sure to see the configuration file specific for the hardware device for other mechanism and attribute specific settings.

name = foo
library=C:/WINNT/system32/foo.dll
description=the Foo hardware device config for JSSE.

slotListIndex = 0


disabledMechanisms = {
  CKM_MD5
  CKM_SHA_1
  CKM_MD5_HMAC
  CKM_SHA_1_HMAC
  
}

You must use a fully qualified path in your configuration file.

The JSSE protocol requires a symmetric key to be created jointly between the client and the server. When symmetric keys are made sensitive or the card is made sensitive, the hardware will not allow the software key to be put on the cryptographic card. If a card is modified to make it sensitive or through the configuration file, symmetric keys are made sensitive, then the symmetric keys would have to be disabled in the hardware configuration file to be used with JSSE. JSSE would therefore be using software for its bulk encryption instead of hardware.

Use of the hardware cryptographic accelerator is automatic if the IBMPKCS11Impl provider has been configured, supports that function and is in the provider list. In 1.4.2, the cryptographic accelerator would be used if it was anywhere in the provider list, even if the JCE software provider was before it. In this release, the configured IBMPKCS11Impl provider does not require be before any other JCA/JCE providers in the provider list.

IBMJSSE2 supports the accessing of hardware keystore through the IBMPKCS11Impl keystore, PKCS11IMPLKS. An application must configure the IBMPKCS11Impl provider, add the hardware provider to the provider list before the JCA/JCE provider, and set the KeyStore provider to, IBMPKCS11IMPLKS. The IBMPKCS11Impl will now be used for most JSSE cryptographic functions including the handling of cryptographic hardware keys in the keystore.