Configure the IBM HTTP Server for distributed platforms and the Web server plug-in for SSL

 

Overview

This section documents the configuration necessary to instantiate a secure connection between the Web server plug-in and the internal HTTP transport in the WebSphere Application Server Web container on a distributed platform. By default, this connection is not secure, even when global security is enabled. This document discusses the configuration for the IBM HTTP Server; however, the Web server related configuration in this situation is not specific to any distributed platform Web server.

  1. Create a self-signed certificate for the Web server plug-in.

    The Web server plug-in requires a key ring file to store its own private and public key files and to store the public certificate from the Web container key file. The following steps are required to generate a self-signed certificate for the Web server plug-in.

    1. Create a directory on the Web server host for storing the key ring file referenced by the plug-in and associated files, for example: IHS_install_root\conf\keys.

    2. Launch the key management utility (iKeyman) packaged with the IBM HTTP Server.

    3. From the iKeyman menu, click Key Database File > New.

    4. Enter the following settings:

      Key database file

      CMS Key Database File

      File name

      WASplugin.kdb

      Location

      C:\http1324\conf\keys\(or file of your choice)

    5. Click OK.

    6. Set the password of your choice at the password prompt. Select the Stash the Password to a File check box to save the password to a stash file. This action allows the plug-in to use the password, which provides access to the certificates contained in the key database.

    7. From the iKeyman menu, click Create > New Self-Signed Certificate to create a new self-signed certificate key pair. Specify the following options. Optionally, you can choose to complete all of the remaining fields.

      Key label

      WASplugin

      Version

      X509 V3

      Key size

      1024

      Common name

      droplet.austin.ibm.com

      Organization

      IBM

      Country

      US

      Validity period

      365

    8. Click OK.

    9. Extract the public self-signed certificate key: this key is used later by the embedded HTTP server peer to authenticate connections originating from the plug-in.

    10. Click Personal Certificates in the menu and select the WASplugin certificate that you just created.

    11. Click Extract Certificate. Extract the certificate to a file:

      Data type

      Base64-encoded ASCII data

      Certificate file name

      WASpluginPubCert.arm

      Location

      C:\http1324\conf\keys (or directory of your choice)

    12. Click OK.

    13. Close the key database and exit the iKeyman when you finish.

  2. Generate a self-signed certificate for the Web container.

    1. Launch the JKS capable iKeyman version located the product /bin directory.

    2. Click Key Database File > New from the iKeyman menu.

    3. Enter the following settings:

      Key database file

      JKS

      File name

      WASWebContainer.jks

      Location

      C:\WebSphere\AppServer\etc\ (or directory of your choice)

    4. Click OK.

    5. Enter the password of your choice at the password prompt window.

    6. Click Create > New Self-Signed Certificate from the iKeyman menu. The following values were used in this example:

      Key Label

      WASWebContainer

      Version

      X509 V3

      Key size

      1024

      Common name

      droplet.austin.ibm.com

      Organization

      IBM

      Country

      US

      Validity Period

      365

    7. Click OK.

    8. Extract the public self-signed certificate key: this key is used later by the Web server plug-in peer to authenticate connections originating from the embedded HTTP server in the product.

    9. Click Personal Certificates from the list. Select the WASWebContainer certificate that you just created. Click Extract Certificate. Extract the certificate to a file:

      Data type

      Base64-encoded ASCII data

      Certificate file name

      WASWebContainerPubCert.arm

      Location

      C:\WebSphere\AppServer\etc\

    10. Click OK.

    11. Close the database and exit the key management utility.

  3. Exchange the public certificates.

    1. Copy the WASpluginPubCert.arm file from the Web server machine to the WebSphere Application Server machine. The source directory in this case is C:\http1324\conf\keys, while the destination is C:\WebSphere\Appserver\etc.

    2. Copy the WASWebContainerPubCert.arm file from the product machine to the Web server machine. The source directory in this case is C:\WebSphere\Appserver\etc, while the destination is C:\http1324\conf\keys.

  4. Import the certificate into the Web server plug-in key file.

    1. On the Web server machine, launch the key management utility that supports the CMS key database format.

    2. From the iKeyman menu, click Key Database File > Open and select the previously created key database file: WASplugin.kdb.

    3. In the password prompt window, enter the password. Click OK.

    4. Click Signer Certificates from the list and click Add. This action imports the public certificate previously extracted from the embedded HTTP server (Web container) keystore file.

      Data type

      Base64-encoded ASCII data

      Certificate file name

      WASWebContainerPubCert.arm

      Location

      C:\WebSphere\Appserver\etc\

    5. Click OK.You are prompted for a label name that represents the trusted signer public certificate.

    6. Enter a label for the certificate: WASWebContainer.

    7. Close the key database and exit IKeyman when you finish.

  5. Import the certificate into the Web container keystore file.

    1. On the WebSphere Application Server machine, launch the JKS capable iKeyman version, located in the product /bin directory.

    2. From the iKeyman menu, select Key Database File > Open. Select the previously created WASWebContainer.jks file.

    3. In the password prompt window, enter the password. Click OK.

    4. Click Signer Certificates from the list. Click Add. This action imports the public certificate previously extracted from the embedded HTTP server (Web container) keystore file.

      Data type

      Base64-encoded ASCII data

      Certificate file name

      WASpluginPubCert.arm

      Location

      C:\WebSphere\Appserver\etc\

    5. Click OK.You are prompted for a label name that represents the trusted signer public certificate.

    6. Enter a label for the certificate: WASplugin.

    7. Close the key database and exit iKeyman when you finish.

  6. Modify the Web server plug-in file.In a production environment, add the secure transport definition, port 9443, to the plugin-cfg.xml file. For example, your modified plugin-key.kdb file contains the following lines: 

    <Transport Hostname="hpws07" Port="9080" Protocol="http"/>
<Transport Hostname="hpws07" Port="9443" Protocol="https"/>

    When you install WebSphere Application Server Network Deployment on one machine, configure a Web server on another machine, and use additional servers for load balancing, configure the plugin-cfg.xml file to point to a plugin-key.kdb file and a plugin-key.sth file for each server in the ServerCluster stanza. You need to reference these files on the local file system of the Web server. The following is an example of two servers configured to point to the same plugin-key.kdb and plugin-key.sth files while a third server points to a different set of files. Based upon the SSL requirements of the servers, you might need different kdb files for different servers. However, most of the time you can use a single kdb file for all of your servers. 

    <ServerCluster Name="server_Cluster">
   <Server Name="server1">
       <Transport Hostname="server1.austin.ibm.com" Port="9080" Protocol="http"/>
       <Transport Hostname="server1.austin.ibm.com" Port="9443" Protocol="https">
           <Property name="keyring" value="C:\WebSphere\AppServer/etc/plugin-key.kdb"/>
           <Property name="stashfile" value="C:\WebSphere\AppServer/etc/plugin-key.sth"/>
       </Transport>
   </Server>
   <Server Name="server2">
       <Transport Hostname="server2.austin.ibm.com" Port="9080" Protocol="http"/>
       <Transport Hostname="server2.austin.ibm.com" Port="9443" Protocol="https">
           <Property name="keyring" value="C:\WebSphere\AppServer/etc/plugin-key.kdb"/>
           <Property name="stashfile" value="C:\WebSphere\AppServer/etc/plugin-key.sth"/>
       </Transport>
   </Server>
   <Server Name="server3">
       <Transport Hostname="server3.austin.ibm.com" Port="9080" Protocol="http"/>
       <Transport Hostname="server3.austin.ibm.com" Port="9443" Protocol="https">
           <Property name="keyring" value="C:\WebSphere\AppServer/etc/newplugin-key.kdb"/>
           <Property name="stashfile" value="C:\WebSphere\AppServer/etc/newplugin-key.sth"/>
       </Transport>
   </Server>
</ServerCluster>

    After you verify that the proper plugin-key.kdb and plugin-key.sth files exist on the Web server, modify the plugin-cfg.xml file that resides on the Web server. You must specify the local path to both the plugin-key.kdb and plugin-key.sth files in the plugin-cfg.xml file. For more information, see plugin-cfg.xml file and Situations requiring manual editing of the plug-in configuration.

    Note: If you manually edit the plugin-cfg.xml file and an automatic regeneration of the file occurs, replace your manual edits.

  7. Modify the Web container to support SSL.To complete the configuration between Web server plug-in and Web container, modify the WebSphere Application Server Web container to use the previously created self-signed certificates.

    1. Start the WebSphere Application Server administrative console.

    2. Click Security > SSL Configuration Repertoires.

    3. Click New to create a new entry in the repertoire. Provide the following values to complete the form:

      Alias

      WebContainerSSLSettings

      Key file name

      C:\WebSphere\Appserver\etc\WASWebContainer.jks

      Key file password

      <key_file_password>

      Key file format

      JKS

      Trust file name

      C:\WebSphere\Appserver\etc\WASWebContainer.jks

      Trust file password

      <trust_file_password>

      Trust file format

      JKS

      Client authentication

      Security level

      HIGH

    4. Click OK.

    5. If you want mutual SSL between the two parties, select the Client Authentication check box.

    6. Save the configuration in the administrative console.

    7. Click Servers > Application Servers, server, in this example, server1.

    8. Click the Web container located in the server navigation tree.

    9. Click HTTP Transport located in the Web container navigation tree.

    10. Select the entry for the transfer you want to secure. Click the item under the Host column. Select the asterisk (*), in this case, in the line of port 9443.

    11. On the configuration panel, select the Enable SSL check box. Click the desired SSL entry from the SSL repertoire list. In this example, the WebContainerSSLSettings.

    12. Click OK.

  8. Test the secure connection.Test the secure connection by accessing a Web application on the WebSphere Application Server using port 9443. For example, https://droplet.austin.ibm.com:9443/snoop.

  9. Import the correct certificate with public and private keys into the browser to test the secured connection, when client-side certification is required.

    1. Launch the iKeyman utility that supports the CMS key database file, on the Web server machine.

    2. Open the key file for the plug-in, C:\http1324\conf\keys\WASplugin.kdb. Provide the password when prompted.

    3. Click WASplugin certificate, located under the Personal Certificates. Click Export.

    4. Save the certificate in PKCS12 format to a file, for example C:\http1324\conf\keys\WASplugin.p12 . Provide a password to secure the PKCS12 certificate file.

    5. Close the key file and exit iKeyman.

    6. Copy the saved WASplugin.p12 file to the client machine from where you access the product server.

    7. Import the PKCS12 file into your browser. Then, access https://your_server_address:9443/snoop.

    8. The browser asks which personal certificate to use for the connection. Select the certificate, and continue connecting.

    9. Once the browser test with direct product access is successful, test the connection through the Web server using port 9443. For example, https://your_server_address:9443/snoop.

 

Results

The IBM HTTP Server plug-in and the internal Web server are configured for SSL.

 

Example

Related concepts
Secure Sockets Layer
Situations requiring manual editing of the plug-in configuration
Related tasks
Managing digital certificates
Creating a Secure Sockets Layer repertoire configuration entry
Related reference
plugin-cfg.xml file
Port number settings in WebSphere Application Server versions