Guide to properly setting up SSL within the IBM HTTP Server

Technote (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:
  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).

  5. Information that IBM WebSphere Support needs to debug SSL configuration and certificate issues related to the IBM HTTP Server

    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:

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

IBM HTTP Server
SSL

Software version:

6.0, 6.1, 7.0, 8.0

Operating system(s):

AIX, HP-UX, Linux, Solaris, Windows

Reference #:

1179559

Modified date:

2004-09-09

Translate my page

Machine Translation

Content navigation