How to configure a TLS connection with RACF key rings for IBM z/OS Connect zosConnect-3.0

About this task

This task provides instructions for one typical example use case. The steps are similar for other use cases and the instructions should be adapted for your environment and requirements. For example, the client may use RACF or an alternative External Security Manager key ring and certificate, or the client may use a self-signed certificate. This configuration creates the following artifacts:

• A certificate authority (CA) signed personal RACF certificate for z/OS Connect to identify itself on TLS connections.
• A RACF key ring to act as the server's keystore.
• A PKCS12 keystore for a client to use as its truststore so that it can trust the certificate that is presented by the 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 PKCS12 keystore to act as the client's keystore.
• A RACF key ring for z/OS Connect to use as its truststore so that it can trust the certificate that is presented by the client.

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

This task makes the following assumptions:

• RACF is the security manager for z/OS Connect. 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 PKCS12 keystore files for its keystore and truststore. This task uses a PKCS12 keystore 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 PKCS12 keystore files for the client. z/OS Connect 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 PKCS12 keystore files for its keystore and truststore.
• The default z/OS Connect SSL elements in the configuration file are customized. This method is typical for configuring TLS on the HTTPS port that is used by z/OS Connect. 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 PKCS12 keystore 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 z/OS Connect Server (steps 1 - 5) and the client (steps 6 - 9). Finally, you configure the z/OS Connect Server to use the RACF key ring (steps 10 - 13).

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

1. Create a RACF key ring for the 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 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 z/OS Connect Server. If a suitable CA certificate exists, skip this step.
   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 z/OS Connect Server.
   1. Create an RSA key pair for 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 z/OS Connect.
      • 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 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 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 create a truststore for the client containing the z/OS Connect Server's CA certificate as a trusted certificate.

6. Prepare to use the keytool command.
   1. Create a directory to contain the certificates and PKCS12 keystore 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/zOSConnectCerts.
   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 z/OS Connect personal certificate into the client's PKCS12 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/zOSConnectCerts/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 that you created in step 6.

      keytool -importcert -file zosConnectCA.cer -alias zosConnectCA -keypass <mypassword> -keystore clientTrust.p12 -storepass <mypassword>
       -storetype PKCS12

      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.p12 is the name of the PKCS12 keystore file into which the certificate is to be imported. This file is used as the client's truststore.

      The command creates the PKCS12 keystore 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 that you created in step 6.

   keytool -list -v -keystore clientTrust.p12

   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 PKCS12 keystore file available to the client.
   In this task, the client's truststore is called clientTrust.p12. Transfer this file in binary mode to the workstation that hosts the client. The instructions for configuring your client to use these PKCS12 keystore files depend on your client application. For more information, see the documentation for the client application.

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

10. Configure the HTTPS port for z/OS Connect.
    Identify an unused TCP/IP port on your z/OS LPAR, which can be used as the HTTPS port for z/OS Connect. Specify the port value on the httpsPort attribute of the httpEndpoint element in the 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. If you want all requests to z/OS Connect to use HTTPS, then configure the server to listen only on an HTTPS port.
    In the httpEndpoint element of the configuration file, set the httpPort attribute value to "-1".
12. Configure the SSL configuration to be used by z/OS Connect.
    Create an ssl repertoire element in the 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 WebSphere Application Server 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 z/OS Connect to reference the RACF key ring that contains the server's personal certificate and CA certificate.
    Create a keyStore element in the configuration file.
    For example,

    <keyStore id="defaultKeyStore"
        fileBased="false"
        location="safkeyring:///Keyring.ZOSCONN"
        password="mypassword"
        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.