Configuring SSL (TLS) for remote JCICSX API development

When configuring a Liberty JVM server in CICS® for remote JCICSX API development, you can configure it to use SSL for data encryption.

• For system programmers, configure the remote Liberty JVM server as follows:
  As a system programmer, you need to generate a certificate for the remote Liberty JVM server with its host name registered.
  1. Register the host name of the remote server in the server.xml file.
     By default the host name of the Liberty server is localhost. In this case your SSL connection will fail because the certificate will be registered to localhost while your client will be trying to connect to the host name of your CICS region. To override the default localhost host name, add the defaultHostName variable to your server.xml file:

     <variable name="defaultHostName" value="your-hostname"/>

     where your-hostname is the host name of the remote Liberty JVM server. For more information, see Setting the default host name of a Liberty server.
  2. Generate a new copy of the remote Liberty JVM server's public certificate.
     After setting the default host name of your server, you must regenerate the certificate for it.

     1. Stop the Liberty JVM server.
     2. Delete the Java keystore that stores the certificates. It is the key.p12 file located in {server.config.dir}/resources/security.
     3. Start the liberty server.
     4. Verify that a new key.p12 file is regenerated.
  3. Verify that the host name is correct in the certificate using OpenSSL or the Java keytool utility:
     • If you're using OpenSSL, input this command to show the certificates of the remote Liberty JVM server:

       $ openssl s_client -showcerts -connect remotejcicsxserver.com:portNo

     • If you're using the Java keytool utility:
       1. Navigate to the folder of the keystore on the remote Liberty server at: {server.config.dir}/resources/security.
       2. If the local Liberty server is at 19.0.0.3 or later, which is the minimum version required to use the client-side tooling of remote JCICSX development, and that autoconfigure is enabled for the remote Liberty server to use SSL, the remote Liberty server will have created a keystore using default values. In this case, use this command to show the certificates stored in the auto-created Java keystore:

          keytool -list -keystore key.p12 -storepass defaultPassword -storetype PKCS12 -v

          Otherwise, substitute values in for storepass and storetype according to your custom configuration.
       3. In the output, verify that CN = your-hostname shows the host name of the remote JVM server, instead of the default localhost value. Otherwise, repeat Step 2.
• For application developers, configure the local Liberty JVM server to trust the remote server's public certificate as follows:
  By default, the local Liberty JVM server might refuse to connect to the remote Liberty JVM server because it does not trust the public certificate that the remote Liberty provides during the SSL handshake. Therefore, the application developer must download a copy of the certificate from the remote Liberty server and add it to the truststore used by the local Liberty server.
  1. Download a copy of the public certificate from the remote Liberty JVM server:

     To use OpenSSL:

     1. Run the following command to show the certificates of the remote server, where your-hostname and your-port are the host name and port number of your remote Liberty JVM server:

        openssl s_client -showcerts -connect your-hostname:your-port

     2. From the output, copy the first certificate. Include the following lines and the information between these lines:

        "-----BEGIN CERTIFICATE-----"
        "-----END CERTIFICATE-----"

     3. Paste the certificate into a new file with a .cer extension, for example, publicKey.cer.
        Note: Note: Be sure not to include additional lines in this file; otherwise the certificate won't be added to you local Liberty truststore successfully.

     If you have access to the remote Liberty server, you can also use the Java keytool utility to download the certificate:

     1. Navigate to the keystore on your remote Liberty JVM server. The file path is {server.config.dir}/resources/security/key.p12.
     2. Use the Java keytool utility to create a public certificate:

        keytool -rfc -export -keystore key.p12 -alias default -file /your/save/location/public-remote.cer -v -storepass yourKeyStorePassword -storeType yourType

        where yourType is the keystore type, which defaults to PKCS12. For more information, see Liberty default keystore type changed to PKCS12.

  2. Navigate to the folder of the keystore on the local Liberty JVM server: {server.config.dir}/resources/security.
  3. Import the public certificate that the system programmer downloaded into the truststore of the local Liberty, using the following command:

     keytool -importcert -file /cert/location/public-remote.cer -keystore key.p12 -storepass localPassword -storetype yourType -trustcacerts -v

     where yourType is the keystore type, which defaults to PKCS12. For more information, see Liberty default keystore type changed to PKCS12.
  4. Restart the local Liberty JVM server to pick up the new certificate.