Configure SSL for WebSphere Application Server

See these topics for instructions on configuring SSL for WebSphere Application Server:

• Configure SSL for WebSphere plug-ins
  • Using the product-provided certificates to configure SSL for WebSphere plug-ins (Version 5.0.1 and later)
  • Creating an SSL key file for the WebSphere Web server plug-in

• Configuring SSL for the application server's HTTPS transport
  1. Create an SSL key file without the default signer certificates
  2. Add the signer certificate of the application server to the plug-in's SSL key file
  3. Grant access to the key files
  4. (Optional) Configure an alias for the SSL port
  5. Configure HTTPS transport for the Web container

Note: For these steps, it is assumed that you have a network drive mapped from your workstation to your iSeries system.

Configure SSL for WebSphere plug-ins

A WebSphere plug-in interfaces with a Web server to handle client requests for server-side resources and routes them to the application server for processing. WebSphere Application Server - Express includes plug-ins for IBM HTTP Server for i5/OS and Domino Web Server for iSeries.

After SSL is working between your browser and Web server, proceed to configure SSL between the Web server plug-in and the WebSphere Application Server product. This is not required if the link between the plug-in and application server is known to be secure or if your applications are not sensitive. If privacy of application data is a concern, however, this connection should be an SSL connection.

Using the product-provided certificates to configure SSL for WebSphere plug-ins (Version 5.0.1 and later)

WebSphere Application Server - Express Version 5.0.1 (and later) updates server instances with an SSL key file. The pathname for the key file is /QIBM/UserData/WebASE/ASE5/instance/etc/plugin-key.kdb, where instance is the name of your server instance. (The remainder of this topic refers to this path as USER_INSTALL_ROOT/etc.) However, server instances are updated only if the plugin-key.kdb file is not already present (that is, if the key file was not manually created prior to the Version 5.0.1 installation).

The plugin-key.kdb file that is used in the update process contains a digital certificate that is required for the Web server plug-in to trust the signer of the Web container's certificate when an HTTPS transport is configured with the default SSL repertoire.

Using the product-provided certificates to configure SSL for the WebSphere plug-ins significantly reduces configuration complexity, but they should not be used for production servers. The tasks below demonstrate how to create your own certificates. Alternatively, you can obtain certificates from a commercial certificate authority.

Creating an SSL key file for the WebSphere Web server plug-in

If you are using the key file that is provided with the product (as of Version 5.0.1) to configure SSL for WebSphere plug-ins, skip this task and proceed to Configure an alias for the SSL port. However, first you should ensure that you have the Cryptographic Access Provider licensed program (5722-AC3) installed on the iSeries system that hosts your Web server.

When configuring SSL, you must first create an SSL key file.

The following is an example of how to create an SSL key file for your WebSphere plug-in:

1. Start the Digital Certificate Manager.
   Procedures vary depending on the release of Digital Certificate Manager (DCM) you have installed on your iSeries system. The release of DCM used in this topic is V5R1M0.

2. Create a local certificate authority.
   Skip this step if you already have a certificate authority (CA) created on you iSeries system.

3. Create a key store for the HTTP server plug-in:
   1. In the left pane, click Create New Certificate Store.
   2. Select Other System Certificate Store and click the Continue button.
   3. On the Create a Certificate in New Certificate Store page, select Yes - Create a certificate in the certificate store, and click Continue.
   4. On the Select a Certificate Authority (CA) page, select Local Certificate Authority and click the Continue button.
   5. Fill in the form to create a certificate and certificate store. Use this pathname for the certificate store:

      /QIBM/UserData/WebASE/ASE5/instance/etc/plugin-key.kdb

      where instance is the name of your instance. (The remainder of these instructions refers to the directory above etc as USER_INSTALL_ROOT.)

      Use MyPluginCert as the key label. Fill in the other required fields, and then click Continue.

4. Set the default system certificate:
   1. In the left pane, click to expand Fast Path.
   2. Select Work with server and client certificates.
   3. Select certificate MyPluginCert.
   4. Click Set default.

5. Remove all trusted signers except the Local CA:
   1. On the left pane, click Select a Certificate Store
   2. Select Other System Certificate Store and click Continue.
   3. On the Certificate Store and Password page, enter the Certificate store path and filename (USER_INSTALL_ROOT/etc/plugin-key.kdb) and the password. Click Continue.
   4. On the left pane, click Fast Path.
   5. Select Work with CA certificates and click Continue.
   6. On the Work with CA Certificates page, for all CA certificates except the LOCAL_CERTIFICATE_AUTHORITY, select the certificate and then click Delete. Respond with Yes when asked if you are sure you want to delete this certificate.

6. Extract the Local CA certificate so that you can import the certificate into the application server key file later:
   1. In the left pane, click Install CA certificate on your PC.
   2. In the right pane, click Copy and paste certificate.
   3. Create text file USER_INSTALL_ROOT/etc/myLocalCA.txt on your workstation's mapped drive to the iSeries, then paste the CA certificate into myLocalCA.txt and save the file. For example, if you want to configure the instance that is named myInstance, and your workstation's F: drive is mapped to the iSeries system, the path is F:\QIBM\UserData\WebASE\ASE5\myInstance\etc\myLocalCA.txt. Ensure that the copy of the CA certificate ends with the new line character.
   4. Click Done.

Use SSL configuration repertoires to manage SSL settings for resources in the administrative domain. The default repertoire is DefaultNode/DefaultSSLSettings. You can use DefaultNode/DefaultSSLSettings for testing or create new SSL configuration repertoires for production applications and associate them with individual resources. For more information, see Use SSL configuration repertoires.

Configuring SSL for the application server's HTTPS transport

To configure SSL, you must first create an SSL key file. The contents of this file depend on whom you want to allow to communicate directly with the application server over the HTTPS port (in other words, you are defining the HTTPS server security policy).

This topic presents a restrictive security policy, in which only a well-defined set of clients (those whose certificates are signed by your local certificate authority) are allowed to connect to the application server HTTPS port. It is recommended that you follow this security policy when your application's deployment descriptor specifies the use of the client certificate authentication method. The procedure for creating an SSL key file without the default signer certificates conforms to this policy.

To configure SSL for the application server's HTTPS transport, follow these steps:

Step 1: Create an SSL key file without the default signer certificates.

1. Start iKeyman on your workstation. For more information, see IBM Key Managment Tool (iKeyman).

2. Create a new key database file:
   1. Click Key Database File and select New.
   2. Specify settings:
      • Key database type: JKS
      • File Name: appServerKeys.jks
      • Location: your etc directory, such as USER_INSTALL_ROOT/etc
   3. Click OK.
   4. Enter a password (twice for confirmation) and click OK.

3. Delete all of the signer certificates.

4. Click Signer Certificates and select Personal Certificates.

5. Add a new self-signed certificate:
   1. Click New Self-Signed to add a self-signed certificate.
   2. Specify settings:
      • Key Label: appServerTest
      • Common Name: use the DNS name for your iSeries server
      • Organization: IBM
   3. Click OK.

6. Extract the certificate from this self-signed certificate so that it can be imported into the plug-in's SSL key file:
   1. Click Extract Certificate.
   2. Specify settings:
      • Data Type: Base64-encoded ASCII data
      • Certificate file name: appServer.arm
      • Location: the path to your etc directory
   3. Click OK.

7. Import the Local CA public certificate:
   1. Click Personal Certificates and select Signer Certificates.
   2. Click Add.
   3. Specify settings:
      • Data Type: Base64-encoded ASCII data
      • Certificate file name: myLocalCA.txt
      • Location: the path to your etc directory
   4. Click OK.

8. Enter plug-in for the label and click OK.

9. Click Key Database File.

10. Select Exit.

Step 2: Add the signer certificate of the application server to the plug-in's SSL key file.

1. Start the Digital Certificate Manager (DCM)
2. On the left pane, click Select a Certificate Store
3. Select Other System Certificate Store and click Continue.
4. On the Certificate Store and Password page, enter the Certificate store path and filename (USER_INSTALL_ROOT/etc/plugin-key.kdb) and the password, then click Continue.
5. On the left pane, click Fast Path.
6. Select Work with CA certificates and click Continue.
7. Click Import.
8. Specify USER_INSTALL_ROOT/etc/appServer.arm for the Import file field value and click Continue.
9. Specify appServer for the CA certificate label field value and click Continue.

Step 3: Grant access to the key files.

It is very important to protect your key files from unauthorized access. Set the following protections by using the i5/OS Change Authority (CHGAUT) command:

• appServerKeys.jks

  PROFILE	ACCESS
  *PUBLIC	*EXCLUDE
  QEJBSVR	*R

• plugin-key.kdb

  PROFILE	ACCESS
  *PUBLIC	*EXCLUDE
  QTMHHTTP	*RX

• All other files you created in the USER_INSTALL_ROOT/etc directory should have *EXCLUDE authority set for *PUBLIC.

Note: QTMHHTTP is the default user profile for the IBM HTTP Server for i5/OS. If your Web server runs under another profile, grant that profile *RX authority for plug-inKeys.kdb instead of QTMHHTTP.

For example, to grant read and execute (*RX) authority for plugin-key.kdb to the QTMHHTTP user profile, run the Change Authority (CHGAUT) command. For example:

  CHGAUT OBJ('/QIBM/UserData/WebASE/ASE5/etc/plugin-key.kdb')
         USER(QTMHHTTP) DTAAUT(*RX)

Step 4: (Optional) Configure an alias for the SSL port

If you have not already configured an alias for your Web server's SSL port in your WebSphere virtual host, do so now.

Step 5: Configure HTTPS transport for the Web container

For more information, see Configure HTTPS transport for your application server's Web container.

Note: Configuring the WebSphere Web plug-in for SSL can require manual updates to the plug-in configuration file. Manual changes can be lost when the plug-in configuration file is regenerated. If you have manually changed the plug-in configuration file, check the file to see determine if your changes have been lost, and reapply them if necessary.

No manual update of the plug-in configuration file is required if you are using the key file that is provided with the product (as of Version 5.0.1) to configure SSL for the Web server plug-in. Your regenerated plug-in configuration file should contain an entry that is similar to the following:

<Transport Hostname="MYISERIES" Port="10175" Protocol="https">  
  <Property name="keyring" value="/QIBM/UserData/WebASE/ASE5/myInstance/etc/plugin-key.kdb"/>
  <Property name="stashfile" value="/QIBM/UserData/WebASE/ASE5/myInstance/etc/plugin-key.sth"/>
</Transport>

The configuration is complete.

As an alternative, you can implement an even more restrictive security policy by configuring the plugin to use a self signed certificate for authenticating to the application server's Web container. Assuming you have successfully completed all steps in the above task, follow these steps to implement this more restrictive policy:

1. Use iKeyman to create a keystore.

2. Create a self signed certificate in the keystore.

3. Export the self signed certificate (with the private key) from the keystore.

4. Extract the self signed certificate (also known as a signer certificate since it doesn't contain the the private key) from the keystore.

5. Again using iKeyman, add the extracted signer certificate to the HTTPS transport's trust store (appServerKeys.jks in the above example).

6. Remove all other signer certificates from the HTTPS transport's trust store.

7. Using DCM, import the self signed certificate (with the private key) into the plugin's key store (plugin-key.kdb). Record the label you use when importing the certificate.

   Note: DCM treats self signed certificates as signer certificates and adds the certificate to the list of signer certificates, even though the certificate contains a private key.

8. Restart the application server.

9. Regenerate the Web plugin configuration file.

10. Specify the certificate the plugin is to use for authenticating to the Web container by manually adding the certLabel property to the HTTPS transport in the Web plugin configuration file (USER_INSTALL_ROOT/config/cell/plugin-cfg.xml). Set the certLabel property value to the label you used when importing the self signed certificate into the plugin's key store. For example:

    <Transport Hostname="MYISERIES" Port="10175" Protocol="https">
      <Property name="keyring" 
       value="/QIBM/UserData/WebASE/ASE5/myinst/etc/plugin-key.kdb"/>
      <Property name="certLabel" value="selfsigned"/>
    </Transport>

11. Restart the Web server.