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

Enabling Cryptographic Devices for SSL
Applies to AIX Applies to Windows NT

Manage cryptographic keys and store them on cryptographic hardware to provide a highly secure architecture for secure online transactions. This capability greatly increases performance and security in a Web server using SSL.

Supported cryptographic devices include:

  • Rainbow Cryptoswift PCI with BSAFE 3.0 Interface (performs acceleration "100-600 TPS") - No key storage. This device Only supports acceleration; use with SSLAcceleratorDisable directive only.
  • nCipher nFast Accelerator with BHAPI plug-in under BSAFE 4.0 - This device is a pure accelerator and does not perform key storage. Requires either a SCSI or PCI-based nForce unit; use with SSLAcceleratorDisable directive only.
  • nCipher nForce Accelerator - Supports two different modes:
    • Accelerator mode: Uses the BHAPI/BSAFE interface. This mode only performs acceleration - no key storage.
    • Key stored accelerator mode: Uses the PKCS#11 interface. This mode performs acceleration and key storage, requiring either a SCSI or PCI-based nForce unit. Moving to nCipher nForce Accelerator 4.0 or higher is recommended for better performance.
  • IBM 4758 Model 023 with PKCS#11 Interface - This device performs key storage with acceleration, but it is not a pure accelerator.

The Rainbow Cryptoswift PCI, nCipher nFast Accelerator and nCipher nForce Accelerator without key storage, are for public key operations (RSA key decryption). Keys are not stored on the accelerator device, but are still stored in the .kdb file. Accelerator devices are used to 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 and nCipher Accelerators mainly incorporate faster performance (more concurrent secure transactions).

With the PKCS#11 protocol, RSA keys are stored on a cryptocard to ensure authentication. The IBM 4758 is not a pure accelerator because it performs key storage with acceleration. The nCipher nForce Accelerator can either perform just 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 that keys are completely inaccessible to the outside world and are never revealed in an unencrypted form because the key is stored on the hardware, providing enhanced key protection and authentication.

nCipher nForce Accelerator 4.0 and higher with PKCS11 key storage has a nonremovable option which improves performance by 30%. Contact nCipher Technical Support for instructions to turn on this feature.

Target Platforms
Applies to HP-UX
Applies to Solaris Applies to Windows NT

The Rainbow Cryptoswift Card is available on the following platforms:

  • HP
  • Solaris
  • Windows NT
Applies to Solaris
Applies to Windows NT 		The nCipher nFast Accelerator is available on the following platforms:
  • Solaris
  • Windows NT
Applies to Solaris
Applies to Windows NT

The nCipher nForce Accelerator device is available on the following platforms:

Accelerator mode-

  • Solaris
  • Windows NT
Applies to AIX
Applies to HP-UX
Applies to Linux
Applies to Solaris
Applies to Windows NT

Key storage accelerator mode-

  • AIX
  • HP
  • Linux
  • Solaris
  • Windows NT
Applies to AIX Applies to Windows NT

The IBM 4758 model 23 with PKCS#11 support is available on the following platforms:

  • AIX
  • Windows NT

To install Rainbow CryptoSwift and IBM 4758 devices, plug the cards into the server PCI slot and load up the driver. Installation of the nCipher accelerator boxes requires a SCSI card or PCI-based nForce unit.

The IBM 4758 requires the PKCS11 support software for the host machine and internal firmware. You will 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 are available for download from http://www.ibm.com/security/cryptocards/. From the download site, you need to obtain the PKCS#11 model 023 Version 2.3 software and the Version 2.30 PKCS#11 Installation manual.

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

The module for the PKCS11 device, the token (device) label, the key label of the key on the device, and the user PIN and password of the token need to pass to the GSKit for access to the key on the PKCS11 device. Note that the PKCS11 module is different for each platform and PKCS11 device. For the IBM 4758 card, the PKCS11 module is shipped with the bos.pkcs11 package on AIX, and with the PKCS11 software from the http://www.ibm.com/security/cryptocard download site for Windows NT. The PKCS11 module for the nCipher device should come with the package. The nCipher library is located in the $NFAST_HOME/toolkits/pkcs11 directory.

Below are the default locations of the PKCS11 modules for each PKCS11 device:

Applies to AIX
Applies to HP-UX
Applies to Linux
Applies to Solaris
Applies to Windows NT
  • nCipher:
    • AIX - /opt/nfast/toolkits/pkcs11/libcknfast.so
    • HPUX - /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
  • IBM4758:
    • AIX - /usr/lib/pkcs11/PKCS11_API.so
    • Windows NT - c:\pkcs11\bin\nt\cryptoki.dll
Applies to AIX

Initializing the IBM 4758 device on AIX

To initialize the IBM 4758 card on AIX, you must first obtain and install the bos.pkcs11 software. Note: The bos.pkcs11 software on the AIX 4.3.3 October and November 2000 Update CDs contains a forking problem. You can obtain the bos.pkcs11 package with the fix from the next AIX 4.3.3 Update CD, or from: Download AIX fixes. Select Download >AIX fixes > Simple Search > AIX Version 4 This package installs the PKCS11 module needed for SSLPKCSDriver directive discussed below.

After the PKCS11 software is installed, Change to the /usr/lib/pkcs11/methods directory:

  1. Run the pkcsconf -I -c <slot number of token> -S <security Officer(SO) pin> command to initialize the token. You are prompted to create a token label.

    Note: You can also view your slot number by issuing the pkcsconf -s command.

  2. Run the pkcsconf -t command. This command allows you to see the status of the token.
  3. If the status (flag value) of your token is 5, you need to initialize a user pin by running this command: pkcsconf -u -c <slot number of token>

    You are asked for your security officer pin, prompted and prompted again to enter a new user pin.

  4. If the status or flag values of your token is "D", after you run the pkcsconf -t command, your user pin is initialized and your card is ready to use.
Applies to Windows NT

Initializing the IBM 4758 device on Windows NT

To initialize the IBM 4758 card on Windows NT, you need to obtain the PKCS11 Model 023 Version 2.3 software for Windows NT from http://www.ibm.com/security/cryptocards/. If you want to use the sample configuration utility that installs with the PKCS11 software to initialize your card, you need to change to the location of the tokenm.mak and tokeni.mak files from your command line. These files are typically located in c:\pkcs11\src\samples\tokens. If you are using the VisualAge C++ for Windows compiler, run the command line for the directory containing the tokenm.mak and tokeni.mak files. If you are using Microsoft Visual C++ compiler, from the command line for the directory containing the tokenm.mak and tokeni.mak files, type nmake tokenm and press Enter. Nmake compiles the sample program and builds the tok_obj.exe configuration utility to initialize the card.

Note: Make sure the cryptoki.dll module is in your path.
Applies to Windows NT

Initializing PKCS11 Token on Windows NT

To initialize the PKCS11 token on Windows NT:

  1. Change to the directory in which to_obj.exe resides. This directory is typically: c:/pkcs11/src/samples/tokens
  2. Type tok_obj.exe and press Enter.
  3. A list of options displays. Choose option 5 to initialize the token and option 6, to set a user pin.

    Note: A valid user pin is between four and eight characters.

Using IKEYMAN to Store Keys on a PKCS11 device
Applies to AIX
Applies to HP-UX
Applies to Linux
Applies to Solaris
Applies to windows NT

To store keys on your PKCS11 device, you need to provide an ikmuser.properties file for IKEYMAN. To provide this file:
  1. Copy the ikmuser.sample file that is shipped with the IBM HTTP Server (IHS) and GsKit, which is typically installed in:
    • 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. Note: Cryptographic token may not work if the ikmuser.properties file is not 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:
      • Windows NT - C:\nfast\toolkits\pkcs11\cknfast.dll
      • AIX - /opt/nfast/toolkits/pkcs11/libcknfast.so
      • SUN - /opt/nfast/toolkits/pkcs11/libcknfast.so
      • HPUX - /opt/nfast/toolkits/pkcs11/libcknfast.sl
      • Linux - /opt/nfast/toolkits/pkcs11/libcknfast.so
    • IBM 4758:
      • AIX - /usr/lib/pkcs11/PKCS11_API.so
      • Windows NT - c:\pkcs\bin\NT\cryptoki.dll

    If the cryptoki.dll file is in your path, specify only the name of the .dll file (PKCS11 module).
    DEFAULT_CRYPTOGRAPHIC_MODULE=cryptoki.dll
    The module is normally installed on your system when you install the software for your PKCS11 device.

  3. Save the ikmuser.properties file

Now, as long as the ikmuser.properties file is in the classes directory, whenever you bring up IKEYMAN, the contents of the ikmuser.properties file are read. When IKEYMAN comes up, the IBM Key Management window has an additional menu item called Cryptographic Token.

  1. Select 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, check 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, check Create new secondary key database file, specify CMS key database file, the file name, and location. If not, make sure there is not a check mark by this option. Click the OK button.
  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 to store on the IBM 4758 card. The only difference is that instead of using Key Database>Open, you use Cryptographic Token >Open.

    6. Note: With the IBM HTTP Server, you must specify a keyfile to perform encryption. If you are using PKCS11 devices, this keyfile should hold your signer certificates for your personal certificate, which are located on the PKCS11 device.

Configuring the IBM HTTP Server to use Accelerator Devices

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

Configuring the IBM HTTP Server to use Accelerator and Key Storage Devices
Applies to UNIX Applies to Windows NT

If you want the IBM HTTP Server to use the nCipher nForce Accelerator Device with the key storage mode, you need to:

  1. Stash the password to your PKCS11 device in a file by using the sslstash command. On UNIX, this command is located in the bin directory of IHS. On windows NT, this command is located in the root directory of IHS.
    • Usage: sslstash -c <file><function><Password>
    • -c: Create a new stash file. If not specified, an existing file is updated.
    • File: Fully qualified name of the file to create or update
    • Function: Function for which the password is used. Valid values are crl, or crypto
    • Password: The password to stash.
  2. Place the following directives in your configuration file:
    • SSLPKCSDriver <fully qualified path of module used to access PKCS11 device>

      If the PKCS11 module is in your path, specify the name of the PKCS11 module. See SSLPKCSDriver directive, for the default locations of the PKCS11 module for each PKCS11 device.

    • SSLServerCert <token label:keylabel of certificate on PKCS11 device>
    • SSLStashfile <fully qualified path of the file containing the password to open the PKCS11 device>
    • SSLKeyfile <fully qualified path to keyfile>

Configuring the IBM HTTP Server to Use Key Storage Devices

If you want the IBM HTTP Server to use the PKCS11 interface (key storage) without acceleration mode, configure the following:

  1. SSLAcceleratorDisable
  2. Stash your password to PKCS11 device:
    • Usage: sslstash [-c] <file> <function> <password>
    • -c: Create a new stash file. If not specified, an existing stash file is updated
    • File: Fully qualified name of the file to create or update
    • Function: Function for which the password is used. Valid values are crl or crypto
    • Password: The password to stash.
  3. Place the following directives in your configuration file:
    • SSLPKCSDriver <fully qualified name of the PKCS11 module used to access PKCS11 device>

      If the PKCS11 module is in your path, specify only this filename. See SSLPKCSDriver directive, for the default locations of the PKCS11 module for each PKCS11 device.

    • SSLServerCert <token label:keylabel of certificate on PKCS11 device>
    • SSLStashfile <fully qualified path to the file containing the password to open the PKCS11 device>
    • SSLKeyfile <fully qualified path to keyfile>
 
Related information...
     (Back to Top)