Configuring the IBM HTTP server Httpd.conf file

You must configure the IBM^® HTTP server to use either the self-signed or CA-signed certificate you created.

1. Make a backup of the httpd.conf file before
2. Navigate to <IHS_root>\conf and, with a text editor, make a backup copy of the IBM HTTP server configuration file, named httpd.conf, then open it.

Add the following to the end of the httpd.conf file to implement one type of SSL implementation on the IBM HTTP server:

   Listen 80

   Listen 443

   FileETag none

   <VirtualHost HOST_MACHINE:443>

         ServerName HOST_MACHINE

         SSLEnable

  

         SSLV2Timeout 100

         SSLV3Timeout 1000

         SSLClientAuth none

   </VirtualHost>

   SSLDisable

1. (IBM HTTP server 1.3.26) (Windows^® only) Add the following line before Listen 80 above:

LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll

2. (IBM HTTP server 2.0.42) Add the following line before Listen 443 above:

LoadModule ibm_ssl_module modules/mod_ibm_ssl.so

3. (AIX^® only) Search for "Dynamic Shared Object (DSO) Support" in httpd.conf, and then locate the list of files that have a SO extension. Enter the following line after LoadModule setenvif_module libexec/mod_setenvif.so:

   LoadModule ibm_ssl_module libexec/mod_ibm_ssl_128.so

4. (AIX only) Search for "AddModule mod_setenvif.c" in httpd.conf, then enter the following line of code after AddModule mod_setenvif.c:

   AddModule mod_ibm_ssl.c

5. (AIX and Linux only) Add the following line after </VirtualHost> and before SSLDisable:

   SSLCacheDisable

6. Navigate to SSLEnable and on the next two lines, enter the path to the key file and SSL stash file:

To configure to use a self-signed certificate on Windows, enter:

   Keyfile "c:\program files\ibmhttpserver\ssl\keys\ihscert.kdb"

   SSLStashfile "c:\program files\ibmhttpserver\ssl\keys\ihscert.sth"

To configure to use a CA-signed certificate on Windows, enter:

   Keyfile "c:\program files\ibmhttpserver\ssl\keys\casignedihscert.kdb"

   SSLStashfile "c:\program files\ibmhttpserver\ssl\keys\casignedihscert.sth"

To configure to use a self-signed certificate on AIX, enter:

   Keyfile "/data/IBMHttpServer/ssl/keys/ihscert.kdb"

   SSLStashfile "/data/IBMHttpServer/ssl/keys/ihscert.sth"

To configure to use a CA-signed certificate on AIX, enter:

   Keyfile "/data/IBMHttpServer/ssl/keys/casignedihscert.kdb"

   SSLStashfile "/data/IBMHttpServer/ssl/keys/casignedihscert.sth"

Note: Windows-based systems use backslashes (\) to delimit directories in a directory path. AIX-based systems and Web addresses use forward slashes (/) as delimiters.

7. Replace all instances of HOST_MACHINE with the fully-qualified host name of the IBM HTTP server.

For example: intlcontact.sales.acme.com.

The resulting httpd.conf file should contain the following text at the end of the file for a system using the intlcontact.sales.acme.com HTTP server. The first example is for self-signed certificate on Windows for an IBM HTTP server 1.3.26; the second is for an IBM HTTP server 2.0.42.

   LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll

   Listen 80

   Listen 443

   FileETag none

   <VirtualHost intlcontact.sales.acme.com:443>

         ServerName intlcontact.sales.acme.com

     SSLEnable

     SSLClientAuth none

     Keyfile "c:\program files\ibmhttpserver\ssl\keys\ihscert.kdb"

       SSLStashfile "c:\program files\ibmhttpserver\ssl\keys\ihscert.sth"

       SSLV2Timeout 100

           SSLV3Timeout 1000

   </VirtualHost>

   SSLDisable

LoadModule ibm_ssl_module modules/mod_ibm_ssl.so      

Listen 443

     <VirtualHost intlcontact.sales.acme.com:443>

         ServerName intlcontact.sales.acme.com

       SSLEnable

       SSLClientAuth none

       Keyfile "c:\program files\ibmhttpserver\ssl\keys\ihscert.kdb"

       SSLStashfile "c:\program files\ibmhttpserver\ssl\keys\ihscert.sth"

      ErrorLog "c:\program files\ibmhttpserver\logs\sslerror.log"

      TransferLog "c:\program files\ibmhttpserver\logs\sslaccess.log"

   </VirtualHost>

     SSLDisable

8. Save and close the file.
9. Stop and restart the IBM HTTP server.

Verify that SSL is working correctly with the IBM HTTP server by going to: https://hostname.domain.com.

Note: Users must use the fully-qualified host name when accessing the server using SSL. For example, use acme.com in the Web address, but not acme. To access the backend IBM Workplace Collaborative Learning Web application, users can enter https://hostname.domain.com/lms-lmm.

MORE about Above in troubleshooting:

Problem(Abstract)

The following information can be used as a guide for setting up the Secure Sockets Layer (SSL) within the IBM HTTP Server. This document covers information on setting up SSL virtualhosts, creating keyfiles, certificates along with how to protect access to directories and URLs to specific ciphers. Also, included is documentation on how to trace and record SSL traffic between a client browser and the Web server.

Resolving the problem

The following steps help guide you through the proper set up of SSL within the IBM HTTP Server:

1. Confirm that the Global Security Kit (GSKit) is installed and meets the minimum requirements
   
   
2. Create a key database file and certificates needed to authenticate the Web server during an SSL handshake
   
   
3. Enable SSL directives within the IBM HTTP Server configuration file (httpd.conf)
   
   
4. Other considerations when enabling SSL directives within the IBM HTTP Server configuration file (httpd.conf)
   
   
5. Information that IBM WebSphere® Support needs to debug SSL configuration and certificate issues related to the IBM HTTP Server

---

1. Confirm that the Global Security Kit is installed and meets the minimum requirements
   The Global Security Kit (GSKit) is a required component for the Secure Sockets Layer (SSL) enablement within the IBM HTTP Server. Therefore, it is important to confirm that a supported version of the Global Security Kit is installed prior to enabling SSL.
   
   For a complete listing of IBM HTTP Server releases and corresponding Global Security Kit versions, click IBM HTTP Server: Global Security Kit (GSKit) supported versions.
   
   
2. 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 server certificates required by the client browser during an SSL handshake.
   
   For quick information on how to create a key database file and personal server certificates, refer to the technote IKEYMAN, How do I...?
   
   More extensive information on using the iKeyman GUI to create key database files and certificates is located here:
   • For releases of IBM HTTP Server v6.0
   • For releases of IBM HTTP Server v6.1
   • For releases of IBM HTTP Server v7.0
   • For releases of IBM HTTP Server v8.0
     
3. Enable SSL directives within the IBM HTTP Server's configuration file (httpd.conf)
   1. Verify that the SSL modules are uncommented
      • For Microsoft® Windows®:
        
        
        

        LoadModule ibm_ssl_module modules/mod_ibm_ssl.so

      • For UNIX® platforms:
        
        
        

        LoadModule ibm_ssl_module modules/mod_ibm_ssl.so

   2. Create an SSL virtualhost stanza using the following examples and directives
      If you are enabling one Web site for SSL, and the hostname is the same as the one already defined in the Global Scope for non-SSL (port 80), you can enable SSL as follows. This virtualhost uses the default hostname defined by the ServerName directive in the Global Scope and the IP address associated with it.
      
      http://www.mycompany.com (non-SSL) 192.168.1.102 https://www.mycompany.com (SSL) 192.168.1.102
      
      Example 1:
      

      Listen 80 ServerName www.mycompany.com <Directory "c:/Program Files/IBM HTTP Server/htdocs"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs" DirectoryIndex index.html Listen 443 <VirtualHost  :443> SSLEnable SSLClientAuth None </VirtualHost> SSLDisable KeyFile "c:/program files/ibm http server/key.kdb" SSLV2Timeout 100 SSLV3Timeout 1000

      If you are enabling one Web site for SSL and the ServerName is different than the ServerName already defined in the Global Scope for non-SSL (port 80), you can enable SSL as follows. Both hostnames must be registered in DNS to a separate IP address, and both IP addresses must be configured on local network interface cards. http://www.mycompany.com (non-SSL) 192.168.1.102 http://www.mycompany2.com (non-SSL) 192.168.1.103 https://www.mycompany2.com (SSL) 192.168.1.103 Example 2:

      Listen 80 ServerName www.mycompany.com <Directory "c:/Program Files/IBM HTTP Server/htdocs"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs" DirectoryIndex index.html <VirtualHost 192.168.1.103:80> ServerName www.mycompany2.com <Directory "c:/Program Files/IBM HTTP Server/htdocs2"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs2" DirectoryIndex index2.html </VirtualHost> Listen 443 <VirtualHost 192.168.1.103:443> ServerName www.mycompany2.com SSLEnable SSLClientAuth None <Directory "c:/Program Files/IBM HTTP Server/htdocs2"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs2" DirectoryIndex index2.html </VirtualHost> SSLDisable KeyFile "c:/program files/ibm http server/key.kdb" SSLV2Timeout 100 SSLV3Timeout 1000

      If you are enabling multiple Web sites for SSL, you can enable SSL as follows. All hostnames must be registered in DNS to a separate IP address. Also, all the IP addresses must be configured on a local network interface card. You must use the SSLServerCert directive to identify which personal server certificate in the key database file is passed to the client browser during the SSL handshake for each Web site. If the SSLServerCert directive is not defined, the IBM HTTP Server passes whatever certificate in the key database file is marked(*) as the "default key". For more information on why different IP addresses are required when enabling multiple Web sites for SSL: IP-Based Virtual Hosting must be used if configuring multiple SSL Virtual Host http://www.mycompany.com (non-SSL) 192.168.1.102 https://www.mycompany.com (non-SSL) 192.168.1.102 http://www.mycompany2.com (non-SSL) 192.168.1.103 https://www.mycompany2.com (SSL) 192.168.1.103 http://www.mycompany3.com (non-SSL) 192.168.1.104 https://www.mycompany3.com (SSL) 192.168.1.104 Example 3:

      Listen 80 ServerName www.mycompany.com <Directory "c:/Program Files/IBM HTTP Server/htdocs"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs" DirectoryIndex index.html <VirtualHost 192.168.1.103:80> ServerName www.mycompany2.com <Directory "c:/Program Files/IBM HTTP Server/htdocs2"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs2" DirectoryIndex index2.html </VirtualHost> <VirtualHost 192.168.1.104:80> ServerName www.mycompany3.com <Directory "c:/Program Files/IBM HTTP Server/htdocs3"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs3" DirectoryIndex index3.html </VirtualHost> Listen 443 <VirtualHost 192.168.1.102:443> ServerName www.mycompany.com SSLEnable SSLClientAuth None SSLServerCert mycompany <Directory "c:/Program Files/IBM HTTP Server/htdocs"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs" DirectoryIndex index.html </VirtualHost> <VirtualHost 192.168.1.103:443> ServerName www.mycompany2.com SSLEnable SSLClientAuth None SSLServerCert mycompany2 <Directory "c:/Program Files/IBM HTTP Server/htdocs2"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs2" DirectoryIndex index2.html </VirtualHost> <VirtualHost 192.168.1.104:443> ServerName www.mycompany3.com SSLEnable SSLClientAuth None SSLServerCert mycompany3 <Directory "c:/Program Files/IBM HTTP Server/htdocs3"> Options Indexes AllowOverride None order allow,deny allow from all </Directory> DocumentRoot "c:/program files/ibm http server/htdocs3" DirectoryIndex index3.html </VirtualHost> SSLDisable KeyFile "c:/program files/ibm http server/key.kdb" SSLV2Timeout 100 SSLV3Timeout 1000

4. Other considerations when enabling SSL directives within the IBM HTTP Server configuration file (httpd.conf).
   
   • Limiting IBM HTTP Server to encrypt at only 128 bits or higherThere are several methods of configuring IBM HTTP Server to restrict and limit SSL to allow only 128 bit browsers and 128,168 bit ciphers access to Web content. For complete information click Limiting IBM HTTP Server to encrypt at only 128 bits or higher.
     
     
   • 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 click How to rewrite HTTP (port 80) requests to HTTPS (port 443).
     
     
   • Logging SSL request information in the access log for IBM HTTP ServerThe IBM HTTP Server implementation provides Secure Sockets Layer (SSL) environment variables that are configurable with the LogFormat directive in httpd.conf. For complete information click Logging SSL request information in the access log for IBM HTTP Server.
     
     
   • Enabling Certificate Revocation Lists (CRL) in the IBM HTTP Server
     Certificate revocation provides the ability to revoke a client certificate given to the IBM HTTP Server by the browser when the key is compromised or when access permission to the key is revoked. CRL represents a database that contains a list of certificates revoked before their scheduled expiration date. For complete information:
     • For releases of IBM HTTP Server v6.0
     • For releases of IBM HTTP Server v6.1
     • For releases of IBM HTTP Server v7.0
     • For releases of IBM HTTP Server v8.0
       
5. Information that IBM WebSphere Support needs to debug SSL configuration and certificate issues related to the IBM HTTP Server
   • MustGather: SSL handshake and configuration problems
     
   • MustGather: CMS key database (.kdb) and certificate problems

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 None
Indicates that client authentication is disabled. This means that the client browser is not required to pass a client certificate during the handshake. Most sites do not require client authentication. To enable client authentication, use the SSLClientAuth Require directive.

SSLDisable
In the Global Scope; indicates SSL is disabled outside the virtualhost.

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. Refer to Step 2 in this technote.

SSLV2Timeout
Sets the timeout for SSL Version 2 session IDs

SSLV3Timeout
Sets the timeout for SSL Version 3 session IDs

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.

SSLCipherRequire
Most often used within a directory and/or location stanza to allow access to specific content, only if the corresponding cipher is used. Browsers that do not provide the allowed cipher are denied access to the requested resource. You can also use SSLCipherBan directives.

For a complete list of available SSL directives:

• For releases of IBM HTTP Server v7.0
• For releases of IBM HTTP Server v6.0
• For releases of IBM HTTP Server v6.1
• For releases of IBM HTTP Server v8.0