Kevin Bittner, Test Engineer, IBM
Bill Hankard, Test Engineer, IBM
Yuriy Veytsman, Staff Software Engineer, IBM
29 Mar 2004
Learn how to make your Lotus Workplace environment more secure by running it with Secure Sockets Layer (SSL) enabled. This article is based on our own experiences with configuring Lotus Workplace to run with SSL.
SSL (Secure Sockets Layer) is a protocol for transmitting confidential information over the Web and other networks. SSL uses a private key to encrypt data, which is then transferred in its encrypted state. The data is then decrypted at the destination server, using the same private key. For many environments, SSL is an important component of their overall security strategy. (You may have noticed that the URLs for sites that require an SSL connection generally start with HTTPS instead of HTTP.)
As part of our pre-release testing for Lotus Workplace 2.0, we configured SSL security on our servers to test Lotus Workplace's ability to communicate in a secure environment. We did this to ensure that Lotus Workplace worked the same with SSL enabled as without it. We ran scripts and tests against servers with SSL enabled, and then ran the same tests without SSL. To do this, we set up a complete SSL environment for Lotus Workplace.
This article reviews our experiences setting up this Lotus Workplace SSL environment. The instructions we provide are based on internal configuration procedures developed initially by the Lotus Workplace Infrastructure team. We begin by explaining how we enabled SSL on the HTTP server. We then discuss enabling SSL in Lotus Workplace itself. We conclude with a description of how you can set up a simple test to validate the new SSL connection. Our goal is to help experienced system administrators (especially those with SSL experience) set up their Lotus Workplace sites with SSL.
Our procedures are based on our experiences setting up SSL on a Windows 2000 server. These instructions will also work for AIX and Linux servers, although there will be some differences in file names and locations. (Consult your platform documentation for help with these differences.)
Enabling SSL on the HTTP server
The first step in setting up SSL for Lotus Workplace is to create the key that the servers use to authenticate with each other. You can do this using IBM's ikeyman tool, which is installed when you install the IBM HTTP server included with Lotus Workplace.
Creating a new key
To create a key and the associated databases and files, follow these steps. (Note: These instructions assume that your Lotus Workplace server is in a non-secured environment. To integrate Lotus Workplace with an existing SSL environment, go to the section "Integrating a Lotus Workplace server into an existing SSL key database" later in this article.)
Click OK to save the new key database file.Select a password for the Key Ring. To do this, type a password and verify it.(Optional) Select the Set expiration time? checkbox and enter the interval (in days) after which a new password must be selected for the Key Ring. The default is 60 days. (This is the setting we used for our testing.)Select the Stash the password to a file? checkbox.
- Start the ikeyman utility. From the Windows Start menu, choose Programs - IBM HTTP Server - Start Key Management Utility. This opens the Key Management menu.
- Create a new key database file by choosing Key Database File - New, and then enter the following information:
Figure 2. Entering Key Ring password informationClick OK. You should see an information dialog box indicating that the password has been encrypted and saved in the file key.sth. Close the dialog box.In Windows Explorer, verify that you have the following four files in <IHS root>/ssl/keys:
Creating a self-signed digital certificate
To create a self-signed digital certificate, do the following:
The remaining fields of this dialog box are optional. However, we recommend that you complete as many of these as you can. Then click OK. You should see the newly created digital certificate in the list:
- At the Key Management menu, click Signer Certificates. (This option is located just above the list of CAs.) Then select Personal Certificates. If you haven't created any personal certificates yet, you should see an empty list:
Figure 3. Personal Certificates
- Click the New Self-Signed button and enter the following information:
Figure 5. New certificateClose the Key Manager utility.
Integrating a Lotus Workplace server into an existing SSL key database
In the preceding sections, we discussed creating a new SSL key file for your Lotus Workplace site. This section describes incorporating Lotus Workplace in an existing SSL environment.
- On your HTTP server, go to your <IHS_ROOT>\ssl folder and create a folder called keys. (The default <IHS_ROOT> directory is C:\Program Files\IBMHttpServer. If you chose default settings while installing WebSphere Application Server, the new folder you create will be C:\Program Files\IBMHttpServer\ssl\keys.)
- Obtain the following files from your current SSL key database administrator (assuming ikeyman was used to create the key and database): <filename>.sth, <filename>.kdb, <filename>.rdb, and <filename>.crl. The file names are not critical; it is the extensions that identify the files to ikeyman:
- <filename>.kdb is the key database file. This stores personal certificates, personal certificate requests, and signer certificates.
- <filename>.sth is the stash file. This stores an "obfuscated" version of the key database password. The stem name of this file is the same as the associated KDB file. This also stores private keys, if any.
- <filename>.rdb is the request database file. This is automatically created when you create a KDB key database file. The stem name of this file is the same as the associated KDB file. This file contains certificate requests that are outstanding and that have not yet been received back from the Certificate Authority (CA). When a certificate is returned from the CA, the RDB file is searched for the matching certificate request (based on the public key). If a match is found, the certificate is received and the corresponding certificate request is deleted from the RDB file. If a match is not found, the attempt to receive the certificate is rejected. Included in the certificate request is the common name, organization, street address, and other information that was specified at the time of the request, as well as the public and private key associated with the request.
- <filename>.crl is the certificate revocation list file. This file normally contains the list of certificates that have been revoked for one reason or another. However, ikeyman does not provide any support for certificate revocation lists, so it is empty.
Updating the HTTP Config file
You next need to update the HTTP server configuration file to use SSL. The following steps adjust the file for the IBM HTTP server. If you are using a different server, consult your product documentation for the correct way to implement SSL.
- Before editing the httpd.conf file, make a backup to revert to in case of an error.
- Open the httpd.conf file (located in <IHS_ROOT>\conf folder) in your favorite text editor.
- Append the following lines to the end of this file:
LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll
Keyfile "c:\program files\ibmhttpserver/ssl/keys/key.kdb"
Keyfile "c:\program files\ibmhttpserver/ssl/keys/key.kdb"
where HOST_MACHINE is your fully qualified machine name (for example, www.sales.workplace.acme.com), and the keyfile path/name combination is the path/name you set previously, as described in the section "Enabling SSL on the HTTP server."
- Next, comment out any entries that start with Afpa. Use # to mark a line for comment. In the http.conf file on our servers, there were three lines to comment:
#AfpaLogFile "C:\IBMHttpServer/logs/afpalog" V-ECLF
These files are used to control the Fast Response Cache Accelerator. For more information on these directives, see the Using AFPA Directives page.
- After you have completed these changes, save and close httpd.conf. Then restart the HTTP server to have these changes take effect. To do this under Windows, open the Services window and restart the IBM HTTP Server service.
After restarting the HTTP server, test that your server is still functional by typing the URL http://localhost into a browser screen and ensuring that you see the IBM HTTP Server configuration screen. If not, check the modifications you made to the http.conf file for any typing errors (including failure to comment out the lines beginning with Afpa.) If this doesn't fix the problem, consult your product documentation.
Enabling SSL in Lotus Workplace
To enable SSL in Lotus Workplace, the WebSphere Application Server upon which Lotus Workplace runs needs to be configured to run under SSL. You do this by logging onto the WebSphere Application Server Administration Console as an Administrator. (Typically, the Administration Console address is http://servername.yourco.com:9090/admin.)
- At the Administration Console, click Environment in the Navigator and select Virtual Hosts.
- Select default_host and then Host Aliases under Additional Properties.
Figure 6. Host Aliases
- Click New and enter the following information:
Host Name: *
This sets up the Administration Server to listen on the default SSL port (443).
- To make this new host alias active, click Apply, and then Save. Click Save again to add the new information to the WebSphere Application Server configuration.
- To have WebSphere Application Server read the saved configuration, update the Web Server Plug-in by selecting Environment from the Navigator and then choose Update Web Server Plug-in.
- Click OK and then log out.
- You now need to make some manual adjustments outside of the Administration Console. This requires shutting down the WebSphere Application Server. You can do this by opening the Windows Start menu and choosing Programs - IBM WebSphere - Application Server 5.0 - Stop the Server. (You can also stop the server by executing the stopServer command from a command window.) Your WebSphere Application Server administrator can help you perform this operation.
- At this point, you must edit several configuration files to enable SSL authentication. The first file is plugin-cfg.xml. This file is located in the <WAS_ROOT> directory, which by default is c:\WebSphere\AppServer in the subdirectory config\cells. Open the file in an editor, and search on the word esiEnable. It should be in the file and set to false. If the value is present and set to true, change it to false. Add the following line:
<Property name="esiEnable" value="false"/>
This line must be placed within the <Config> </Config> pairing.
- You also need to set up the WebSphere Portal Server to listen on the SSL port. The quickest and easiest way is to edit the file configservices.properties. The file is located in \WebSphere\PortalServer\shared\app\config\services\. In the file, the following two lines need to be verified or adjusted:
redirect.login.ssl = true
host.port.https = <alias_port>
where <alias_port> is the port number used for the virtual host alias specified in step 3 of this procedure. The parameter redirect.logout.ssl can be left set to false.
- The next step involves making the same change to a number of files. These files are part of the Portal Server and WebSphere Portal Content Publisher (WPCP) and are part of the Enterprise Applications for them. The changes enable the protected portal URLs to use HTTPS for communication. In all cases, the file that needs to be adjusted is called web.xml. The files we need to adjust are in the following directories:
Note: The <WAS_ROOT> is by default c:\WebSphere\AppServer, and <cell-name> is the common or short name of the host server, for instance; acmesales. In each of these files, the value NONE specified in the <transport-guarantee> pairing needs to be set to CONFIDENTIAL. For example:
// replace NONE with CONFIDENTIAL
The setting occurs once in each file with one exception: In the WPCP_Runtime directory, the web.xml file contains the setting twice. Missing the second one causes SSL and HTTPS to fail.
Editing JSP files
You need to enable SSL in the JSP files that control WebSphere Portal. To do this, you must edit 16 JSP files. All the files can be found in subdirectories under <WAS_ROOT>\installedApps\<cell-name>\wps.ear\wps.war\themes\html.
Tip: If you use the Windows Search feature in Windows Explorer, search below this directory for all files containing the string ssl=. You should return 16 files.
- Open the following files to edit:
- In all these files, there should be a single instance of the setting ssl=false. In each case, reset it to true. A simple search of the file should locate the setting quickly. This attribute should appear in an anchor similar to this:
<a href='<wps:url home="public" screen="Login"/>'>
- After finding the login link, change the ssl= attribute to true, for example:
<%-- login button --%>
<wps:if loggedIn="no" notScreen="Login">
<a href='<wps:url home="public" ssl="true" screen="Login"/>'>
<img src='<wps:urlFindInTheme file="nav_login.gif"/>'
alt='<wps:text key="link.login" bundle="nls.engine"/>'
border="0" align="absmiddle" width="25" height="25"
title='<wps:text key="link.login" bundle="nls.engine"/>'>
- After you edit all the JSP files, you need to delete the compiled versions that are being used by the WebSphere Application Server. To do this, go to the WebSphere Application Server cache directory <WAS_ROOT>/temp/<node_name>/WebSphere_Portal/wps and remove the subdirectory wps.war. When the WebSphere Application Server restarts, it will recompile the JSP files and recreate the directory, this time configured for SSL.
- Restart the WebSphere Application Server by opening the Windows Start menu and choosing Programs - IBM WebSphere - Application Server 5.0 - Start the Server (or by executing the startServer command from a command window). Again, your server administrator can help with this step.
- You need to update the URL for the Document Manager portlet to access via SSL. To do this, logon to Lotus Workplace as the administrator. Select Administration - Portlets - Manage portlet. Then select the Document Manager portlet, and click the wrench icon (modify parameters). In the Edit Parameters fields, add the parameter pdmWpcpUrl, and set the value to https://<servername>/wps/wcp. Then click the plus sign to add the parameter and log out.
- Log on to the WebSphere Application Server Administration Console as an administrator, and regenerate the Web Server Plug-in by selecting Environment and then Update Web Server Plug-in. This forces the server to "see" the changes that have been made to the various XML and JSP files.
- Click OK and then log out.
Restarting all servers
You now need to restart all the servers associated with Lotus Workplace to ensure that the changes you have just made are in place. Using the guidelines from the appropriate product documentation, stop and then restart the WebSphere Application Server, the WebSphere Portal server, the Lotus Workplace server, and finally the HTTP server.
Validating the SSL connections
After you have fully configured SSL to the level you want, there are some simple steps to take to check for SSL connectivity. First, hit the HTTP server through the SSL port, 443. You do this by entering the URL:
where <server name> is the name of the HTTP host machine. In this URL, notice the s in https and the port designation 443. You are presented with a window similar to this:
Figure 7. Security Alert screen
This window is a standard browser function and indicates that a security certificate is being accessed and validated against the browser's list of accepted certificates. The appearance of the window is a sign that SSL is being used. Click Yes and proceed.
After the HTTP server Welcome page is displayed, look on the browser task bar for the Lock indicator. This is what the one in Internet Explorer looks like:
Figure 8. Lock indicator
If the Lock icon is closed, the site is secured, and SSL is working with the HTTP server.
Next, check Lotus Workplace. Start up a Lotus Workplace session and click the Log In link. Again, you may be presented with the Security Alert window. If so, click Yes and continue. At this point, check the URL displayed on the browser. The HTTP prefix should be replaced with HTTPS, and the lock indicator should be visible. This will show that the basic operations of Lotus Workplace and the login operation are secured.
Once you log in, if Lotus Workplace Collaborative Learning has been installed, select the Learning page and check the URL again. Because Lotus Workplace Collaborative Learning is operated through a separate server, you should check to see that this page is also secured. Again, the URL should begin with HTTPS, and the Lock indicator should be visible. At this point, the basic SSL configuration for Lotus Workplace is complete.
We hope you find our procedures and suggestions for setting up SSL for Lotus Workplace helpful. SSL is often an important part of a site's overall security, and many administrators want to ensure that they can deploy Lotus Workplace with SSL enabled. Our experience indicates that with a little effort, you can set up Lotus Workplace with SSL, helping to ensure the safety and integrity of your corporation's most sensitive information.
|About the authors|
Kevin Bittner is a Test Engineer for the Lotus Engineering Test (LET) team. He started with Lotus in the early 1990's as a 1-2-3/Unix support analyst, and has been involved in customer support for most of his career at Lotus.
Bill Hankard is a Test Engineer for the Lotus Engineering Test (LET) team.
Yuriy Veytsman has been a Staff Software Engineer with IBM/Lotus since the late 1990's, working on projects involving Domino Web Access (iNotes), Discovery Server, Lotus Team Workplace (QuickPlace), and Lotus Instant Messaging (Sametime) testing, and various other responsibilities. Previously, Yuriy was employed developing a variety of software and hardware applications for numerous companies throughout Europe