Use IKEYMAN to store keys on a PKCS11 device

Before you begin

Read about the IBMPKCS11Impl provider at http://www.ibm.com/developerworks/java/jdk/security/60/secguides/pkcs11implDocs/IBMJavaPKCS11ImplementationProvider.html#ConfigFile.

Procedure

• Obtain the file name and the path location of the cryptographic driver in order to store the keys on the PKCS11 device. The following are examples of path locations for PKCS11 devices:

  • nCipher:

    • /opt/nfast/toolkits/pkcs11/libcknfast.so

    • /opt/nfast/toolkits/pkcs11/libcknfast.sl

    • /opt/nfast/toolkits/pkcs11/libcknfast.so

    • /opt/nfast/toolkits/pkcs11/libcknfast.so

    • C:\nfast\toolkits\pkcs11\cknfast.dll

  • IBM 4758

    • /usr/lib/pkcs11/PKCS11_API.so

    • $PKCS11_HOME\bin\NT\cryptoki.dll

  • IBM e-business Cryptographic Accelerator

    • /usr/lib/pkcs11/PKCS11_API.so

• If your Web server and Java™ Development Kit (JDK) are 64-bit, select a 64-bit vendor PKCS11 library.

  On some platforms, the 64-bit PKCS11 library filename has 64 appended to it.

  We can display the architecture of the Web server by running apachectl -V.

  We can display the architecture of the Web server by running httpd.exe -V.

• Determine the token label of the PKCS11 token that you use.

  Native vendor tools, such as pkcsconf -its, often display the token label.

• Create a PKCS11 configuration file describing your PKCS11 device using the following fields:

  • library: Full path to the proper architecture PKCS11 driver

  • name: Same as the token label from the previous step

  • description: Text field with your description

  • attributes: A set of attributes that you copy verbatim from the certificates example that the Web server uses

  Note: With some cryptographic accelerators, an alternate syntax is required to avoid SSL0227E errors. /opt/HTTPServer/conf/pkcs11.cfg example:

  library = /usr/lib/pkcs11/PKCS11_API.so
  name = PCI
  description = description
  attributes(*,CKO_PRIVATE_KEY,*) =
            {CKA_PRIVATE=true CKA_TOKEN=true)
  

• Update the java/jre/lib/security/java.security file under the installation root to add a new security provider.

  • Have the new security provider reference the GSKit PKCS11 classes and the location of your PKCS11 configuration file.

  • Append the provider to the end of the provider list as the new highest-numbered provider.

  • Modify the following examples to specify the location of your configuration file.

    Some of the lines are split on multiple lines for display purposes. Enter a line as a single line even if it displays in this task as multiple lines.

  # The following line is the last pre-existing security provider.
  security.provider.12=com...
  # Add the following line.
  security.provider.13=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl /opt/HTTPServer/conf/pkcs11.cfg
  

  # The following line is the last pre-existing security provider.
  security.provider.12=com...
  # Add the following line.
  security.provider.13=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl C:\opt\HTTPServer\conf\pkcs11.cfg
  

• Run IKEYMAN to store the keys on the PKCS11 device.

  After launching IKEYMAN:

  1. Select Key Database File from the menu, then Open to navigate to the Key database information dialog

  2. From the drop-down for Key Database Type, select PKCS11Config.

     If PKCS11Config is not an option, but PKCS11Direct is, you have an error that you must fix. Check your java.security work in prior steps. The PKCS11Direct option is not visible to the Web server.

     All other fields become locked, as the parameters are provided from the pkcs11.cfg file.

  3. Click OK to navigate to the Open Cryptographic Token dialog.

     The Cryptographic Token Label label of the PKCS11 device is displayed in the panel. This label comes from the name field of the pkcs11.cfg file, and might be different from the native token label.

  4. Complete the following actions on the Open Cryptographic Token dialog.

     1. Enter the cryptographic token password for the PKCS11 device in the Cryptographic Token Password field. The password was previously set and is hardware-specific. This password is often called a user PIN in vendor documentation and tools.

     2. Select the Create new secondary key database file option and complete prompts for creating a new secondary key database.

     3. Click OK.