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 a RACF® keyring.
About this task
Enabling SSL in a Liberty JVM server requires adding the
transportSecurity-1.0 Liberty feature, a keystore, and an HTTPS port. 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(2048)
WITHLABEL('CICS-Sample-Certification')
The SIZE of the certificate should be a minimum of 2048 bits. For more information, see the
RACF RACDCERT GENCERT (Generate certificate) command.
-
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(2048)
SIGNWITH (CERTAUTH LABEL('CICS-Sample-Certification'))
WITHLABEL('<userid>-Liberty-Server')
The SIZE of the certificate should be a minimum of 2048 bits. For more information, see the
RACF RACDCERT GENCERT (Generate certificate) command.
-
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
location="safkeyring://<userid>/<keyring>"
.
Note: If you are running Java 11, the location must be
location="safkeyringjce://<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>transportSecurity-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.