Configuring WebSEAL for cryptographic hardware

Edit online

About this task

Perform the following steps to configure WebSEAL for cryptographic hardware:

1. Install the cryptographic card and device driver

Edit online

About this task

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 you are using. This procedure involves shutting down and restarting the computer machine.

2. Create a token device label and password to store WebSEAL keys

Edit online

About this task

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 you configure a cryptographic card to perform key storage (using the PKCS#11 interface), you must define one or more tokens (or "containers") that store keys for different situations.

When you configure a cryptographic card to perform key storage tasks for WebSEAL (GSKit), you must specify a token label (and password) that represents 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:

token = websealtoken
password = secret

3. Configure iKeyman to use the PKCS#11 module

Edit online

About this task

The iKeyman utility is packaged with the Java™ Runtime Environment version 6.0 or later. You 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:
  • The WebSEAL token label for the hardware device.
  • The password or PIN for the token.
  • The key label of any WebSEAL key stored on the device.

Procedure

  1. Locate the java.security file in the directory location that is applicable to your 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 you can use iKeyman to create, store, and manipulate keys for WebSEAL on the cryptographic hardware.

4. Use iKeyman to open the WebSEAL token device

Edit online

Procedure

  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 you have the cryptographic token specified in the java.security file, the dialog box contains both the path and the library. If you do not see the library, you can use the Browse menu option. Click OK when this step is complete.
  5. Additionally, if you 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.kdbWindowsC:\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.

5. Request and store the WebSEAL server certificate

Edit online

Procedure

  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:websealThe WebSEAL key is stored on the cryptographic hardware and assigned to the token device labeled "websealtoken".

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

Edit online

Procedure

  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:
    [server]
unix-group = pkcs11

7. Modify the WebSEAL server certificate label

Edit online

About this task

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.

[ssl]
webseal-cert-keyfile-label = <token-name>:<key-label>

For this example:

[ssl]
webseal-cert-keyfile-label = websealtoken:webseal

8. Configure WebSEAL for PKCS#11 symmetric algorithms

Edit online

About this task

You 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:

[ssl]
pkcs11-symmetric-cipher-support = yes

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:

[ssl]
pkcs11-symmetric-cipher-support = no

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 you are using.

9. Restart WebSEAL

Edit online

Procedure

  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.