Provide feedback on the IBM HTTP Server forum on IBM developerWorks.
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
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.
output | explanation | action (see list below) |
---|---|---|
Flags: 0xnCnnnn | USER_PIN_LOCKED and USER_PIN_TO_BE_CHANGED | 3,4 |
Flags: 0xn8nnnn | USER_PIN_TO_BE_CHANGED | 4 |
Flags: 0xn4nnnn | USER_PIN_LOCKED | 3,4 |
Flags: 0xCnnnnn | SO_PIN_LOCKED and SO_PIN_TO_BE_CHANGED | 1,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)
pkcsconf -I -c 0
pkcsconf -P -c 0
pkcsconf -u -c 0
pkcsconf -p -c 0
An example of a properly configured token is:
Flags: 0x44D
Examples of improperly configured token is:
Flags: 0x8044D
Flags: 0xC044D
Flags: 0xA044D
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.
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 SSLEnable
d virtual host:
# Symmetric offload SSLAttributeSet 417 549
Possibly symptoms include:
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.
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
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
)
Maintenance from Novell is required to use crypto offload on this OS after SP1. Contact Novell for a fix for bugzilla #643843 and #582774
Configuring WebSphere V7.0 and IBM HTTP Server V7.0 to use Cryptographic Hardware for SSL Acceleration on Linux on IBM System z has some z/Linux info for IHS and WebSphere Application Server, with Ikeyman v7 oriented instructions.
2006 redbook on using z/Linux crytographic hardware (Ikeyman v7)
"Using IKEYMAN Version 8 to store keys on a PKCS11 device" has PKCS11 information for Ikeyman v8 and later (as used by default with IHS v7 and later).
Mandatory configuration changes for GSkit 7.0.4.x on z/Linux
If a z/Linux crypto accelerator is being used, collect the following additional doc: