How to configure a TLS connection with PKCS12 keystores

About this task

This configuration creates the following artifacts:

• A CA signed personal certificate for the z/OS Connect Server to identify itself during the TLS handshake.
• A PKCS12 keystore for the z/OS Connect Server to use as its keystore.
• A PKCS12 keystore for the client to use as its truststore so that it can trust the certificate that is presented by the z/OS Connect Server during the TLS handshake.

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 during the TLS handshake.
• A PKCS12 keystore for the client to use as its keystore.
• A PKCS12 keystore for z/OS Connect to use as its truststore so that it can trust the certificate that is presented by the client during the TLS handshake.

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

This task makes the following assumptions:

• 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 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.
• The client uses separate PKCS12 keystore files for its keystore and truststore.
• The z/OS Connect Server uses separate PKCS12 keystore files for its keystore and truststore.
• The default z/OS Connect SSL elements in the configuration file are customized to reference the PKCS12 keystores created in this task. 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="1234" httpsPort="9876"> 
          <sslOptions sslRef="mySSLConfig" /> 
  </httpEndpoint>

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

In the following steps, you configure the TLS connection between z/OS Connect (steps 1 - 5) and the client (steps 6 - 9). Finally, you configure z/OS Connect to use the PKCS12 keystore (steps 10 - 12).

1. Prepare to use the keytool command for the z/OS Connect Server.
   1. Create a directory to contain the certificates and PKCS12 keystore files to be created by the keytool command for the z/OS Connect Server.
      For example, /u/myuser/zOSConnectCerts.
   2. Add the keytool command to the PATH environment variable.
      For example,

      export PATH=$PATH:<javaInstallPath>/bin

      The value of <javaInstallPath> is the installation path of Java that includes the keytool command.
2. Create a self-signed certificate for the z/OS Connect Server.
   Generate a self-signed RSA key pair for the z/OS Connect Server and add them to a PKCS12 keystore file, which acts as the IBM z/OS Connect server's keystore. Enter the following command from the directory that you created in step 1:

   keytool -genkeypair -alias zosconnectcert -dname "CN=myServer.host.com, O=IBM, C=US" -keyalg RSA -keypass <mypassword> -keysize 2048 -keystore zosconnectKey.p12 -storepass <mypassword> -storetype PKCS12 -validity 365 

   The command uses the following values:

   • zosconnectcert is the alias of the personal certificate to be created.
   • CN=myServer.host.com, O=IBM, C=US is an example distinguished name (DN) for the certificate. The CN value is typically the hostname of the machine hosting the z/OS Connect Server that owns the certificate.
   • zosconnectKey.p12 is the name of the PKCS12 keystore file to be dynamically created to act as the z/OS Connect server's keystore. This command creates the PKCS12 keystore file if it does not exist.
3. Sign the z/OS Connect server'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 directory that you created in step 1:

      keytool -certreq -alias zosconnectcert -keystore zosconnectKey.p12 -file zosconnectcert.csr -storepass <mypassword> -storetype PKCS12

      The command uses the following values:

      • zosconnectcert is the alias of the personal certificate to be signed.
      • zosconnectKey.p12 is the name of the PKCS12 keystore file that contains the personal certificate to be signed.
      • zosconnectcert.csr is the name of the CSR file to be created.
   2. Send the CSR file (zosconnectcert.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 clients PKCS12 keystore.
      Enter the following command from the directory that you created in step 1:

      keytool -importcert -file zosconnectCA.cer -alias zosconnectca -keypass <mypassword> -keystore zosconnectKey.p12 -storepass <mypassword> -storetype PKCS12

      The command uses the following values:

      • zosconnectca is the alias to be given to the CA root certificate to be imported.
      • zosconnectCA.cer is the name of the certificate file that is returned by the certificate authority. It contains the CA root certificate to be imported.
      • zosconnectKey.p12 is the name of the PKCS12 keystore file into which the certificate is to be imported. This file is the z/OS Connect server's keystore.

      This command issues the following prompt:

      Trust this certificate? [no]: 
      

      Enter yes in response.
   4. Import the signed client's personal certificate.
      Enter the following command from the directory that you created in step 1:

      keytool -importcert -file zosconnectcertSigned.cer -alias zosconnectcert -keypass <mypassword> -keystore zosconnectKey.p12 -storepass <mypassword> -storetype PKCS12

      The command uses the following values:

      • zosconnectcert 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.
      • zosconnectcertSigned.cer is the name of the certificate file that the certificate authority returns, and contains the signed personal certificate to be imported.
      • zosconnectKey.p12 is the name of the PKCS12 keystore file into which the certificate is to be imported. This file is the z/OS Connect server's keystore.
4. Confirm that the z/OS Connect server's keystore and personal certificate are created correctly.
   Enter the following command from the directory that you created in step 1 to list the contents of the z/OS Connect server's keystore.

   keytool -list -v -keystore zosconnectKey.p12 -storepass <mypassword> -storetype PKCS12

   The response should contain entries for the signed personal certificate with an Alias name of zosconnectcert and Entry type of PrivateKeyEntry and, for the CA root certificate (and if applicable, the intermediate certificate), an entry with Entry type of trustedCertEntry.
5. Export the z/OS Connect servers CA certificate (public key) to a certificate file.
   Enter the following command from the directory that you created in step 1:

   keytool -exportcert -alias zosconnectca -file zosconnectCA.cer -keystore zosconnectKey.p12 -storepass <mypassword> -storetype PKCS12

   The command uses the following values:

   • zosconnectca is the alias of the CA certificate to be exported.
   • zosconnectCA.cer is the name of the certificate file to be created.
   • zosconnectKey.p12 is the name of the PKCS12 keystore file from which the certificate is to be exported.

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

6. Prepare to use the keytool command for the client.
   1. Create a directory to contain the certificates and PKCS12 keystore files to be created by the keytool command for the client. For example, /u/myuser/ClientCerts.
   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 Java that includes the keytool command.
7. Import the CA certificate used to sign the z/OS Connect server's personal certificate into the clients PKCS12 truststore as a trusted certificate.
   1. Obtain the z/OS Connect servers CA certificate.
      The z/OS Connect servers CA certificate that is created in this task is called zosconnectCA.cer. Transfer this file in binary mode into the directory that you created in step 6 on the workstation that hosts the client.
   2. Enter the following command from the 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 clients truststore. The command creates the PKCS12 keystore file if it does not exist.

      This command 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 directory that you created in step 6.

   keytool -list -v -keystore clientTrust.p12 -storepass <mypassword> -storetype PKCS12

   The response should contain entries for the CA certificate with an Alias name of zosconnectca and Entry type of trustedCertEntry.

9. Make the clients truststore PKCS12 keystore file available to the client.
   In this task, the client's truststore is called clientTrust.p12. The instructions for configuring your client to use this PKCS12 keystore file depend on your client application. For more information, see the documentation for the client application.

In the following steps, you configure the z/OS Connect to use the PKCS12 keystore and truststore.

10. Configure the HTTPS port for the z/OS Connect Server.
    Identify an unused TCP/IP port on your host machine, which can be used as the HTTPS port for the z/OS Connect Server. Specify the port value on the httpsPort attribute of the httpEndpoint element in the configuration file either by directly editing the configuration file or by specifying the value of the corresponding environment variable that is used in your environment.
    For example, to use 9443 as the HTTPS port for the defaultHttpEndpoint, add the following element to the configuration:

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

    Note: If you want all requests to the z/OS Connect Server to use HTTPS, then configure the server to only listen on an HTTPS port.

    In the httpEndpoint element of the configuration file, set the httpPort attribute value to "-1" to disable it.

11. Configure the SSL configuration to be used by the z/OS Connect Server.
    1. Enable the transportSecurity-1.0 feature.
       Add the <feature>transportSecurity-1.0</feature> to the featureManager element in the configuration file.
       For example,

       <featureManager>
           <feature>transportSecurity-1.0</feature>
           ...
       </featureManager> 

    2. Create an ssl repertoire element in the configuration file.
       For example, to use the default values for the id and keyStoreRef attributes:

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

       For more information about the ssl repertoire element, see SSL Repertoire (ssl) in the 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.
12. Configure the z/OS Connect Server to reference the PKCS12 keystore that contains the server's personal certificate and CA certificate.
    1. Copy the PKCS12 keystore file zosconnectKey.p12 to a directory which the user ID running the z/OS Connect Server has read access to.
       This example copies zosconnectKey.p12 to the z/OS Connect Server directory ${server.config.dir}/resources/security. This is a typical location for file system keystores.

       Note: You may configure a local shared volume that maps to the ${server.config.dir}/resources/security directory or your preferred location for file system keystores. In this case, copy the zosconnectKey.p12 file to the local mapped directory.
    2. Create a keyStore element in the configuration file to reference the zosconnectKey.p12 file.
       For example,

       
       <keyStore id="defaultKeyStore" 
           location="${server.config.dir}/resources/security/zosconnectKey.p12" 
           password="mypassword" 
           type="PKCS12" />

       The element uses the following values:

       • The id attribute value defaultKeyStore must match the value that is specified on the keyStoreRef attribute of the ssl element.
       • The location attribute value must be the fully qualified path to the PKCS12 keystore that acts as the server's keystore.
       • The password attribute is the password for the PKCS12 keystore.
       • The type attribute indicates the type of keystore.