Configure the Web server plug-in for Secure Sockets Layer

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
  • 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
  6. Modify the Web server plug-in file

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 includes plug-ins for IBM HTTP Server for iSeries 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

WebSphere Application Server Version 6 application server instances contain an SSL key file. The pathname for the key file is user_root/profile_name/etc/plugin-key.kdb, where user_root is your profile installation directory. The default location is /QIBM/UserData/WebSphere/AppServer/V6/edition/profiles.

The plugin-key.kdb file contains a digital certificate. The digital certificate 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. The default Web container is created with such an HTTPS transport.

This default HTTPS transport should be removed or reconfigured to replace the product-provided certificates before putting the server into production. 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

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 article is V5R3M0.

   Warning: You may need to renew digital certificates signed by the Digital Certificate Manager local certificate authority before proceeding. See WebSphere Application Server Technical Notes for more information.

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 Continue.
   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 (or your profile installation location) for the certificate store:

      /QIBM/UserData/WebSphere/AppServer/V6/edition/profiles/
      profile_name/etc/myplugin-key.kdb

      The remainder of these instructions refers to the directory above etc as user_root/profile_name.

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

4. Select the certificate store
   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_root/profile_name/etc/myplugin-key.kdb) and the password. Click Continue.

5. 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.

6. Disable all trusted signers except the Local CA:
   1. On the left pane, click Fast Path.
   2. Select Work with CA certificates and click Continue.
   3. On the Work with CA Certificates page, for all CA certificates except the LOCAL_CERTIFICATE_AUTHORITY, select the certificate and then click Disable. Respond with Yes when asked if you are sure you want to disable this certificate.

7. 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 Local CA certificate on your PC.
   2. In the right pane, click Copy and paste certificate.
   3. Create text file user_root/profile_name/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 default instance, and your workstation's F: drive is mapped to the iSeries system, the path is F:\QIBM\UserData\WebSphere\AppServer\V6\Base\profiles\profile_name\ 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 DefaultSSLSettings. You can use DefaultSSLSettings for testing or create new SSL configuration repertoires for production applications and associate them with individual resources. For more information, see Creating a Secure Sockets Layer repertoire configuration entry.

Configuring SSL for the application server's HTTPS transport

To configure SSL for the application server's HTTPS transport, 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. IBM recommends 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 Starting the key management utility (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_root/profile_name/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_root/profile_name/etc/myplugin-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_root/profile_name/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 OS/400 Change Authority (CHGAUT) command:

• appServerKeys.jks

  PROFILE	ACCESS
  *PUBLIC	*EXCLUDE
  QEJBSVR	*R

• myplugin-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 iSeries. 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 myplugin-key.kdb to the QTMHHTTP user profile, run the Change Authority (CHGAUT) command. For example:

  CHGAUT OBJ('/QIBM/UserData/WebSphere/AppServer/V6/Base/profiles/default/etc/myplugin-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.

Step 6: Modify the Web server plug-in file

Use the administrative console to modify the plugin-cfg.xml file. You must specify the local path to the myplugin-key.kdb file in the plugin-cfg.xml file.

1. Click Servers --> Web servers --> Web_server_name.

2. Under Additional properties, click Plug-in properties --> Custom properties.

3. Click New and add the property information for the keyring location. Enter the following information for the keyring location:
   • Name: KeyringLocation
   • Value: user_root/profile_name/etc/myplugin-key.kdb

4. Click Save at the top of the administrative console panel to save all of your changes.

If you want to access the Web server plug-in from the Web server, click Servers --> Web servers --> Web_server_name, and then click the Generate Plug-in option.

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 (myplugin-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. Specify the certificate the plugin is to use for authenticating to the Web container

   1. In the left hand pane of the administrative console, expand Servers and click Web servers.

   2. Click your Web server's name

   3. Click the Configuration tab

   4. Click Plug-in properties

   5. Under Additional Properties click Custom Properties

   6. Click New

   7. Enter certLabel for the property name and for the property value enter the label you used when importing the self signed certificate into the plugin's key store

   8. Click OK

   9. Save your changes

10. Regenerate the Web plugin configuration file.

11. Restart the Web server.

Related concepts
Secure Sockets Layer

Related tasks
Managing digital certificates
Creating a Secure Sockets Layer repertoire configuration entry

Related reference
Port number settings in WebSphere Application Server versions