LiveCycle Developer Center

Configuring SSL on IBM WebSphere 6.0x – Part 1: Creating the keystore

This article is the first in a three-part series on configuring SSL for IBM WebSphere 6.0x. In Part 1, I'll walk you through the process of creating a key database file and self-signed certificates. Part 2 will cover the process of enabling SSL itself. Finally, Part 3 will show you how to enable the client to trust the server's SSL certificate.

Secure Sockets Layer (SSL) utilizes digital certificates to establish a secure connection between client and server where the data that is transferred is encrypted. The digital certificates that are used to enable SSL can be purchased from a third-party certificate authority, or self-signed certificates can be created using the IBM Key Management Utility.

Note: This document was created for WebSphere 6.0.x.x but the steps to enable SSL on WebSphere 5.1.x are virtually identical. There are some UI changes between version 5.1.x and 6.0.x in WebSphere, but this guide should enable you to configure SSL on WebSphere version 5.1.x as well.

Requirements

In order to make the most of this article, you need the following software:

Microsoft Windows Server 2003 Enterprise Edition

• Learn more

IBM WebSphere

• Learn more

Prerequisite knowledge

• General understanding digital certificate technology
• Understanding of the purpose of SSL
• General knowledge of the WebSphere Administration User Interface

Creating the keystore

The first step in configuring SSL on WebSphere 6.0x is to create the keystore. The keystore is a database file used by SSL to store the certificates it uses for authentication and data integrity. You create the keystore using IBM's Key Management Utility, which comes installed with WebSphere:

1. Select Start > All Programs > IBM HTTP Server 6.0 > Start Key Management Utility.

2. Select Key Database File > New (see Figure 1).

   

   Figure 2. Create a new key database file

3. Select Key database type > JKS.
4. Name the file with a .jks extension. For the purposes of this tutorial, we will use ServerCredentials.jks.

5. Click the Browse button and navigate to C:\Program Files\IBM\WebSphere\AppServer\profiles\default\etc (see Figure 2).

   Note: I've recommended this path because it's the default path created when you install WebSphere. Furthermore, this path maps to the server variable ${USER_INSTALL_ROOT}/etc, which you will use in later steps. Whatever path you use, take note of it, as in later steps you will map WebSphere to the location of the .jks file.

   

   Figure 2. Set the key database type, filename, and location

6. Click OK. In the dialog box that appears next, enter a password and click OK.

7. Select Personal Certificates from the Key database content menu (see Figure 3).

   

   Figure 3. Select Personal Certificates

8. Click the New Self-Signed button.

9. Fill in the Create New Self-Signed Certificate dialog box with the required information (see Figure 4). For the purposes of this document, we will use serverSSL-credentials as the Key Label.

   Important note: The Common Name value must be identical to the machine name used in the URL that is utilizing SSL. (See the section Certificate configuration for a detailed explanation.)

   

   Figure 4. Filling in the Create New Self-Signed Certificate dialog box

10. Click OK.
11. Make sure your certificate is selected in the Key database content list; then click the Extract Certificate button.
12. Select Data type > Base64-encoded ASCII data.

13. Name the file with an .arm extension. For the purposes of this tutorial, we will use serverSSL-credentials.arm.

    Note: An .arm file is the equivalent of a .cer file (Public Key portion of a PKI credential).

14. Click the Browse button and navigate to C:\Program Files\IBM\WebSphere\AppServer\profiles\default\etc (see Figure 5).

    Note: I've recommended this path because it's the default path created when you install WebSphere. Furthermore, this path maps to the server variable ${USER_INSTALL_ROOT}/etc, which you will use in later steps

    

    Figure 5. Setting the parameters to extract the certificate to a file

15. Click OK. The window's status bar will display the message "The requested action has successfully completed."
16. Select Signer Certificates from the Key database content menu.
17. Click the Add button.
18. Select Data type > Base64-encoded ASCII data.
19. Enter the same filename—serverSSL-credentials.arm—that you used in Step 13.
20. Click the Browse button and navigate to C:\Program Files\IBM\WebSphere\AppServer\profiles\default\etc, the same path you used in Step 14.
21. Click OK. Enter a label for the certificate. For the purposes of this tutorial, we will use serverSSL-credentials-cert.
22. Click OK.

Certificate configuration

When you connect to an SSL-enabled URL, if the security certificate common name (CN) is different from the server name used in the URL, or the security certificate is not trusted, a security alert dialog box will be displayed. If this occurs when you are using a web browser, you can continue to connect to the HTTPS site by clicking the Yes button.

However, when you connect to an SSL-enabled URL with Adobe Acrobat or Adobe Reader and the security alert is triggered, the dialog box is not displayed and there is no way to dismiss it. Adobe Acrobat will generate an error.

Acrobat version 7.0x will report: "Unable to connect to the service at: https://servername:9443. Please check that the URL you have entered is correct and that this computer is connected to the network and try again."

Acrobat version 8.0 will report: "Unable to contact service. If this computer is not connected to the network, connect to the network and try again."

Naming the security certificate

As noted, the Common Name (CN) value used when creating a keystore must be identical to the machine name used in the URL that is utilizing SSL (the actual filename is not important). For example, if you use the URL "https://LCPolicy:9443/edc/Main.do" to access the Policy Server login page, then the CN value used when creating the keystore (.jks file) must be LCPolicy. If the CN value doesn't match the server name in the URL, you will be prompted with the Security Alert dialog box shown in Figure 6.

Figure 6. Security Alert telling you that either the certificate's name is invalid or it doesn't match the name of the site

The alert shown in Figure 6 indicates that the server's security certificate (.cer) has been trusted (imported into the Internet Explorer certificate store) but that the name on the security certificate is invalid or does not match the name of the site.

Trusting the security certificate

In addition to properly naming the security certificate, you must ensure that the server's security certificate is trusted by the client that is establishing the SSL connection with the server (see Figure 7).

Figure 7. Security Alert telling you that the server's security certificate has not been trusted

The alert shown in Figure 7 indicates that the server's security certificate (.cer) has not been trusted, This means that the certificate has not been imported into the Internet Explorer certificate store.

Where to go from here

So far, you've got the keystore created: the key database file, a personal certificate, and a signer certificate. From here, Part 2 will show you how to enable SSL itself. Then Part 3 will show you how to enable the client to trust the server's SSL certificate.

You can also get more information about SSL in WebSphere from IBM:

• IBM WebSphere 6.0x Online Manual, Secure Sockets Layer

About the author