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

This section documents the configuration necessary to instantiate a secure connection between the Web server plug-in and the internal HTTP transport in the WAS 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_$WAS_HOME>\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.amsterdam.setgetweb.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.amsterdam.setgetweb.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 WAS 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 WAS 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"/>

    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.

    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 WAS 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, server.

    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 (.war) on the WAS using port 9443. For example, https://droplet.amsterdam.setgetweb.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.

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

 

Usage Scenario

 

See Also

SSL
Situations requiring manual editing of the plug-in configuration
Managing digital certificates
Creating a SSL repertoire configuration entry
plugin-cfg.xml file
Port number settings in WAS versions