How to configure TLS with RACF key rings

Configure a IBM z/OS Connect server so that clients must connect by using an HTTPS connection with TLS server authentication.

About this task

This configuration creates the following artifacts:

• A certificate authority (CA) signed personal RACF certificate for a IBM z/OS Connect server to identify itself on TLS connections.
• A RACF key ring to act as the server's keystore.
• A Java KeyStore (JKS) for a client to use as its truststore so that it can trust the certificate that is presented by the IBM z/OS Connect server on the TLS connection.

You can also configure TLS client authentication, sometimes referred to as mutual TLS authentication, to require the client to provide its personal certificate on the connection. This configuration creates the following artifacts:

• A CA signed personal certificate for the client to identify itself on the TLS connections.
• A JKS to act as the client's keystore.
• A RACF key ring for the IBM z/OS Connect server to use as its truststore so that it can trust the certificate that is presented by the client.

The certificates, key rings, and JKS files that are used in this task are described in Figure 1.

This task makes the following assumptions:

• RACF is the security manager for the IBM z/OS Connect server. If you are using an alternative External Security Manager, refer to the appropriate product documentation for the equivalent commands.
• The client, which might be an intermediate server such as an API Gateway, can use JKS files for its keystore and truststore. This task uses a JKS for the client, but other keystore types or SAF key rings might be used depending on the client and the operating system that it runs on.
• The keytool command is used to create the certificates and JKS files for the client. The IBM z/OS Connect server uses a single RACF key ring for both its keystore and truststore. An alternative method is to use a separate RACF key ring for each role.
• The client uses separate JKS files for its keystore and truststore.
• The default IBM z/OS Connect SSL elements in the server.xml configuration file are customized. This method is typical for configuring TLS on the IBM z/OS Connect server's default HTTPS port. If you are configuring TLS for an additional HTTPS port, follow these instructions, but replace the default id attribute values of the ssl and keyStore elements with customized values. You would also need to associate the customized ssl element with the appropriate httpEndpoint element by configuring the sslOptions subelement. For example,

  <httpEndpoint id="myHttpEndpoint" host="*" 
      httpPort="9081" httpsPort="9444"> 
          <sslOptions sslRef="mySSLConfig" /> 
  </httpEndpoint>

In this example, mySSLConfig is the id attribute value of the ssl element.

Note: The term label is used by RACF and alias is used by JKS to reference the same artifact, therefore in this documentation, the phrase label or alias is used for clarity.

In the following steps, you configure the TLS connection between the IBM z/OS Connect server (steps 1 - 5) and the client (steps 6 - 9). Finally, you configure the IBM z/OS Connect server to use the RACF key ring (steps 10 - 13).

Enter the RACF commands from the z/OS LPAR where the IBM z/OS Connect server is hosted.

1. Create a RACF key ring for the IBM z/OS Connect server to use as its keystore.
   Enter the following command:

   RACDCERT ID(ZCSERV1) ADDRING(Keyring.ZOSCONN)

   The command uses the following values:

   • ZCSERV1 is the user ID that owns the key ring. The user ID under which the IBM z/OS Connect server runs must have READ access to this key ring. Either specify the server's user ID on the ID property or ensure that the server's user ID has READ access to the key ring owned by an alternative user ID.
   • Keyring.ZOSCONN is the name of the key ring to be created.
2. Create a CA certificate for the IBM z/OS Connect server.
   1. Create a self-signed RSA key pair to act as a CA certificate. A key pair consists of a public and private key.
      Enter the following command:

      RACDCERT GENCERT CERTAUTH SUBJECTSDN(CN('CA for zosConnect') O('IBM') OU('zosConnect') C('US')) SIZE(2048) WITHLABEL('zosConnectCA') NOTAFTER(DATE(2029-12-31))

      The command uses the following values:

      • CN('CA for zosConnect') O('IBM') OU('zosConnect') C('US') is an example distinguished name (DN) for the certificate.
      • zosConnectCA is the label or alias of the certificate.
      • 2029-12-31 is the expiry date of the certificate.
   2. Connect (add) the CA certificate to the key ring.
      Enter the following command:

      RACDCERT ID(ZCSERV1) CONNECT(RING(Keyring.ZOSCONN) LABEL('zosConnectCA') CERTAUTH)

      The command uses the following values:

      • ZCSERV1 is the user ID that owns the key ring.
      • Keyring.ZOSCONN is the name of the key ring.
      • zosConnectCA is the label or alias of the certificate to be connected to the key ring.
3. Create a personal certificate, signed by the CA certificate, for the IBM z/OS Connect server.
   1. Create an RSA key pair for the IBM z/OS Connect server signed by the CA certificate.
      Enter the following command:

      RACDCERT ID(ZCSERV1) GENCERT SUBJECTSDN(CN('myServer.host.com') O('IBM') OU('zosConnect') C('US')) SIZE(2048) SIGNWITH(CERTAUTH LABEL('zosConnectCA')) WITHLABEL('zosConnectServerCert') NOTAFTER(DATE(2029-12-31))

      The command uses the following values:

      • CN('myServer.host.com') O('IBM') OU('zosConnect') C('US') is an example distinguished name (DN) for the certificate. The common name (CN) value is typically the hostname of the z/OS LPAR that hosts the IBM z/OS Connect server.
      • zosConnectCA is the label or alias for the CA certificate that is used to sign the personal certificate.
      • zosConnectServerCert is the label, or alias, for the personal certificate to be created and signed.
   2. Connect (add) the personal certificate to the key ring.
      Enter the following command:

      RACDCERT ID(ZCSERV1) CONNECT(RING(Keyring.ZOSCONN) LABEL('zosConnectServerCert'))

      The command uses the following values:

      • ZCSERV1 is the user ID that owns the key ring.
      • Keyring.ZOSCONN is the name of the key ring.
      • zosConnectServerCert is the label or alias of the personal certificate to be connected to the key ring.
4. Confirm that the key ring and certificates were created correctly.
   1. List the certificates in the key ring.
      Enter the following command:

      RACDCERT ID(ZCSERV1) LISTRING(Keyring.ZOSCONN)

      The following screen capture shows the expected response:

      Ring:
           >Keyring.ZOSCONN<
      Certificate Label Name             Cert Owner     USAGE      DEFAULT
      --------------------------------   ------------   --------   -------
      zosConnectCA                       CERTAUTH       CERTAUTH     NO 
      zosConnectServerCert               ID(ZCSERV1)    PERSONAL     NO

   2. List the details of the CA certificate.
      Enter the command:

      RACDCERT CERTAUTH LIST(LABEL('zosConnectCA'))

      The expected response contains the following information:

      Issuer's Name: 
            >CN=CA for zosConnect.OU=zosConnect.O=IBM.C=US< 
      Subject's Name:
            >CN=CA for zosConnect.OU=zosConnect.O=IBM.C=US<

   3. List details of the IBM z/OS Connect server's personal certificate.
      Enter the command:

      RACDCERT ID(ZCSERV1) LIST(LABEL('zosConnectServerCert'))

      The expected response contains the following information:

      Issuer's Name:
            >CN=CA for zosConnect.OU=zosConnect.O=IBM.C=US< 
      Subject's Name:
            >CN=myServer.host.com.OU=zosConnect.O=IBM.C=US<

5. Export the IBM z/OS Connect server's CA certificate, containing the public key, to a z/OS sequential file.
   Enter the following command:

   RACDCERT CERTAUTH EXPORT(LABEL('zosConnectCA')) DSN('ZCSERV1.CERTS.ZCCA') FORMAT(CERTDER)

   The command uses the following values:

   • zosConnectCA is the label or alias for the CA certificate.
   • 'ZCSERV1.CERTS.ZCCA' is the name of the target z/OS sequential file.
   • CERTDER specifies a DER encoded X.509 certificate.

In the following steps, you configure the TLS connection on the client.

6. Prepare to use the keytool command.
   1. Create a directory to contain the certificates and JKS files to be created by the keytool command.
      In a later step, you copy those files to other locations, so if you run the keytool command on z/OS, make the location a z/OS UNIX System Services (USS) directory. For example, /u/myuser/zOSConnectJKS.
   2. Add the keytool command to the PATH environment variable.
      For example,

      export PATH=$PATH:<javaInstallPath>/bin

      The value <javaInstallPath> is the installation path of the IBM SDK for z/OS that includes the keytool command.
7. Import the CA certificate used to sign the IBM z/OS Connect server's personal certificate into the client's JKS truststore as a trusted certificate.
   1. Transfer in binary format, the z/OS sequential file 'ZCSERV1.CERTS.ZCCA' containing the exported CA certificate to the client's workstation.
      The method that you use depends on the operating system on which the client is running and the file transfer utilities you have access to. You might be able to FTP to the z/OS LPAR and get the z/OS sequential file directly, or you might first need to copy the z/OS sequential file to a USS file, and then get the USS file. For example,

      cp "//'ZCSERV1.CERTS.ZCCA'" /u/myuser/zOSConnectJKS/zosConnectCA.cer
   2. Name the CA certificate file that you received onto the client system as zosConnectCA.cer
   3. Enter the following command from the USS directory you created in step 6.
      keytool -importcert
          -file zosConnectCA.cer
          -alias zosConnectCA
          -keypass passw0rd
          -keystore clientTrust.jks
          -storepass passw0rd
          -storetype jks
      

      The command uses the following values:

      • zosConnectCA is the alias to be given to the CA certificate to be imported.
      • zosConnectCA.cer is the name of the certificate file that contains the public key of the CA certificate to be imported.
      • clientTrust.jks is the name of the JKS file into which the certificate is to be imported. This file is used as the client's truststore.

      The command creates the JKS file if it does not exist and issues the following prompt:

      Trust this certificate? [no]:

      Enter yes in response.
8. Check that the CA certificate was added to the client's truststore correctly.
   List the contents of the client's truststore by issuing the following command from the USS directory you created in step 6.

   keytool -list -v -keystore clientTrust.jks

   The expected response contains the following information:

   Your keystore contains 1 entry
   Alias name: zosconnectca
   Entry type: trustedCertEntry
   Owner: CN=CA for zosConnect, OU=zosConnect, O=IBM, C=US
   Issuer: CN=CA for zosConnect, OU=zosConnect, O=IBM, C=US

9. Make the client's truststore JKS file available to the client.
   In this task, the client's truststore is called clientTrust.jks. Transfer this file in binary mode to the workstation that hosts the client. The instructions for configuring your client to use these JKS files depend on your client application. For more information, see the documentation for the client application.

In the following steps, you configure the IBM z/OS Connect server to use the RACF key ring.

10. Configure the HTTPS port for the IBM z/OS Connect server.
    Identify an unused TCP/IP port on your z/OS LPAR, which can be used as the HTTPS port for IBM z/OS Connect . Specify the port value on the httpsPort attribute of the httpEndpoint element in the server.xml configuration file.

    For example, to use 9443 as the default HTTPS port, add the following element to the configuration:

    <httpEndpoint id="defaultHttpEndpoint" host="*"
        httpPort="9080" httpsPort="9443"/>

11. Configure the IBM z/OS Connect server to require HTTPS requests.
    Set the attribute requireSecure="true" in the server.xml configuration file to force all requests at that scope to use an HTTPS connection. This attribute can be set at different scopes:

    • To require an HTTPS connection globally for the server, set requireSecure="true" on the zosconnect_zosConnectManager element in the server.xml configuration file. For example,

      <zosconnect_zosConnectManager requireSecure="true" ... />

    • To require an HTTPS connection for a specific API, set requireSecure="true" on the zosConnectAPI element in the server.xml configuration file. For example,

      <zosconnect_zosConnectAPIs> 
          <zosConnectAPI name="Api1" requireSecure="true"/>
      </zosconnect_zosConnectAPIs>

      This setting takes precedence over the global setting.
    • To require an HTTPS connection for a specific service, set requireSecure="true" on the service element in the server.xml configuration file. For example,

      <zosconnect_services>
          <service name="Service1" requireSecure="true"/>
      </zosconnect_services>

      This setting takes precedence over the global setting.

    For more information about these elements, see Configuration elements in the Reference section.
12. Configure the SSL configuration to be used by the IBM z/OS Connect server.
    Create an ssl repertoire element in the server.xml configuration file, with default values for the id and keyStoreRef attributes. For example,

    <ssl id="defaultSSLConfig"
        keyStoreRef="defaultKeyStore" />

    For more information about the ssl repertoire element, see the Server configuration section in the IBM WebSphere® Application Server for z/OS Liberty documentation.

    The server now has only a keystore. Because it does not yet have any trusted certificates, it does not require a truststore.

13. Configure the IBM z/OS Connect server to reference the RACF key ring that contains the server's personal certificate and CA certificate.
    Create a keyStore element in the server.xml configuration file. For example,

    <keyStore id="defaultKeyStore"
        fileBased="false"
        location="safkeyring:///Keyring.ZOSCONN"
        password="password"
        readOnly="true"
        type="JCERACFKS" />

    The element uses the following values:

    • defaultKeyStore must match the value that is specified on the keyStoreRef attribute of the ssl element.
    • The location value must be the RACF key ring that acts as the server's keystore.
    • The password attribute is mandatory, so a value must be specified. However, the value is not used when type="JCERACFKS" because RACF key rings are not secured with passwords.

In the following steps, you configure TLS client authentication for the client.

1. Create a self-signed certificate for the client.
   Generate a self-signed RSA key pair for the client and add them to a JKS file, which acts as the client's keystore. Enter the following command from the USS directory you created in step 6 of How to configure a TLS connection between IBM z/OS Connect and the client

   keytool -genkeypair
       -alias clientCert
       -dname "CN=myClient.host.com, O=IBM, C=US"
       -keyalg RSA
       -keypass passw0rd
       -keysize 2048
       -keystore clientKey.jks
       -storepass passw0rd
       -validity 365
   

   The command uses the following values:

   • clientCert is the alias of the personal certificate to be created.
   • CN=myClient.host.com, O=IBM, C=US is an example distinguished name (DN) for the certificate. The CN value is typically the host name of the client that owns the certificate.
   • clientKey.jks is the name of the JKS file to be dynamically created to act as the client's keystore.

   This command creates the JKS file if it does not exist.
2. Sign the client's personal certificate with a CA certificate.
   A certificate signing request (CSR) is created for the self-signed personal certificate and sent to a certificate authority (CA). The CA verifies the request and returns a CA signed version of the personal certificate, a CA root certificate and optionally, an intermediate certificate.
   1. Create a certificate signing request (CSR) for the personal certificate.
      Enter the following command from the USS directory you created in step 6 of How to configure a TLS connection between IBM z/OS Connect and the client.

      keytool -certreq
          -alias clientCert
          -keystore clientKey.jks
          -file clientCert.csr
          -storepass passw0rd
      

      The command uses the following values:

      • clientCert is the alias of the personal certificate to be signed.
      • clientKey.jks is the name of the JKS file that contains the personal certificate to be signed.
      • clientCert.csr is the name of the CSR file to be created.
   2. Send the CSR (clientCert.csr), to your preferred certificate authority with any additional details they require.
      The certificate authority returns a CA root certificate, the signed client's personal certificate, and optionally an intermediate certificate.
   3. Import the CA root certificate and if present, the intermediate certificate, into the client's JKS keystore.
      Enter the following command from the USS directory that you created in step 6 of How to configure a TLS connection between IBM z/OS Connect and the client.

      keytool -importcert
          -file clientCA.cer
          -alias clientCA
          -keypass passw0rd
          -keystore clientKey.jks
          -storepass passw0rd
          -storetype jks
      

      This command issues the following prompt:

      Trust this certificate? [no]:

      Enter yes in response.

      The command uses the following values:

      • clientCA is the alias to be given to the CA root certificate to be imported.
      • clientCA.cer is the name of the certificate file that is returned by the certificate authority. It contains the CA root certificate to be imported.
      • clientKey.jks is the name of the JKS file into which the certificate is to be imported. This file is the client's keystore.
   4. Import the signed client's personal certificate.
      Enter the following command from the USS directory that you created in step 6 of How to configure a TLS connection between IBM z/OS Connect and the client

      keytool -importcert
          -file clientCertSigned.cer
          -alias clientCert
          -keypass passw0rd
          -keystore clientTrust.jks
          -storepass passw0rd
          -storetype jks
      

      The command uses the following values:

      • clientCert is the alias to be given to the signed personal certificate to be imported. It must match the name of the original self-signed personal certificate, so that one is replaced in the keystore.
      • clientCertSigned.cer is the name of the certificate file that is returned by the certificate authority, and contains the signed personal certificate to be imported.
      • clientKey.jks is the name of the JKS file into which the certificate is to be imported. This is the client's keystore.
3. Confirm that the client's keystore and personal certificate are created correctly.
   Enter the following command from the USS directory that you created in step 6 of How to configure a TLS connection between IBM z/OS Connect and the client to list the contents of the client's keystore.

   keytool -list -v -keystore clientKey.jks

   The expected response should contain entries for the signed personal certificate with an Entry type of PrivateKeyEntry and, for the CA root certificate (and if applicable, the intermediate certificate), an entry with Entry type of trustedCertEntry.

4. Export the client's CA certificate (public key) to a certificate file.
   Enter the following command from the USS directory that you created in step 6 of How to configure a TLS connection between IBM z/OS Connect and the client.

   keytool -exportcert
       -alias clientCA
       -file clientCA.cer
       -keystore clientKey.jks
       -storepass passw0rd
       -storetype jks
   

   The command uses the following values:

   • clientCA is the alias of the CA certificate to be exported.
   • clientCA.cer is the name of the certificate file to be created.
   • clientKey.jks is the name of the JKS file from which the certificate is to be exported.
5. Make the client's keystore JKS file available to the client.
   The client's keystore that is created in this task is called clientKey.jks. Transfer this file in binary mode to the workstation that hosts the client. The instructions for configuring your client to use these JKS files depend on your client application. For more information, see the documentation for the client application.

In the following steps, you configure TLS client authentication for the IBM z/OS Connect server.

6. Connect the client's CA certificate (public key) to the IBM z/OS Connect server's RACF key ring truststore as a trusted certificate.
   1. Transfer the exported client's CA certificate in binary format to the z/OS LPAR where the IBM z/OS Connect server is hosted, as a z/OS sequential file.
      Name the created z/OS sequential file as 'ZCSERV1.CERTS.CLIENT'.

      The transfer method that you use depends on the operating system on which you ran the keytool command. You might be able to FTP to the z/OS LPAR and put the z/OS sequential file directly, or you may first need to FTP the file to a USS directory and then copy that USS file to be a z/OS sequential file. For example,

      cp /u/myuser/zOSConnectJKS/clientCA.cer "//'ZCSERV1.CERTS.CLIENTCA'"

   2. Import the client's CA certificate (public key) into RACF.
      Enter the following command

      RACDCERT ID(ZCSERV1) ADD('ZCSERV1.CERTS.CLIENTCA') WITHLABEL('clientCA') TRUST
   3. Connect (add) the client's CA certificate (public key) as a trusted (CERTAUTH) certificate to the RACF key ring used by the IBM z/OS Connect server as its truststore.
      Enter the following command:

      RACDCERT ID(ZCSERV1) CONNECT(RING(Keyring.ZOSCONN) LABEL('clientCA') USAGE(CERTAUTH))
7. Confirm that the client's CA certificate is connected to the IBM z/OS Connect server's key ring correctly.
   Enter the following command to list the certificates in the key ring:

   RACDCERT ID(ZCSERV1) LISTRING(Keyring.ZOSCONN)

   This screen capture shows the expected response:

   
   Ring:
        >Keyring.ZOSCONN<
   Certificate Label Name             Cert Owner     USAGE      DEFAULT
   --------------------------------   ------------   --------   -------
   zosConnectCA                       CERTAUTH       CERTAUTH     NO 
   zosConnectServerCert               ID(ZCSERV1)    PERSONAL     NO
   clientCA                           ID(ZCSERV1)    CERTAUTH     NO

8. Edit the SSL configuration to be used by the IBM z/OS Connect server.
   Edit the existing ssl repertoire element in the server.xml configuration file, to add a trustStoreRef attribute with the default value. Set client authentication as required by setting clientAuthentication="true". For example,

   <ssl id="defaultSSLConfig" 
       keyStoreRef="defaultKeyStore" 
       trustStoreRef="defaultTrustStore" 
       clientAuthentication="true" />

9. Create a keyStore element in the server.xml configuration file for the IBM z/OS Connect server's truststore.
   The keyStore element is also used for truststores. For example,

   <keyStore id="defaultTrustStore"
       fileBased="false"
       location="safkeyring:///Keyring.ZOSCONN"
       password="password"
       readOnly="true"
       type="JCERACFKS" />

   The element uses the following values:

   • defaultTrustStore must match the value that is specified on the trustStoreRef attribute of the ssl element.
   • The location value must be the RACF key ring that acts as the server's truststore.
   • The password attribute is mandatory, so a value must be specified. However, the value is not used when type="JCERACFKS" because RACF key rings are not secured with passwords.
10. Start, or restart the server if it was already running, to pick up the changes.
    The messages.log file should contain the following message:

    CWWKO0219I: TCP Channel defaultHttpEndpoint-ssl has been started and is now listening for requests on host * (IPv6) port 9443

    The message uses the following values:

    • defaultHttpEndpoint-ssl is the id attribute value of the httpEndpoint element followed by -ssl.
    • * is the value of the httpEndpoint element host attribute.
    • 9443 is the value of the httpEndpoint element httpsPort attribute.