Configure WebSEAL for cryptographic hardware

Perform the following steps to configure WebSEAL for cryptographic hardware:

Parent topic: Cryptographic hardware for encryption and key storage

Install the cryptographic card and device driver

Follow the instructions provided by the specific vendor to install the cryptographic card and its device driver (with PKCS#11) for the specific cryptographic hardware we are using. This procedure involves shutting down and restarting the computer machine.

Create a token device label and password to store WebSEAL keys

In the context of cryptographic hardware and the associated device drivers, a token is a logical device that acts as a "container" for storing key, data, and certificate objects. Key objects can include public keys and private keys. When configuring a cryptographic card to perform key storage (using the PKCS#11 interface), we must define one or more tokens (or "containers") that store keys for different situations.

When configuring a cryptographic card to perform key storage tasks for WebSEAL (GSKit), specify a token label (and password) representing the token device that stores the WebSEAL public/private key pair. WebSEAL sends the public key in the server-side certificate that it uses to authenticate itself to any client.

Use the instructions provided with the installed cryptographic hardware to create a label for the token device that stores the WebSEAL key.

For example:

Configure iKeyman to use the PKCS#11 module

The iKeyman utility is packaged with the Java Runtime Environment version 6.0 or later. We must configure iKeyman for the PKCS#11 device module (shared library) of the installed cryptographic hardware device. The iKeyman utility uses this module to understand the following components:

Steps

  1. Locate the java.security file in the directory location that is applicable to the environment:

      Solaris:
      User-defined location during Java installation. For example, /usr/java.

      Linux:
      /opt/ibm/java-s390x-60/jre/lib/security

      AIX:
      /usr/java6_64/jre/lib/security

      Windows:
      C:\Program Files\IBM\Java60\jre\lib\security

  2. Edit this file by adding a line to include the IBMPKCS11Impl provider in the provider list. That is, com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl. For example:

      # # List of providers and their preference orders: # security.provider.1=com.ibm.crypto.provider.IBMJCE security.provider.2=com.ibm.jsse.IBMJSSEProvider security.provider.3=com.ibm.jsse2.IBMJSSEProvider2 security.provider.4=com.ibm.security.jgss.IBMJGSSProvider security.provider.5=com.ibm.security.cert.IBMCertPath security.provider.6=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl security.provider.7=com.ibm.security.cmskeystore.CMSProvider security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGO

  3. Save these updates.

Results

When the shared library is configured, the iKeyman utility includes a new menu option: PKCS11Direct. Now we can use iKeyman to create, store, and manipulate keys for WebSEAL on the cryptographic hardware.

Use iKeyman to open the WebSEAL token device

  1. Start the iKeyman utility that is packaged with the Java Runtime Environment version 6.0 or later.

  2. Select Key Database File, then Open.

    A separate Open dialog box displays.

  3. In the Open dialog window, select Cryptographic Tokens from the Key database type menu.

  4. If we have the cryptographic token specified in the java.security file, the dialog box contains both the path and the library. If we do not see the library, we can use the Browse menu option. Click OK when this step is complete.

  5. Additionally, if we want to open an existing secondary key database (for key data not stored on the cryptographic hardware-such as CA root certificates), check Open Existing Key Database.

  6. Browse for and select the default WebSEAL key database:

    UNIX or Linux

      /var/pdweb/www-instance/certs/pdsrv.kdb

    >Windows

      C:\Program Files\Tivoli\pdweb\www-instance\certs\pdsrv.kdb

  7. Click OK.

    The Token Password dialogue box displays.

  8. Enter the default password pdsrv. Click OK.

Results

The main iKeyman window returns.

Request and store the WebSEAL server certificate

Steps

  1. Follow instructions in the IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide to request a secure, signed digital certificate for WebSEAL from a Certificate Authority (CA).

  2. Follow instructions in the IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide to receive the WebSEAL certificate from the CA and store it in a key database. When performing this procedure, select the token device representing the cryptographic hardware as the storage location for the certificate.

Results

When it is stored on the token device, the key (certificate) appears (for example) as:websealtoken:webseal The WebSEAL key is stored on the cryptographic hardware and assigned to the token device labeled "websealtoken".

Configure WebSEAL and GSKit to use the PKCS#11 shared library

Steps

  1. In the WebSEAL configuration file, specify the names of the token label and password under the [ssl] stanza:

    For this example:

      [ssl] pkcs11-token-label = websealtoken pkcs11-token-pwd = secret

  2. (For IBM 4960 only) In the WebSEAL configuration file, modify the WebSEAL instance UNIX group account configuration to specify group pkcs11. This allows WebSEAL to access the PKCS token:

Modify the WebSEAL server certificate label

Configure WebSEAL to use this new hardware-based key rather than the default key in its communications with browser clients. Modify the webseal-cert-keyfile-label stanza entry in the [ssl] stanza of the WebSEAL configuration file to designate the new key label.

For this example:

Configure WebSEAL for PKCS#11 symmetric algorithms

We can configure WebSEAL to support the GSKit option for using PKCS#11 for symmetric algorithms.

To enable PKCS#11 for symmetric algorithms, uncomment the pkcs11-symmetric-cipher-support stanza entry in the [ssl] stanza of the WebSEAL configuration file and set the value to "yes". For example:

To disable support for symmetric algorithms, uncomment the pkcs11-symmetric-cipher-support stanza entry in the [ssl] stanza of the WebSEAL configuration file and set the value to "no". For example:

The PKCS#11 symmetric cipher support does not include removable devices. If a removable device is encountered, it is ignored even if the support has been requested. Additionally, not all devices support symmetric ciphers. Refer to the appropriate vendor documentation for the device we are using.

Restart WebSEAL

  1. Restart WebSEAL for all cryptographic hardware configuration to take effect.
  2. Verify that WebSEAL is using the cryptographic hardware by examining entries contained in the msg_webseald.log file.