Enabling Cryptographic Devices: IBM HTTP Server
System Administration IBM HTTP Server documentation

Enabling cryptographic hardware for the Secure Sockets Layer
Pertains to AIX users Pertains to Windows NT users Pertains to Windows 2000 users

This section provides information on enabling cryptographic hardware for the Secure Sockets Layer (SSL). Links to related topics appear at the end of this section.
 

Managing cryptographic keys and storing them on cryptographic hardware provides a highly secure architecture for secure online transactions. This capability greatly increases performance and security in a Web server using SSL.

Note: For this example, key storage devices are defined as those devices where the key is only visible on the hardware device.

The following cryptographic devices have been tested with IBM HTTP Server:

Device Key Storage? Acceleration Support? Notes Notes
Rainbow Cryptoswift PCI with BSAFE Interface Model No Yes Use with SSLAcceleratorDisable directive only. Supported on HP, Solaris and Windows NT operating systems.
nCipher nFast Accelerator with BHAPI plug-in under BSAFE 4.0 No Pure accelerator Requires either a SCSI or PCI-based nForce unit; use with SSLAcceleratorDisable directive only. Supported on Solaris and Windows NT operating systems.
nCipher nForce Accelerator, accelerator mode No Yes Uses the BHAPI and BSAFE interface. Supported on Solaris and Windows NT operating systems.
nCipher nForce Accelerator, Key stored accelerator mode Yes Yes Uses the PKCS#11 interface. Requires either a SCSI, or PCI-based nForce unit. Move to nCipher nForce Accelerator V4.0 or later for better performance. Supported on AIX, HP, Linux, Solaris and Windows NT operating systems.
IBM 4758 Model 002/023 with PKCS#11 Interface Yes No Uses the PKCS11 interface. Supported on AIX and Windows NT operating systems.
 
Pertains to AIX users

Support for the following adapters has been tested with later WebSphere Application Server releases:

Device Key Storage? Acceleration Support? Notes Notes
Rainbow Cryptoswift PCI with BSAFE Interface Model CS/200 and CS/600 No Yes Supported on the AIX operating system.
IBM e-business Cryptographic Accelerator No Yes Uses the PKCS11 interface. Because this device uses the PKCS11 interface, the SSLAcceleratorDisable directive does not apply to this device. Supported on the AIX operating system.

Use the Rainbow Cryptoswift, IBM e-business Cryptographic Accelerator, nCipher nFast Accelerator and nCipher nForce Accelerator, for public key operations, and RSA key decryption. These devices store keys on your hard drive. Accelerator devices speed up the public key cryptographic functions of SSL, freeing up your server processor, which increases server throughput and shortens wait time. The Rainbow Cryptoswift, IBM e-business Cryptographic Accelerator, and nCipher accelerators incorporate faster performance and more concurrent secure transactions.

The PKCS#11 protocol either stores RSA keys on cryptographic hardware, or encrypts keys using cryptographic hardware to ensure protection. The nCipher nForce Accelerator can either perform acceleration, or it can perform both acceleration and key storage with PKCS#11 support. The IBM 4758 and nCipher nForce Accelerator with PKCS#11 support ensures inaccessible keys to the outside world. This support never reveals keys in an unencrypted form because the key is either encrypted by the hardware, or stored on the hardware.

nCipher nForce Accelerator V4.0 and later using PKCS11 key storage, has a nonremovable option which can noticeably improve performance. Contact nCipher Technical Support for instructions to turn on this feature.

Getting started

The IBM 4758 requires the PKCS11 support software for the host machine and internal firmware. You also need the manual which explains software installation and card coprocessor microcode loading. The support software and manual do not come with the IBM 4758 card, but you can download them from the following Web site: http://www-3.ibm.com/security/cryptocards/index.shtml. From the download site, obtain the PKCS#11 Model 002/023 software and the PKCS#11 Installation manual.

After installing the support software on your machine and loading the microcode on the IBM 4758, initialize the card.

Configure the IBM HTTP Server to pass the module for the PKCS11 device, the token label, the key label of the key created by the PKCS11 device, and the user PIN password of the token to the GSKit for access to the key for the PKCS11 device by modifying the configuration file. The PKCS11 module differs for each platform and PKCS11 device. For the IBM hardware cryptographic devices - IBM 4758 card, available on AIX and Windows operating systems, and IBM e-business Cryptographic Accelerator, the PKCS11 module ships with the bos.pkcs11 package on AIX.

Install the devices.pci.14109f00 device for the IBM 4758 and the devices.pci.1410e601 device for the IBM e-business Cryptographic Accelerator. AIX V4.3.3 maintenance level09 is recommended when using the IBM e-business Cryptographic Accelerator.

For the IBM 4758 on Windows, the PKCS11 module comes with the PKCS11 software available for download from: http://www.ibm.com/security/cryptocards/html/ordersoftware.shtml. For nCipher, the PKCS11 module ships with nCipher software and is located in the $NFAST_HOME/toolkits/pkcs11 directory.

The default locations of the PKCS11 modules for each PKCS11 device follow:

Pertains to AIX users
Pertains to HP-UX users
Pertains to Linux users
Pertains to Solaris users
Pertains to Windows NT users
Pertains to Windows 2000 users
  • nCipher:
    • AIX - /opt/nfast/toolkits/pkcs11/libcknfast.so
    • HP-UX - /opt/nfast/toolkits/pkcs11/libcknfast.sl
    • Linux - /opt/nfast/toolkits/pkcs11/libcknfast.so
    • SUN - /opt/nfast//toolkits/pkcs11/libcknfast.so
    • Windows NT - C:\nfast\toolkits\pkcs11\cknfast.dll
  • IBM 4758:
    • AIX - /usr/lib/pkcs11/PKCS11_API.so
    • Windows NT - $PKCS11_HOME\bin\nt\cryptoki.dll
  • IBM e-business Cryptographic Accelerator:
    • AIX - /usr/lib/pkcs11/PKCS11_API.so
Pertains to AIX users

Initializing IBM cryptographic hardware (IBM 4758 and IBM e-business Cryptographic Accelerator) on the AIX operating system

To initialize the IBM cryptographic hardware (IBM 4758 and IBM e-business Cryptographic Accelerator) on AIX, obtain and install the bos.pkcs11 software. Tip: Obtain the most recent bos.pkcs11 package from: Download AIX fixes. Click Download > AIX fixes > Simple Search > AIX Version 4. This package installs the PKCS11 module needed for the SSLPKCSDriver directive discussed below. You also need the devices.pci.1410e601 device for the IBM e-business Cryptographic Accelerator and the devices.pci.14109f00 and devices.pci.14109f00 for the IBM 4758.

After you install the PKCS11 software, initialize your device. You can access the Manage the PKCS11 subsystem panel from Smitty to initialize your PKCS11 device. To initialize your token:

  1. Select Initialize your token
  2. Set a security officer and User PIN, if not already set
  3. Initialize your user PIN. See Chapter 5: Token Initialization from the PKCS11 manual for more detailed information.
Pertains to Windows NT users Pertains to Windows 2000 users

Initializing IBM tokens on Windows operating systems

To initialize the IBM 4758 card on the Windows NT and Windows 2000 operating systems, obtain the PKCS11 software for these operating systems from http://www-3.ibm.com/security/cryptocards/html/ordersoftware.shtml.

You can use the TOKUTIL.EXE utility that installs with the PKCS11 software to initialize your card on Windows operating systems.

Refer to Chapter 5: Token Initialization from the PKCS11 for more details.

Tip: Make sure you have the cryptoki.dll module in your path.

Using IKEYMAN to store keys on a PKCS11 device
Pertains to AIX users
Pertains to HP-UX users
Pertains to Linux users
Pertains to Solaris users
Pertains to Windows NT users
Pertains to Windows 2000 users

To create keys for your PKCS11 device, provide an ikmuser.properties file for IKEYMAN. To provide this file:
  1. Copy the ikmuser.sample file that ships with the IBM HTTP Server and GSKit, typically installed in the following directories:
    • AIX = /usr/opt/ibm/gskkm/classes
    • HP = /opt/ibm/gsk5/classes
    • Linux = /usr/local/ibm/gsk5/classes
    • Solaris = /opt/ibm/gsk5/classes
    • Windows NT = C:\Program Files\ibm\gsk5\classes
    to a file called ikmuser.properties in the classes directory. Tip: Cryptographic token may not work if the ikmuser.properties file does not reside in the classes directory.
  2. Edit the ikmuser.properties file to set the DEFAULT_CRYPTOGRAPHIC_MODULE property to the name of the module managing your PKCS11 device. For example:
    DEFAULT_CRYPTOGRAPHIC_MODULE=C:\pkcs11\bin\NT\cryptoki.dll

    • nCipher:
      • AIX - /opt/nfast/toolkits/pkcs11/libcknfast.so
      • HP-UX - /opt/nfast/toolkits/pkcs11/libcknfast.sl
      • Linux - /opt/nfast/toolkits/pkcs11/libcknfast.so
      • SUN - /opt/nfast/toolkits/pkcs11/libcknfast.so
      • Windows NT - C:\nfast\toolkits\pkcs11\cknfast.dll
    • IBM 4758:
      • AIX - /usr/lib/pkcs11/PKCS11_API.so
      • Windows NT - $PKCS11_HOME\bin\NT\cryptoki.dll
    • IBM e-business Cryptographic Accelerator:
      • AIX - /usr/lib/pkcs11/PKCS11_API.so

    The module is normally installed on your system when you install the software for your PKCS11 device.

  3. Save the ikmuser.properties file

As long as you have the ikmuser.properties file located in the classes directory, the device reads the ikmuser.properties file contents, whenever you bring up IKEYMAN. When IKEYMAN comes up, the IBM Key Management window has an additional menu item called cryptographic token.

  1. Click Cryptographic Token from your IBM Key Management window.
  2. Click Open.
  3. The Open Cryptographic Token window displays. Select your cryptographic token label and enter the user pin and password you specified when initializing your token with the configuration utility.
  4. If you want to open an existing secondary key database, select Open an existing secondary key database file, specify a file name, and location. If not, disable this function by removing the check mark. If you want to create a new secondary key database file, select Create new secondary key database file, specify a conversational monitor system (CMS) key database file, the file name, and location. If not, make sure to clear the check mark by this option. Click OK.
  5. Proceed with the steps as if you had opened a key database. You can continue with the same steps to create a self-signed certificate, or add a new digital-signed certificate. Instead of using Key Database > Open, use Cryptographic Token > Open.

    6. Tip: With the IBM HTTP Server, you must specify a key file to perform encryption. If you use PKCS11 devices, this key file should hold your signer certificates for your personal certificate, created using PKCS11 device.

Configuring the IBM HTTP Server to use nCipher and Rainbow accelerator devices

The IBM HTTP Server enables nCipher and Rainbow accelerator devices by default. To disable your accelerator device, add the following directive to your configuration file: SSLAcceleratorDisable

Configuring the IBM HTTP Server to use PKCS11 devices

Note: When using the IBM e-business Cryptographic Accelerator, or the IBM 4758, the user ID under which the Web server runs must be a member of the PKCS11 group. You can create the PKCS11 group by installing the bos.pkcs11 package or its updates. Change the Group directive in the configuration file to: group pkcs11.

If you want the IBM HTTP Server to use the PKCS11 interface, configure the following:

  1. Stash your password to the PKCS11 device:

    Syntax: sslstash [-c] <file> <function> <password>

    2. where:
    • -c: Creates a new stash file. If not specified, an existing stash file updates
    • file: Represents a fully qualified name of the file to create or update
    • function: Represents function for which the server uses the password. Valid values include crl or crypto
    • password: Indicates the password to stash.
  2. Place the following directives in your configuration file:
    • SSLPKCSDriver <fully qualified name of the PKCS11 driver used to access PKCS11 device>

      See SSLPKCSDriver directive, for the default locations of the PKCS11 module for each PKCS11 device.

    • SSLServerCert <token label:key label of certificate on PKCS11 device>
    • SSLStashfile <fully qualified path to the file containing the password for the PKCS11 device>
    • Keyfile <fully qualified path to key file with signer certificates>
 
Finding related information
     (Back to the top)