How to configure TLS with RACF key rings

About this task

Configure a z/OS Connect server so that CICS, IMS, or z/OS applications must connect by using an HTTPS connection with TLS server authentication. This configuration creates the following artifacts:

• A certificate authority (CA) signed personal certificate for a IBM z/OS Connect server to identify itself on TLS connections.
• A RACF key ring to act as the IBM z/OS Connect server’s keystore.
• A RACF key ring to act as the keystore for the CICS, IMS, or the z/OS application, so that it can trust the certificate 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 CICS, IMS, or z/OS application to provide its personal certificate on the connection. This configuration creates the following artifacts:

• A CA signed personal certificate for the CICS, IMS, or z/OS application to identify itself on TLS connections.
• A RACF key ring for the CICS, IMS, or z/OS application.
• 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 CICS, IMS, or z/OS application.

The certificates and key rings used in this task are described in Figure 1.

This task makes the following assumptions:

• RACF is the security manager. If you are using an alternative External Security Manager, refer to the appropriate product documentation for the equivalent commands.
• The CICS, IMS, or z/OS application, and the IBM z/OS Connect server each uses a single RACF key ring for both their own keystores and truststores.
• The default z/OS Connect SSL elements in the server.xml configuration file are customized. This method is typical for configuring TLS on the 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:

• This task covers TLS server authentication, and TLS client authentication (optional). It does not include the additional configuration to map a CICS, IMS, or z/OS application's personal certificate to a RACF user ID to authenticate with a IBM z/OS Connect server, but is a prerequisite to that task. For more information about configuring a CICS, IMS, or z/OS application certificate to authenticate with a z/OS Connect server, see How to configure client certificate authentication with RACF.
• The term label is used by RACF, however the term alias is often used to reference the same artifact. Therefore in this documentation, the phrase label or alias is used for clarity.

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 the 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 the z/OS Connect Server.
   1. Create an RSA key pair for the 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 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 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. Configure the HTTPS port for the z/OS Connect Server.
   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 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"/>

6. Configure the 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. For example,

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

   • To require an HTTPS connection for all API requesters, set requireSecure="true" on the zosconnect_apiRequesters element. For example,

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

   • To require an HTTPS connection for a specific API requester, set requireSecure="true" on the apiRequester element. For example,

     <zosconnect_apiRequesters> 
         <apiRequester name="Stock_Control" requireSecure="true"/>
     </zosconnect_apiRequesters>

     This setting takes precedence over the global setting.

   For more information about these elements, see zosConnect-2.0 Configuration elements in the Reference section.
7. Configure the SSL configuration to be used by the 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 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.

8. Configure the 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="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.
9. Exchange the z/OS Connect server's CA certificate with the CICS, IMS or z/OS application.
   Work with your security administrator of the CICS, IMS or z/OS application to export the IBM z/OS Connect server's CA certificate and add it to the CICS, IMS or z/OS application RACF key ring. This will allow the CICS, IMS or z/OS application to trust the certificate sent from the z/OS Connect server.
   For CICS, see How to configure TLS from CICS.
   For IMS or a z/OS application, see How to configure AT-TLS from an IMS or z/OS application.

The following steps are optional, and are only required to configure TLS client authentication. This is also called mutual TLS authentication.

10. Exchange the CA certificate of the CICS, IMS or z/OS application with the IBM z/OS Connect server.
    The CICS, IMS or z/OS application must create a personal certificate, signed by a CA certificate, and stored in a RACF key ring.
    Work with your security administrator of the CICS, IMS or z/OS application to export the CICS, IMS or z/OS application's CA certificate and add it to the z/OS Connect server's truststore. This will allow the z/OS Connect server to trust the certificate sent from the CICS, IMS or z/OS application.
    For CICS, see How to configure TLS from CICS.
    For IMS or a z/OS application, see How to configure AT-TLS from an IMS or z/OS application.
11. Edit the SSL configuration to be used by the 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" />

12. Create a keyStore element in the server.xml configuration file for the 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="mypassword"
        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.
13. 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.