http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/rzamy/50/sec/secjsswa.

htm

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

Create an SSL key file without the default signer certificates

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

Grant access to the key files

(Optional) Configure an alias for the SSL port

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

(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:

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.

Create a local certificate authority.

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

Create a key store for the HTTP server plug-in:

In the left pane, click Create New Certificate Store.

Select Other System Certificate Store and click the Continue button.
 On the Create a Certificate in New Certificate Store page, select Yes -
Create a certificate in the certificate store, and click Continue.

On the Select a Certificate Authority (CA) page, select Local Certificate

Authority and click the Continue button.

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.

Set the default system certificate:

In the left pane, click to expand Fast Path.

Select Work with server and client certificates.

Select certificate MyPluginCert.

Click Set default.

Remove all trusted signers except the Local CA:

On the left pane, click Select a Certificate Store

Select Other System Certificate Store and click Continue.

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.

On the left pane, click Fast Path.

Select Work with CA certificates and click Continue.

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.
 Extract the Local CA certificate so that you can import the certificate into the
application server key file later:

In the left pane, click Install CA certificate on your PC.

In the right pane, click Copy and paste certificate.

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.

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.

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

Create a new key database file:

 Click Key Database File and select New.

Specify settings:

Key database type: JKS

File Name: appServerKeys.jks

Location: your etc directory, such as

USER_INSTALL_ROOT/etc

Click OK.

Enter a password (twice for confirmation) and click OK.

Delete all of the signer certificates.

Click Signer Certificates and select Personal Certificates.

Add a new self-signed certificate:

Click New Self-Signed to add a self-signed certificate.

Specify settings:

Key Label: appServerTest

Common Name: use the DNS name for your iSeries server

Organization: IBM

Click OK.

Extract the certificate from this self-signed certificate so that it can be imported
into the plug-in's SSL key file:

Click Extract Certificate.

Specify settings:

Data Type: Base64-encoded ASCII data

Certificate file name: appServer.arm

Location: the path to your etc directory

 Click OK.

Import the Local CA public certificate:

Click Personal Certificates and select Signer Certificates.

Click Add.

Specify settings:

Data Type: Base64-encoded ASCII data

Certificate file name: myLocalCA.txt

Location: the path to your etc directory

Click OK.

Enter plug-in for the label and click OK.

Click Key Database File.

Select Exit.

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

Start the Digital Certificate Manager (DCM)

On the left pane, click Select a Certificate Store

Select Other System Certificate Store and click Continue.

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.

On the left pane, click Fast Path.

Select Work with CA certificates and click Continue.

Click Import.

Specify USER_INSTALL_ROOT/etc/appServer.arm for the Import file field

value and click Continue.
 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

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 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 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:

Use iKeyman to create a keystore.

Create a self signed certificate in the keystore.

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

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

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

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

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.

Restart the application server.

 Regenerate the Web plugin configuration file.

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>

Restart the Web server.