This document is intended for technical staff with a basic understanding of HTTPS, PKI and Certificates Authorities.
The purpose of this document is to support WebSphere and IFS Applications configurations for medium or high level of network security with HTTPS (SSL/TLS) secure communication protocols.
HTTPS Server Authentication of Web Server outlines how to configure the Web Server to perform Server Authentication. This often required in medium and high level security installation. This option designed to make it impossible for external parties to eavesdrop or modify communication between web browser and Web Server.
HTTPS Server Authentication of Application Server outlines how to configure the Application Server to perform Server Authentication. This is a high level security option designed to make it impossible to eavesdrop or modify communication between Web Server and Application Server. This option is useful in high-security DMZ configurations.
HTTPS Client Authentication of Web Server outlines how to configure the Web Server to perform Client Authentication when communicating with Application Server (i.e. Mutual Authentication). This is a high level security option designed to make it impossible for unauthorized parties to even be able to communication with Application Server. This option is provides highest level of network communication security, excellent for high-security DMZ configurations.
Image: A complete WebSphere SSL setup with two Server Certificates and one Client Certificate
When enabling HTTPS, must be enabled for both Web Browser <-> Web Server and Web Server <-> Application Server. This is due to Web Sphere plug-in requiring the same protocol to be used for the entire communication chain.
This means that a minimum of two server certificates are recommended/required; one for web server and one for application server.
Request certificates in due time to avoid delays due to Certificate Authority processing of request (refer to Working with Certificate Authorities).
As with any DMZ configuration, although a high level of network communication security is achieved using HTTPS, it is still advisable to only expose as little as possible to DMZ and external networks. This means for example that only necessary ports should be opened in firewalls, and that only necessary applications should be configured to be available from Web Server.
In order to perform these steps, the environment variable JAVA_HOME
must be set to an java installation, preferably a JDK 1.4.2 installation.
Environment variable PATH should be include the bin directory of the
java installation directory. The gsk7cmd command line interface or ikeyman graphical user interface
must be installed before requesting certificate. The IBM HTTPServer distribution
includes gskit.sh installation software for installing gsk7cmd.
This document assumes /opt/WebSphere/AppServer/etc/ssl to be
used for storing certificates etc on Application Server machine, and /opt/IBMIHS/ssl
to be used on Web Server machine.
| Server | Description |
|---|---|
| appserver_keystore.jks on Application Server | This file is a keystore; it contains the private key used to authenticate
Application Server to Web Server. File is in JKS (Java Keystore) format and is managed by keytool. |
| appserver_truststore.jks on Application Server
|
This file is a truststore; it contains the certificates allowed to authenticate
Web Server to Application Server. File is in JKS (Java Keystore) format and is managed by keytool. |
| ServerKey.kdb on Web Server
|
This file is a keystore; it contains the private key used to authenticate Web
Server to web browsers. File is in CMS (IBM .kdb files) format and is managed by gsk7cmd. |
| PluginKey.kdb on Web Server
|
This file works as a truststore; it contains a list of certificates trusted
by Web Server to authenticate Application Server. This file also works as a keystore; in SSL Mutual Authentication it contains the private key used to identify Web Server to Application Server. File is in CMS (IBM .kdb files) format and is managed by gsk7cmd. |
All required certificates should be requested early in order to have certificates available to complete SSL / TLS / HTTPS installation. Send Certificate Signing Requests (CSR) to an appropriate Certificate Authority (refer to Working with Certificate Authorities).
Carefully verify choice of key and signature algorithm
for gsk7cmd and keytool syntax to be compliant with Certificate
Authority recommendations,
as WebSphere plug-in as well as some browsers will not work with heterogeneous use of algorithms
(GSK_ERROR_BAD_CERT entries in IBM HTTP Server logs may indicate this
problem)
Note that keystores containing private keys are security critical, and also has a technical/financial value (the money, time and resources required to get a new certificate). Backing up keystores after generating private key is recommended.
The complete HTTPS setup for WebSphere looks as bellow:
Image: A complete WebSphere SSL setup with two Server Certificates and one Client Certificate
The most basic HTTPS setup (HTTPS Server Authentication of Web Server) only requires a Server Certificate for the Web Server.
A medium / high security DMZ configuration (HTTPS Server Authentication of Application Server) requires an additional Server Certificate for Application Server.
Finally, the most advanced configuration (HTTPS Client Authentication of Web Server) requires an Client Certificate for Web Server. However, it is possible to use a single certificate as Server Certificate and Client Certificate, so it possible to achieve the highest level of security with a single certificate / private key for web server.
When requesting certificates from Certificate Authority, it is important to state intended purpose (Server Certificate, Client Certificate or both).
Create the keystore appserver_keystore.jks which will be used to store Application Server private key. This is a secret file and SSL / TLS security relies on this file to remain confidential. This file should never be transmitted unencrypted and should only be available to trusted technical staff.
When creating the keystore and CSR, storepass and keypass must have the same value. dname must include CN=FullyQualifiedDomainName (a complete hostname such as ws-internal.example.com)
Note: Certificate Authority may have additional requirements which are not documented here.
Generate keystore and Certificate Signing Request (CSR) with two keytool commands:
keytool -genkey -alias AppServer -dname 'CN=ws-internal.example.com,o=websphere,c=us' -storepass
123456 -keypass 123456 -keystore appserver_keystore.jks
-keyalg RSA
keytool -certreq -alias AppServer -storepass 123456 -keypass
123456 -keystore appserver_keystore.jks -file
appserver_CertSignReq.csrFile appserver_CertSignReq.csr contains the CSR to be sent to Certificate Authority.
Create the keystore ServerKey.kbd which will be used to store Web Server private key. This is a secret file and SSL / TLS security relies on this file to remain confidential. This file should never be transmitted unencrypted and should only be available to trusted technical staff.
When creating the keystore and CSR, dn must include CN=FullyQualifiedDomainName (a complete hostname such as ws-webserver.example.com). This domain name is the domain name end-users will use to access the websphere installation.
Note: Certificate Authority may have additional requirements which are not documented here.
Generate keystore and Certificate Signing Request (CSR) with two gsk7cmd commands:
gsk7cmd -keydb -create -db ServerKey.kdb -pw 123456 -stashgsk7cmd -certreq -create -db ServerKey.kdb -pw
123456 -label "TEST CA - WebServer" -dn 'CN=ws-webserver.example.com,O=TEST,C=SE' -size
1024 -file webserver_CertSignReq.csrFile webserver_CertSignReq.csr contains the CSR to be sent to Certificate Authority.
Note: Command gsk7cmd -keydb -create
will insert a large number of commercial Certificate Authorities into keystore
by default.
This may be undesirable or forbidden by policies; if so utilize gsk7cmd -cert -list and gsk7cmd -cert -delete
to remove unwanted certificates.
If SSL Mutual Authentication is to be used between IBM HTTP Server and Application Server, this should be considered early on. There are two options: request a single certificate for dual purposes (may be used for Server and Client Authentication) or request an additional certificate to be used for Client Authentication. Consult Certificate Authority for pricing and guidelines.
How to configure HTTPS server authentication of web server is documented in IBM WebSphere info center. Following are the step to find the relevant IBM documentation.
How to configure HTTPS Server Authentication of Application Server is documented in IBM WebSphere info center. Following are the step to find the relevant IBM documentation.
This is the final step of enabling Mutual Authentication between Web Server and Application Server. HTTPS Server Authentication of Application Server should be configured before configuring HTTPS Client Authentication. How to configure HTTPS Client Authentication of Web Server is documented in IBM WebSphere info center. Following are the step to find the relevant IBM documentation.