Configuring IBM HTTP server SSL support

IBM HTTP server (IHS) maintains a file where all its configuration is stored.

The configuration file for IHS has the following default path:

/opt/IBM/HTTPServer/conf/httpd.conf

Any SSL configurations need to go into this file. The following example SSL definition supports the Transport Security Layer (TLS) protocol and IBM® System z® cryptographic features, where TLS is the successor for the SSL.

# Example SSL(TLS) configuration 
# 
# required due to GSKit8 library problem
LoadFile /usr/lib64/libcrypto.so 
# 
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so 
Listen 443 
<VirtualHost wasnode1.net:443> 
ServerName wasnode1.net 
SSLEnable 
SSLProtocolDisable SSLv2 
SSLProtocolDisable SSLv3 
# cipher suite TLS_RSA_WITH_AES_256_CBC_SHA(35b) 
# remove all ciphers first 
SSLCipherSpec ALL NONE 
SSLCipherSpec ALL +TLS_RSA_WITH_AES_256_CBC_SHA 
# symmetric offload (older GSKit versions)  
# SSLAttributeSet 417 549  
</VirtualHost>
# PKCS#11 configuration 
KeyFile /opt/IBM/HTTPServer/ssl/key.kdb 
SSLServerCert IBMICATOK:ihscert
SSLStashfile /opt/IBM/HTTPServer/ssl/ibmicatok.sth 
SSLPKCSDriver /usr/lib/pkcs11/PKCS11_API.so64 
SSLDisable 
SSLCachePortFilename /opt/IBM/HTTPServer/logs/siddport 
# End of SSL configuration

For more details on IHS SSL directives see IBM WebSphere Application Server (WAS) Version 8 information center:

https://www.ibm.com/docs/en/was/8.5.5?topic=websphere-application-server-distributed-operating-systems-version-855

IBM HTTP Server for Websphere Application Server, Version 8.0 > Reference > Settings > SSL directives

Explanation of some SSL httpd.conf directives

LoadFile /usr/lib64/libcrypto.so

This statement needs to be added due to conflicting GSKit8 and openSSL libraries. The problem currently occurs on a Novell SLES11 SP2 distribution with WAS8 (GSKit 8). It has also been observed for older distributions and IHS GSKit versions (for example using GSKit 7.0.4.14). Later Novell SLES or Red Hat distributions may not require this circumvention.

The following circumventions have been tested:

(a) Put the following statement in the httpd.conf file:

LoadFile /usr/lib64/libcrypto.so

(a1) As an alternative to the preferred step (a), add the following to the IBM HTTP Server bin/envvars file:

LD_PRELOAD=/usr/lib/libcrypto.so:/usr/lib64/libcrypto.so 
export LD_PRELOAD

(b) For the iKeyman utility, add the following at the top of the IHS bin/ikeyman_startup script:

LD_PRELOAD=/usr/lib/libcrypto.so:/usr/lib64/libcrypto.so

Error indication: IHS does not start with SSL support enabled. The IHS error_log file shows:

[Mon Aug 20 14:46:52 2012] [crit] Error 430 initializing SSL environment, aborting startup
[Mon Aug 20 14:46:52 2012] [error] SSL0153E: Initialization error, 
The PKCS#11 driver failed to find the token specified by the caller.

When IHS starts successfully with SSL enabled the error_log reports:

[Mon Aug 27 17:05:16 2012] [notice] Using GSKit version 8.0.14.9

See also the IBM support technote:

http://www.ibm.com/support/docview.wss?uid=swg21313367

SSLProtocolDisable SSLv2, SSLProtocolDisable SSLv3

Disabling SSL protocols SSLv2 and SSLv3 to force TLS in this example.

SSLCipherSpec ALL NONE

SSLCipherSpec ALL +TLS_RSA_WITH_AES_256_CBC_SHA

An example for the long name cipher suite specification. ALL NONE removes all default ciphers from the list. Then any desired cipher suites can be added to the list, indicated by the prefix plus sign. Only one cipher suite is added here to force the usage of the selected ciphers for the benchmark application. See also the comments in Selecting IBM WebSphere Application Server cipher suites.

# SSLAttributeSet 417 549

Not used here. This was required for older GSKit versions, so that CPACF can be used for the symmetric cipher offload. GSKit8 no longer requires this directive. However, verify with the icastats command that the chosen symmetric ciphers (3DES, AES) are displayed in the hardware column.

SSLServerCert IBMICATOK:ihscert

Sets the server certificate to use for this virtual host. In this case it is the PKCS#11 cryptographic ICA token that holds the server certificates. The token label must be the same as the label given during the PKCS#11 token initialization process. The name of the server certificate follows after the token.

SSLStashfile /opt/IBM/HTTPServer/ssl/ibmicatok.sth

Name of the password file that holds the stashed PKCS#11 cryptographic ICA token user PIN.

SSLPKCSDriver /usr/lib/pkcs11/PKCS11_API.so64

Fully qualified name of the PKCS#11 library module.