Cryptographic accelerator Questions and Answers

Provide feedback on the IBM HTTP Server forum on IBM developerWorks.

Table of contents

Cryptographic hardware FAQ

How can IBM HTTP Server be used with CoolThreads/Niagra/UltraSparc servers from Sun Microsystems?

See this whitepaper (alternate link) from Sun Microsystems for detailed analysis and administrative steps. Configuring RSA offload via the PKCS#11 interface is critical to achieve good SSL performance on this platform.

Threaded applications such as IBM HTTP Server may see a dramatic SSL handshake performance degradationwhen using the RSA offload capabilities of the Niagra platform. Customers encountering slow PKCS#11 performance should work with oracle to ensure they have all applicable fixes for multi-threaded applications using the PKCS#11 driver.

When the software token described in the whitepaper above is used, the Niagra PKCS#11 driver will also default to doing many other cryptographic operations in software instead of using the coprocessors. Information on disabling these mechanisms in the software-based driver are discussed in section 4 here (http://www.sun.com/bigadmin/features/articles/web_server_t1.jsp).

Some users have reported importing of existing keys is difficult in this environment. We recommend using Ikeyman to convert any pre-existing keys to PKCS12 format, then using the native Solaris tools (pk12util, pktool) to perform any interaction with the cryptographic token. One such report, accompanied with a recipe for using pre-existing (non self-signed) keuys is documented in this thread: http://www.ibm.com/developerworks/forums/thread.jspa?threadID=364420&tstart=0

What cryptographic hardware is supported with IBM HTTP Server?

Why does my PKCS11 token routinely get erased?

Consult your enterprise Linux vendor for an updated opencryptoki library to fix this truncation of the soft-token.

How can I tell if my PKCS11 token is ready to be used by IBM HTTP Server?

Detecting an improperly initialized cryptographic token

Note: all examples assume the first token is being used, so each pkcsconf invocation contains "-c 0".

Run the following command in a terminal:

$ pkcsconf -t -c 0| grep Flags

If the output matches any of the following patterns, your PKCS11 token is not usable by IHS because it has not been configured properly.

outputexplanationaction (see list below)
Flags: 0xnCnnnn USER_PIN_LOCKED and USER_PIN_TO_BE_CHANGED 3,4
Flags: 0xn8nnnn USER_PIN_TO_BE_CHANGED4
Flags: 0xn4nnnn USER_PIN_LOCKED3,4
Flags: 0xCnnnnn SO_PIN_LOCKED and SO_PIN_TO_BE_CHANGED1,2,3,4
Flags: 0x8nnnnn SO_PIN_TO_BE_CHANGED 2
Flags: 0x4nnnnn SO_PIN_LOCKED 1,2,3,4

For more information about the Flag values see this file

Solutions (make sure these complete succesfully)

  1. To correct SO_PIN_LOCKED, contact a system administrator and have them run: (Note: This may destroy corresponding personal certificates)
    pkcsconf -I -c 0
  2. To correct SO_PIN_TO_BE_CHANGED, change (set) the Security Officer PIN:
    pkcsconf -P -c 0
  3. To correct USER_PIN_LOCKED, contact a system administrator or initialize the user PIN (may destroy corresponding personal certificates):
    pkcsconf -u -c 0
  4. To correct USER_PIN_TO_BE_CHANGED, change (set) the user PIN:
    pkcsconf -p -c 0
    Note: Solution 2 uses a upper case 'P' and solution 4 uses an lower case 'p'.

An example of a properly configured token is:

Flags: 0x44D

Examples of improperly configured token is:

Why doesn't IHS 7.0 recognize the certificates stored on my cryptographic device?

If the mandatory configuration steps to use Ikeyman with IBM HTTP Server are not followed, personal certificates created/imported onto cryptographic devices will not be usable with the IBM HTTP Server runtime.

Note that it is never sufficient to just rename java/jre/lib/ext/gskikm.jar to any other filename in the java/jre/lib/ext/ directory.

If java/jre/lib/ext/gskikm.jar has been renamed properly, the Help/About menu in Ikeyman will report a version beginning with "7".

The symptom of creating a personal certificate without performing the configuration is the following error message for each handshake: SSL0227E: SSL Handshake Failed, Specified label could not be found in the key file

The Infocenter topic linked above also contains information about properly using Ikeyman without removing java/jre/lib/ext/gskikm.jar, by creating an external PKCS11 configuration file.

What cryptographic operations does IHS offload when configured with SSLPKCSDriver?

IHS offloads RSA cryptographic operations (assymetric operations) when configured with SSLPKCSDriver, if supported by the cryptographic hardware.

IHS 6.0.2.39, 6.1.0.29, 7.0.0.0 and later can be configured to offload symmetric crypto operations (e.g. DES, RC4, AES), if the crypgoraphic hardware supports it, with the following configuration in the SSLEnabled virtual host:

 
# Symmetric offload
SSLAttributeSet 417 549

Errors on z/Linux using cryptographic accelerator

Possibly symptoms include:

Causes

Cause #1: Mandatory environment setup for z/Linux crypto offload

See http://www-01.ibm.com/support/docview.wss?uid=swg21313367 for mandatory environemnt variables to be set for Ikeyman, gsk7capcimd, and the IHS runtime when crypto offload is used on z/Linux with GSKit 7.0.4.14 and later.

Cause #2: Invalid PIN on crypto token

During configuration using the pkcsconf tool, some error messages may not have been noticed and the "user PIN" may not have been set after being initialized. The PIN may also have been locked due to too many failing password attempts.

If ikeyman crashes due to this issue, the top of the javacore backtrace will look like this:

com.ibm.gsk.ikeyman.basic.CryptographicToken.c_BuildKeyLabelList(Native Method)

If the token had been properly setup once in the past, and already has a personal certificate, IHS will likely crash in the parent process:

[notice] seg fault or similar nasty error detected in the parent process

Solution

The user PIN must be changed/set (pkcsconf -p) after being initialized (pkcsconf -u). If the user PIN is locked due too many incorrect passwords, the token must be re-initialized (pkcsconf -I)

Cause #3: Crypto offload fails after SLES11 SP1?

Maintenance from Novell is required to use crypto offload on this OS after SP1. Contact Novell for a fix for bugzilla #643843 and #582774

Parent process crashes on z/Linux with crypto enabled

This is the result of a crypto token being uniitlized, or locked. See this topic.

Where can I get more information about setting up z/Linux crypto offload?

Supplemental data to collect for cryptographic token related errors

If a z/Linux crypto accelerator is being used, collect the following additional doc: