Provide feedback on the IBM HTTP Server forum on IBM developerWorks.
To satisfy the assymetric offload only requirement when using this card with IHS, use the following stanza in the same context as
SSLPKCSDriver
:
# Disable symmetric cipher offload for 4765 SSLAttributeSet 417 550 # Disable digest offload for 4765 SSLAttributeSet 417 552
At least APAR IV75204/IV76220/IV76279 and IV76225/IV75996/IV76280 is needed to use this adapter with IHS.
The following filesets are required:
Summary of other requirements:
cryptstat Crypt0
to confirm
RSA is being offloaded. If no offload is occuring, one item to check is that the Y4 adapter
shows as "active" rather than "available" in p11admin.
Ikeyman cannot create SHA2 based certificates or CSR's while using a 4765, because the 4765 does not support
some SHA2 algorithms. You must use gskcapicmd
from GSKit 8.0.50.44 or later.
Some example command-line invocations follow:
IHSROOT=/opt/IHS TOKENLABEL=token1 PKCS11_PASS=1234 SECONDARY_PASS=WebAS # List tokens $IHSROOT/bin/gskcapicmd -keydb -list -crypto /usr/lib/pkcs11/ibm_pkcs11_64.so -pw $PKCS11_PASS # List certs $IHSROOT/bin/gskcapicmd -cert -list -crypto /usr/lib/pkcs11/ibm_pkcs11_64.so -tokenlabel "$TOKENLABEL" -pw $PKCS11_PASS # Add PEM-encoded CA certificate to secondary KDB. Obtained from the CA. $IHSROOT/bin/gskcapicmd -cert -add -db $IHSROOT/conf/secondary.kdb -pw $SECONDARY_PASS \ -label sha2-ca -file /tmp/cacert.pem -trust enable # Create certificate request (CSR) $IHSROOT/bin/gskcapicmd -certreq -create -crypto /usr/lib/pkcs11/ibm_pkcs11_64.so -pw $PKCS11_PASS -dn "cn=`hostname`" \ -size 2048 -sigalg SHA256WithRSA -secondarydb $IHSROOT/conf/secondary.kdb -secondarydbpw $SECONDARY_PASS \ -tokenlabel "$TOKENLABEL" -label sha2 -file /tmp/certreq.cer # Receive PEM-encoded signedcertificate from CA $IHSROOT/bin/gskcapicmd -cert -receive -crypto /usr/lib/pkcs11/ibm_pkcs11_64.so \ -tokenlabel "$TOKENLABEL" -pw $PKCS11_PASS -secondarydb $IHSROOT/conf/secondary.kdb -secondarydbpw $SECONDARY_PASS \ -file /tmp/certreq.cer.cer
Check the *.cfg path specified in java.security to ensure the file is present and readable, as an invalid path will cause the PKCS11Config setting to be suppressed. The added entry looks like this:
security.provider.13=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl /opt/crypto/pkcs11.cfg
In the "pkcs11.cfg" referenced from java.security, An invalid token name will NOT suppress "PKCS11Config", but it also won't work later.
In the "pkcs11.cfg", if the path to the PKCS11 library is invalid, the "PKCS11Config" will be suppressed.
In the "pkcs11.cfg", if the PKCS11 library is not loadable by the OS (dependencies, wrong architecture compared to JRE), the "PKCS11Config" will be suppressed.
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.
If your problem is with the runtime recognizing your token (e.g. SSL0154E), add the proper LoadFile or LD_PRELOAD entry as suggested here.
libpath=
in your
*.cfg file.
com.ibm.gsk.ikeyman.error.KeyManagerException: com.ibm.pkcs11.PKCS11Exception: Invalid dll name /opt/IBM
This information/configuration is deprecated and preserved for historical purposes only. Modern SPARC systems offer CPU instructions that can be used to accelerate SSL without complicated PKCS11 configuration. See #solcpuins.
Information on configuring this platforms crypto acceleration with IHS used to be available at the following URLs, but have not been available for quite some time.
Configuring RSA offload via the PKCS#11 interface is critical to achieve good SSL performance on this platform prior to T4/T5/M6/M7 hardware levels
Under some configurations, 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 concurrent access to the PKCS#11 driver (and to confirm that hardware offload is being used).
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 http://www.oracle.com/technetwork/systems/articles/web-server-t1-jsp-141041.html
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) keys is documented in this thread: http://www.ibm.com/developerworks/forums/thread.jspa?threadID=364420&tstart=0
A number of users have reported that while pktool appears to work for importing an existing certificate, they don't actually work unless pk12util is used.
IHS has not been tested with KSSL. KSSL is a kernel-level SSL proxy on Solaris that can exploit Niagra cryptographic accelerators. If you configure KSSL, you don't configure IHS for SSL at all and IHS is not aware of any SSL parameters being used.
Questions about configuring KSSL should be directed to Oracle. If you're following instructions for Apache, convert your CMS KeyFile (*.kdb) into PKCS12 using the GSKit tools then extract the private key and certificate files from the PKCS12.
SSLPKCSDriver
Note: all examples assume the first token is being used, so each pkcsconf invocation contains "-c 0".
('pkcsconf'
is not available on all unix systems. For AIX, refer to the
AIX crypto tools section. and
use the referenced documentation to determine equivalent commands that can be used.)
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
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 cryptographic hardware supports it, with the following configuration in the SSLEnable
d virtual host:
# Symmetric offload SSLAttributeSet 417 549
To confirm offload in your IHS/PLG environment: * restart IHS (clear Plugin connection pool) * z/Linux: note the value in /proc/driver/z90crypt Per-device successfully completed request counts 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 0000006B 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 (On Solaris, use kstat -n ncp0 | grep rsa. On AIX, check cryptstat Crypt0) * Send a request through IHS with SSL that will hit your Application Server (curl -vk https://localhost/context-root/foo.jsp) * z/Linux: The number in /proc/driver/z90crypt should now jump by 1 if either IHS or Plugin are using z90crypt acceleration or by 2 if both are. Per-device successfully completed request counts 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 000000000000006C 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 (On Solaris, use kstat -n ncp0 | grep rsa. On AIX, check cryptstat Crypt0) * If the number is not right, make sure there were no SSL initialization errors during Plugin startup. Optionally disable the HTTP transport in plugin-cfg.xml to make sure SSL is occuring. * To test subsequently with backend connections, you must restart IHS so you can be sure the Plugin does not have a cached SSL connection (No handshake required, so no increase in RSA acceleration count).
Possible 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.
This (LD_PRELOAD, LoadFile) applies to GSkit v8 in IHS v8 (and gsk8capicmd/gskcapicmd) and later as well.
CTGSK3026W The key file "pkcs11" does not exist or cannot be read. CTGSK2137W The label does not exist on the PKCS#11 device.
pkcsconf
tool on Linux),
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
The "User" directive must be a member of the pkcs11 group, and the pkcsslotd daemon must be started.
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
The 'pksconf'
utility referred to at various places within this document is not available on AIX systems.
However, there are PKCS11 crypto utilities (p11km & p11admin
) that are available (believed to have been introduced in AIX 6.1, technology level 4).
You can refer to the Tools subsection of :
Public Key Cryptography Standards #11 (AIX 7.1 Knowledge Center)
for detailed info.
Here is a summary description of the tools:
Additionally, ikeyman and gskcapicmd can create keys and certificates via generic PKCS11 interfaces.
If a crypto accelerator is being used, collect the following doc:
bin/gskcapicmd -keydb -list -crypto ...
and
bin/gskcapicmd -cert -list -crypto ... -tokenlabel ...
LoadFile
or LD_PRELOAD added setup in the environment prior to launching IHS.
pkcsconf -itsm
' as root (to display the PKCS11, token and slot info plus the mechanism list).