TKE catcher configuration for a TLS connection

Edit online

Communication between the TKE workstation and the catcher.exe daemon (controlled by the CSUTKEcat script) can be sent through a plain TCP connection (TCP mode) or, starting with CCA 8.0, a TLS connection (TLS mode). In both modes, the TKE catcher.exe daemon listens on port 50003.

During installation and start-up, the CSUTKEcat script checks if TLS mode is possible by querying the OpenSSL version. If OpenSSL is installed as version 1.1.1 or newer, then the catcher daemon starts in TLS mode. Otherwise, it starts in TCP mode. The catcher performs the necessary configuration changes for running in either mode as necessary. However, if running in TLS mode, there is further set up required for use in a production environment, or if you want to switch back to TCP mode (the legacy connection used in CCA 7.x and earlier). This section describes how to switch between the TLS and TCP modes. It also describes the setup and configuration that the catcher daemon uses to establish a TLS connection to communicate with your TKE. This covers setup on the machine on which your catcher is running, and setup on the TKE with which you want to connect and communicate. The TKE information here is surface level. Use it in concert with the z/OS Cryptographic Services.

The catcher will check if the key and the certificate in the catcher.key and catcher.crt files are already in place and proceed depending on the results:

  • If they are both in place it continues as normal.
  • If neither is in place, then it generates its own ECC P521 key and certificate to be used and place them in the correct location.
  • If only one of the files is in place, but the other is missing, then the catcher sends an error message to the log and cancels the catcher startup.

Important upgrade note

  • When upgrading to CCA 8.0 from CCA 7.3 or earlier, the default catcher mode changes from TCP to TLS mode for systems with OpenSSL version 1.1.1 or later. This means that further setup is required to continue the communication between the catcher and the TKE.
    • You can achieve this either by setting the catcher mode back to TCP and then restarting the catcher daemon.
    • Or you can complete the TLS mode setup.

    Both tasks are described in subtopics within this information unit.

  • When setting the connection modes (TCP or TLS) for the TKE catcher, you must ensure that the TKE Host definition matches that mode. Do this by checking or unchecking the Enable SSL/TLS check box on the Create New Host or Change Host window of the Trusted Key Entry tool. See the "Enable TCP connection on the TKE" and "Enable TLS connection on the TKE" sections for more details.

Restrictions

When running in TLS mode, the catcher only uses TLS version 1.2 or higher.

Supported keys

  • RSA 1024 – 4096
    Note: You should only use RSA 2048 or stronger keys.
  • ECC
    • prime256v1
    • secp384r1
    • secp521r1

Dependencies

  • You must have OpenSSL installed on your system together with one of the following libraries:
    • libssl.so.1.1
    • libssl.so.3
  • See Distribution-specific information and the Release Notes for CCA 8.0 for information about distributions that support TLS mode. Additionally, you can check your OpenSSL library by running one of the following commands and comparing your output to the list of the previously listed libraries: 
    ls -l /usr/lib*/*/libssl.so*
ls -l <library_path>/libssl.so*

-rw-r--r-- 1 root root 659392 Oct 27 17:06 /usr/lib/s390x-linux-gnu/libssl.so.3

Important files

/etc/cca/catcher.conf
Configuration file for CCA catcher.exe daemon (CSUTKEcat): Used to switch between TCP mode and TLS mode.
/opt/IBM/CCA/bin/catcher.key
File containing the private key used by the catcher.exe daemon in the TLS connection.
If no such file exists, the catcher automatically generates one itself:
  • Generates an ECC secp521r1 key
  • Stores the file in PEM format.
Note: If file catcher.key is not found but file catcher.crt is found, then the catcher daemon will not generate either of them. Instead it will throw an error and shutdown.
Best practice for users is to replace the file catcher.key with their own key. After replacing the catcher key, users must restart the catcher daemon to ensure that their new key and certificate are in use.
/opt/IBM/CCA/bin/catcher.crt
File containing the certificate used by the catcher.exe daemon in the TLS connection.
If no such file exists, the catcher automatically generates one itself:
  • It creates this certificate using the key it generates and stores the certificate in the catcher.crt file.
  • This new certificate is self-signed.
  • This new certificate places the Server Hostname as the value of the Common Name attribute into the Subject Name field.
  • It also places the following values into the Subject Alternative Name field: IPv4 address, IPv6 address, Short Server Hostname.
  • This new certificate is stored in PEM format.
Note: If file catcher.crt is not found but file catcher.key is found, then the catcher daemon will not generate either of them. Instead it will throw an error and shutdown.
Best practice for users is to replace the automatically generated key and certificate with their own key and certificate. After replacing the catcher certificate, users must restart the catcher daemon to ensure their new key and certificate are in use. The certificate Subject Name, Common Name attribute, or Subject Alternative Name must contain a value that matches the Host Name/IP value used in your TKE host setup. This is usually your Server Hostname, but an IP address is also acceptable.

Setup for TLS mode

  1. Generate or otherwise acquire the TLS key and certificate you want to use:
    • The key and certificate must by in PEM format.
    • The Common Name (CN) attribute within the Subject tag of the certificate must match the host name/IP value used in your TKE host setup. This is usually your server hostname, but an IP address is also acceptable. You may put your hostname in the Common Name attribute within the Subject Name, and your IP address(es) in your Subject Alternative Name field.
    • Example 1 (RSA based):

      This example produces a self-signed certificate, which is only suitable for testing.

      openssl req -newkey rsa:2048 -nodes -keyout catcher.key -x509
            -days 365 -subj "/CN=<server hostname>"  
            -addext "subjectAltName = IP:<ip_address>" 
            -out catcher.crt
    • Example 2 (ECC prime256v1 based):

      Optional step: Use the following command to print details about the mechanism to use:

      openssl ecparam -list_curves | grep prime256v1
      The output may look similar to the following:
      prime256v1: X9.62/SECG curve over a 256 bit prime field
      Use the following commands to acquire key and certificate:
      openssl ecparam -out catcher.key -name prime256v1 -genkey
openssl req -new -key catcher.key -x509 -nodes -days 365 -subj "/CN=<server hostname>" 
            -addext "subjectAltName = IP:<ip_address>" 
            -out catcher.crt

      Optional step: Use the following command to display details about the generated certificate:

      openssl x509 -in catcher.crt -text -noout
  2. Place your key and certificate into the /opt/IBM/CCA/bin/ directory. Replace the auto-generated key and certificate if one was created by the catcher daemon.
    • Use the name catcher.key for the key file and the name catcher.crt for the certificate file.
    • Example: 
      cp catcher.key /opt/IBM/CCA/bin/catcher.key
cp catcher.crt /opt/IBM/CCA/bin/catcher.crt
  3. Restart the catcher daemon to ensure your new key and certificate are in use, for example: 
    systemctl restart CSUTKEcat
  4. Import your catcher certificate into your TKE:
    • This can be done in the following two ways:
      • Method 1: Physical media (USB stick) import
      • Method 2: Remote server import
    • Follow the instructions for your chosen import method in topic Importing the catcher certificate into the TKE.
  5. Start running the catcher in TLS mode (if not already running in this mode):
  6. Enable the TLS connection on the TKE:

Everything is set up now. Any communication between the TKE and the CCA TKE catcher will now go through TLS.

Importing the catcher certificate into the TKE

Method 1: Physical Media Import

  1. Format your USB stick using the TKE:
    1. Insert your USB stick into the TKE server.
    2. Starting on the TKE Welcome Page: Select the Launch the Trusted Key Entry Console web application link.
    3. Select Service Management in the left sidebar menu.
    4. Select Format Media on the Service Management page.
    5. Select the Trusted Key Entry data radio button in the Format Media window. Then select Format.
    6. Select your USB stick from the list on the Select Media Device window. Then select OK.
    7. Select the appropriate file system for your machines on the Specify File System window. Then select Format.
    8. Select Yes on the Format Media window when asked whether you are sure that you want to continue. You may need to wait a few seconds for the formatting to complete.
    9. Select OK on the Format Media Complete window.
    10. Now that the formatting is complete, eject your USB stick.
  2. Copy your catcher.crt file onto your USB stick.
  3. Import the catcher.crt file into the TKE:
    1. Insert your USB stick into the TKE server.
    2. Starting on the TKE Welcome Page: Select the Privilaged Mode Access link .
    3. Login with your user credentials.
    4. Select Service Management in the left sidebar menu.
    5. On the Service Management page, scroll down to the Configuration section and select Certificate Management.
    6. Select the drop-down menu Import on the Manage Trusted Signing Certificates window. Then select From Removable Media.
    7. Select your USB stick from the list on the Select Media Device window. Then select OK.
    8. Select the catcher.crt file from the right listing of files in the Certificate Management window. Then select OK. Confirm the informational dialog with OK: "The signing certificate(s) have been imported successfully."
    9. After the import has succeeded you see a Confirm Import window. Verify the displayed certificate information. Then select Yes to finalize the import.
    10. Your certificate has now been imported, and you should see it displayed in the Manage Trusted Signing Certificates window.
  4. Eject the USB stick.

Method 2: Remote Server Import

  1. If required, start running the catcher in TLS mode. Follow the steps described in topic Change the catcher to TLS mode.
  2. Starting on the TKE Welcome Page: Select the Privilaged Mode Access link.
  3. Login with your user credentials.
  4. Select Service Management in the left sidebar menu.
  5. On the Service Management page, scroll down to the Configuration section and select Certificate Management.
  6. Select the drop-down menu Import on the Manage Trusted Signing Certificates window. Then select From Remote Server.
  7. Enter the same IP/Host and Port you are using to connect to the catcher on the Import Remote Certificate window. Then select OK. You may see a Please wait... window while the certificate is acquired.
  8. After the import has succeeded, you should see a Confirm Import window. You must verify the shown certificate information, particularly the hashes, to ensure you are importing your certificate. Then select Yes to finalize the import.
  9. Your certificate has now been imported, and you should see it displayed in the Manage Trusted Signing Certificates window.

Change the catcher to TLS mode

Note: Starting with CCA 8.0, the default is TLS mode anyway.
  1. In the /etc/cca/catcher.conf file, change the line TLS_OFF to TLS_ON and save the file.
  2. Restart the catcher daemon. For example, enter the command: systemctl restart CSUTKEcat.
  3. [optional] Verify that the catcher is running in TLS mode:
    1. Check that the catcher.exe was started with the -tls option.
    2. Run the following command: ps -ax | grep catcher.exe. The output should show catcher.exe -tls (with the -tls option), otherwise you are running in TCP mode. For example: 
      $ ps -ax | grep catcher.exe
39518 ? Ss 0:00 /opt/IBM/CCA/bin/catcher.exe -tls

Enable TLS connections on the TKE

  1. Set up for TLS mode and change your catcher daemon to TLS mode, if required. Follow the instructions in topic Setup for TLS mode.
  2. Starting on the TKE Welcome Page: Select the Launch the Trusted Key Entry Console web application link.
  3. Select Trusted Key Entry in the left sidebar menu.
  4. Select the applicable Trusted Key Entry version on the Trusted Key Entry page.
  5. Login with your user credentials.
  6. On the Trusted Key Entry window, perform the following:

    a) If the host already exists and you just want to change the connection to TLS:

    1. Right click on your Host.
    2. Select Change Host.
    3. On the Change Host window: Select the Enable SSL/TLS check box, then press OK.

    b) If you want to create a new Host with a TLS connection:

    1. Right click in the Hosts area.
    2. Select Create Host.
    3. On the Create Host window:

      Fill in the needed information. Select the Enable SSL/TLS check box, then press OK.

  7. TLS connections are now enabled for that Host.

Updating the catcher key and certificate

If you want to update the key and certificate for your TLS connection, then use the following instructions.

  1. Generate or otherwise acquire the new TLS key and certificate you want to use.
    • The key and certificate must by in PEM format.
    • The Common Name (CN) attribute within the Subject tag of the certificate must match the host name/IP value used in your TKE host setup. This is usually your server hostname, but an IP address is also acceptable. You may put your hostname in the Common Name attribute within the Subject Name, and your IP address(es) in your Subject Alternative Name field..
    • Example (to produce a self-signed certificate, which is only suitable for testing):
      openssl req -newkey rsa:2048 -nodes -keyout catcher.key -x509
            -days 365 -subj "/CN=<server hostname>" 
            -addext "subjectAltName = IP:<ip_address>"
            -out catcher.crt
  2. Place your new key and certificate into the /opt/IBM/CCA/bin/ directory.
    • Use the name catcher.key for the key file and the name catcher.crt for the certificate file.
    • If you want to save your old key and certificate, then rename the files or move them to another directory.
    • If you do not want to save the old key and certificate, then you can overwrite the current files with your new files. This might be the case if the current catcher.key and catcher.crt files were automatically generated by the catcher daemon itself.
    • Example: 
      cp catcher.key /opt/IBM/CCA/bin/catcher.key 
cp catcher.crt /opt/IBM/CCA/bin/catcher.crt
  3. Import your new catcher certificate into your TKE. This can be done in two ways.
    • Method1: Physical media (USB stick) import
    • Method2: Remote server import
    Follow the instructions in topic Importing the catcher certificate into the TKE for your chosen import method .
  4. Restart the catcher daemon to ensure your new key and certificate are in use. For example, issue the following command: systemctl restart CSUTKEcat
  5. Your new TLS key and certificate are now in place.

Change the catcher to TCP mode

  1. In the /etc/cca/catcher.conf file, change the line TLS_ON to TLS_OFF and save the file.
  2. Restart the catcher daemon. For example, enter the command: systemctl restart CSUTKEcat.
  3. [optional] Verify that the catcher is running in TCP mode :
    1. Check that the catcher.exe was started without the -tls option.
    2. Run the following command: ps -ax | grep catcher.exe. The output should show only catcher.exe (without the -tls option). For example: 
      $ ps -ax | grep catcher.exe
29716 ? Ss 0:00 /opt/IBM/CCA/bin/catcher.exe

Enable TCP connections on the TKE

  1. Change your catcher daemon to TCP mode. Follow the instructions in Change the catcher to TCP mode.
  2. Starting on the TKE Welcome Page: Select the Launch the Trusted Key Entry Console web application link.
  3. Select Trusted Key Entry in the left sidebar menu. This might already be selected.
  4. Select the applicable Trusted Key Entry version on the Trusted Key Entry page.
  5. On the Trusted Key Entry window, perform the following:

    a) If the host already exists and you just want to change the connection to TCP:

    1. Right click on your Host.
    2. Select Change Host.
    3. On the Change Host window: Click on the Enable SSL/TLS check box, so that it is in the unchecked state. Then press OK.

    b) If you want to create a new Host with a TCP connection:

    1. Right click in the Hosts area.
    2. Select Create Host.
    3. On the Create Host window:

      Fill in the needed information. Click on the Enable SSL/TLS check box, so that it is in the unchecked state. Then press OK.

  6. TCP connections are now enabled for that Host.