Configuring SSL (TLS) for a Liberty JVM server using RACF

You can configure a Liberty JVM server to use SSL for data encryption, and optionally authenticate with the server by using a client certificate. Certificates can be stored in a Java™ keystore or in a SAF key ring such as RACF®.

About this task

Enabling SSL in a Liberty JVM server requires adding the ssl-1.0 Liberty feature, a keystore, and an HTTPS port. Configuring server.xml manually. You edit the server.xml file to add the required elements and values. You must follow the manual procedure if you want to use a RACF key ring.

It is important to understand that any web request to a Liberty JVM server uses the JVM support for TCP/IP sockets and SSL processing, not CICS® sockets domain.

Procedure

To manually configure SSL, you need to create a signing certificate. Use this signing certificate to create a server certificate. Then, export the signing certificate to the client web browser where it is used to authenticate the server certificate.

Create a certificate authority (CA) certificate (signing certificate). An example, using RACF commands, follows:

RACDCERT GENCERT 
  CERTAUTH 
  SUBJECTSDN(CN('CICS Sample Certification Authority')
   O('IBM')  
   OU('CICS'))
   SIZE(1024)
  WITHLABEL('CICS-Sample-Certification')

Create a server certificate that uses the signing certificate from step 2, where <userid> is the CICS region user ID. The hostname is the host name of the server that the Liberty server HTTPS port is configured to use.

RACDCERT ID(<userid>) GENCERT                                                                 
  SUBJECTSDN(CN('<hostname>') 
   O('IBM')  
   OU('CICS'))
   SIZE(1024)
   SIGNWITH (CERTAUTH LABEL('CICS-Sample-Certification'))
  WITHLABEL('<userid>-Liberty-Server')

Connect the signing certificate and server certificate to a RACF key ring.
You can use RACF with the following command, and replace the value of <keyring> with the name of the key ring you want to use. Replace the value of <userid> with the CICS region user ID.
```
RACDCERT ID(<userid>) CONNECT(RING(<keyring>)            
       LABEL('CICS-Sample-Certification')                  
       CERTAUTH)

RACDCERT ID(<userid>) CONNECT(RING(<keyring>)            
       LABEL('<userid>-Liberty-Server'))  
```
Export the signing certificate to a CER file:
```
RACDCERT CERTAUTH EXPORT(LABEL('CICS-Sample-Certification'))               
       DSN('<userid>.CERT.LIBCERT')
       FORMAT(CERTDER)  
       PASSWORD('password') 
```
FTP the exported certificate in binary to your workstation, and import it into your browser as a certificate authority certificate.

Edit the server.xml file and add the SSL feature, and the keystore. Set the HTTPS port (value is 9443 in the following example) and restart your CICS region. The SAF key ring must be specified in the URL form safkeyring://<userid>/<keyring>. The <userid> value must be set to the CICS region user ID and the <keyring> value must be set to the name of the key ring. The password field is not used for accessing the SAF key ring and must be set to password.

<featureManager>
  ... 
       <feature>ssl-1.0</feature>
</featureManager>
...
<httpEndpoint host="*" httpPort="9080" httpsPort="9443" 
    id="defaultHttpEndpoint"/>
...
. 
<keyStore filebased="false" id="racfKeyStore" 
        location="safkeyring://<userid>/<keyring>" 
        password="password" 
        readOnly="true" 
        type="JCERACFKS"/> 
<ssl id="defaultSSLConfig" keyStoreRef="racfKeyStore" 
      sslProtocol="SSL_TLS" 
      serverKeyAlias="<userid>-Liberty-Server" />

Results

SSL for a Liberty JVM server is successfully configured.