IBM Support

Guide to properly setting up SSL within the IBM HTTP Server

Troubleshooting


Problem

The following document is a guide for setting up Secure Sockets Layer (SSL) within the IBM HTTP Server. This document contains instructions for creating keyfiles, certificates, and SSL-enabled virtual hosts as well as troubleshooting and tracing information.

Resolving The Problem

The following steps help guide you through the initial configure of TLS/SSL within the IBM HTTP Server:
  1. Create a key database file and certificates needed to enable SSL
  2. Enable SSL directives within the IBM HTTP Server configuration file (httpd.conf)
  3. Enable secure ciphers TLS v1.2 and v1.3 in IHS
  4. Further SSL configuration
 
1) Create a key database file and certificates needed to authenticate the Web server during an SSL handshake
The iKeyman GUI, which is included within the IBM HTTP Server distribution, can be used to create a key database file (for example: key.kdb) needed to store "personal certificates" used to enable SSL.
It is also possible to manage certificates for IHS using the WebSphere Application Server Administration Console. See https://www.ibm.com/support/pages/node/6453975 for details.

For detailed information on creating a  key database and server certificates, refer to the following technotes:
2.i) Load mod_ibm_ssl
# Remove leading # from below if present
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
2.ii) Create an SSL virtual host stanza using one of the following examples and directives
Examples configurations can be appended to httpd.conf

Option 1: Adding a single SSL virtual host using the default certificate in a keyfile
  
Listen 443
# On Windows, specify a Listen of 0.0.0.0:443 and/or [::]:443
<VirtualHost *:443>
    ServerName example.com
    ServerAlias www.example.com
    SSLEnable
</VirtualHost>
KeyFile "c:/program files/ibm http server/conf/key.kdb"
Option 2: Adding SSL virtual hosts using multiple certificates (8.5.5 and earlier)
If multiple certificates are needed, multiple SSL virtualhosts can be defined. Either multiple keystores, or specified labels from a shared KeyFile can be used.  Each SSL virtual host must use a unique IP:PORT combination.
  
Listen 443
<VirtualHost 192.168.1.102:443>
  ServerName www.example.com
  SSLEnable
  SSLServerCert example
</VirtualHost>

<VirtualHost 192.168.1.103:443>
  ServerName store.example.com
  SSLEnable
  SSLServerCert store
</VirtualHost>

<VirtualHost 192.168.1.104:443>
  ServerName orders.example.com
  SSLEnable
  # Custom keystore
  KeyFile "c:/program files/ibm http server/store.kdb"
</VirtualHost>

# Default keyfile when unspecified in virtual host
KeyFile "c:/program files/ibm http server/key.kdb"

 
Option 3: Adding multiple SSL virtual hosts using multiple certificates (9.0)
IHS 9.0 and later supports a more flexible way of using multiple certificates without multiple IP:PORT combinations. See the following topic for examples: TLS Server Name Indication
To enable the secure ciphers for TLS versions 1.2 and 1.3 in IHS, configure the desired ciphers in the httpd.conf configuration file located at /opt/IBM/HTTPServer/conf (for Linux) and C:\Program Files\IBM\HTTPServer\conf (for Windows):
Note: Add the protocol version (for example, TLSv1.2) after the cipher suites (SSLCipherSpec) in the IHS configuration to ensure compatibility with future IHS versions. For example, SSLCipherSpec TLSv1.2 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384.
  •  SSLCipherSpec TLSv1.2 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  •  SSLCipherSpec TLSv1.2 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  •  SSLCipherSpec TLSv1.2 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  •  SSLCipherSpec TLSv1.2 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 
  •  SSLCipherSpec TLSv1.3 TLS_AES_256_GCM_SHA384
  •  SSLCipherSpec TLSv1.3 TLS_CHACHA20_POLY1305_SHA256
  •  SSLCipherSpec TLSv1.3 TLS_AES_128_GCM_SHA256

The following ciphers are not supported in both WAS 8.x and WAS 9.x:

  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256
  • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
  • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

TLS v1.3 ciphers are not supported in WAS 8.x.

  • TLS_AES_256_GCM_SHA384
  • TLS_AES_128_GCM_SHA256
  • TLS_CHACHA20_POLY1305_SHA256
Notes:
  • Configure the ciphers when the installer directs you to create a new WAS profile during the CCRC WAN server installation. However, if you choose to install the CCRC WAN server into an existing WAS profile, verify the cipher configurations of the existing profiles using the WAS administration console.
  • The SSLServerCert directive defines the server certificate to be used for a virtual host. To configure both an ECDSA and an RSA certificate, provide two certificate labels separated by a space. If the client supports only RSA or only ECDSA, the corresponding certificate is selected. When the client supports both, the certificate label listed first in this directive takes precedence. Therefore, the certificate type (RSA or ECDSA) that matches the cipher configured in the tls_custom_ciphers.conf file of the client should be specified first in the SSLServerCert directive. After completing the configuration, restart the IHS service for the changes to take effect. For more information, see Secure Sockets Layer (SSL) directives.
After basic SSL has been configured, some further configuration topics may be of interest.
 

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTJ","label":"IBM HTTP Server"},"ARM Category":[{"code":"a8m50000000Cd10AAC","label":"IHS"}],"ARM Case Number":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"All Version(s)","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
07 September 2022

UID

swg21179559

Page Feedback