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 virtualhosts as well as troubleshooting and tracing information.

Resolving The Problem

The following steps help guide you through the proper set up of 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. Other considerations when enabling SSL directives within the IBM HTTP Server configuration file (httpd.conf)
  4. Information that IBM WebSphere® Support needs to debug SSL configuration and certificate issues related to the IBM HTTP Server
 
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.

For detailed information on creating a  key database and server certificates, refer to the following technotes:

More extensive information on using the iKeyman GUI to create key database files and certificates is located here:
1) Verify that the SSL modules are uncommented in httpd.conf:
# Remove leading # from below if present
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
2) Create an SSL virtualhost stanza using the following examples and directives
Examples configurations can be appended to httpd.conf

Example 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"
Example 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.

For more information on why different IP addresses are required when enabling multiple Web sites for SSL prior to 9.0, see the following technote: IP-Based Virtual Hosting must be used if configuring multiple SSL Virtual Host
 
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"

 
Example 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
  • How to rewrite HTTP (port 80) requests to HTTPS (port 443)
    The rewrite module (mod_rewrite.c) provided with the IBM HTTP Server can be used as an effective way to automatically rewrite all HTTP requests to HTTPS. For complete information review the following technote:
  • Logging SSL request information in the access log for IBM HTTP Server
    The IBM HTTP Server implementation provides Secure Sockets Layer (SSL) environment variables that are configurable with the LogFormat directive in httpd.conf. For complete information review the following technote:
Brief description of the SSL directives discussed in this document

Listen
Tells the IBM HTTP Server what port to use for secure communication. The standard port is 443. This directive is set in the Global Scope.

SSLEnable
Enables this virtualhost for secure communication

SSLClientAuth Required
By default, only the server provides a certificate to the client. To enable client authentication, use the "SSLClientAuth Required" directive.

KeyFile
In the Global Scope; points to the key database file that contains the personal server certificates required by the browser during an SSL handshake.

SSLServerCert
Specifies the labelname of the certificate in the key database file that must be passed to the client browser during an SSL handshake. This is useful and required when you have multiple certificates stored in the key database file along with multiple SSL virtualhosts.

SSLCipherSpec
Used to limit which cipher the site allows during an SSL handshake. Browsers that do not provide the allowed cipher are denied access to the requested resource.


For a complete list of available SSL directives:

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"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":"","label":""}}]

Document Information

Modified date:
11 February 2021

UID

swg21179559