Configuring TLS cipher suites

You can use cipher suite configuration file to customize your own list of cipher suites based on your needs.

About this task

When a TLS connection is established, during the TLS handshake, the client and server exchange information about which TLS protocols and cipher suites they have in common. They then communicate using the protocol and common cipher suites that offers the highest level of security. System TLS has infrastructure to support multiple cipher suites. Cipher Suites info shows the cipher suite specifications, which are shown here in the system value format, that can be supported by System TLS for each protocol version. Z ChatOps provides the cipher suites configuration file where you can specify a list of cipher suites to be used during a TLS connection.

The cipher suite configuration file provides several cipher suites that are recommended for use.

Note: It is not recommended that you change them, but if you find some cipher suites are no longer secure, or you have higher requirements, you can change the cipher suites in the configuration file.

In the cipher suites configuration file, there are four levels of security: Recommended, Secure, Weak, and Insecure. The cipher suites configuration file contains TLS 1.2 and TLS 1.3 two versions, and each version has four lists corresponding to four security levels. Z ChatOps only use the cipher suites written in recommended and secure list, while all cipher suites written in weak or insecure list will be shielded and cannot be used.

You can add new cipher suites in the configuration file, and you can also identify any less efficient or less secure cipher suites and then decide whether to eliminate such cipher suites.

Important: The name format used in the cipher suite configuration file .cipher-suite.json is OpenSSL. You can refer to the website https://testssl.sh/openssl-iana.mapping.html to find the correct name.

Procedure

Go to the Z ChatOps configuration directory.
- For Container users:
  i. Go to the directory where you extract the IBM Z® ChatOps Container archive.
  ii. Run the following command to open an interactive shell on the IBM Z ChatOps container that is running.
```
./bnzContainer.sh shell
```
  iii. Go to the configuration directory.
```
cd config
```
  Tip: If you are familiar with docker/podman commands, you can use commands to open the interactive bash shell. You can also edit the configuration files directly in the mounted path of the zchatops-configuration-1131 or zchatops-configuration-113 volume.
- For native installation users:
```
cd $ZCHATOPS_HOME/config
```

Edit the cipher suites configuration file .cipher-suite.json by adding new cipher suites to the recommended or secure list, and moving the cipher suites that you don't need to the weak or insecure list.

Add new cipher suites.
i. Identify the TLS version of the new cipher suites, and find the corresponding list.

ii. Add the new cipher suites in the recommended or secure list.
Remove the cipher suites that you don't need.
i. Find the cipher suites that you don't need, and identify which TLS version they are.

ii. Move these cipher suites to the weak or insecure list, and make sure you move them to the correct TLS version list.

{
    "tls13": {
        "recommended": [
            "TLS_CHACHA20_POLY1305_SHA256",
            "TLS_AES_128_GCM_SHA256",
            "TLS_AES_256_GCM_SHA384",
            "TLS_AES_128_CCM_SHA256",
            "TLS_AES_128_CCM_8_SHA256"
        ],
        "secure": [],
        "weak": [],
        "insecure": []
    },

    "tls12": {
        "recommended": [
            
            "ECDHE-ECDSA-AES128-CCM8",
            "DHE-DSS-AES128-GCM-SHA256",
            ... ...
            ... ...        
            "ECDHE-ECDSA-ARIA256-GCM-SHA384",
            "ECDHE-ECDSA-AES256-CCM8",
            "DHE-PSK-AES128-CCM",
            "DHE-PSK-ARIA128-GCM-SHA256"
        ],

        "secure": [
            "DHE-RSA-ARIA128-GCM-SHA256",
            ... ...
            ... ...  
            "ECDHE-RSA-AES256-GCM-SHA384",
            "DHE-RSA-ARIA256-GCM-SHA384"
        ],

        "weak": [
            "ADH-ARIA256-GCM-SHA384",
            "DHE-PSK-NULL-SHA256",
            "PSK-RC4-SHA",
            ... ...            
            ... ...                     
            "ECDHE-PSK-NULL-SHA256",
            "EXP-RC2-CBC-MD5",
            "NULL-SHA"
        ],

        "insecure": [
            "AES256-SHA",
            "CAMELLIA128-SHA",
            "ECDH-ECDSA-AES128-GCM-SHA256",
            "DH-RSA-AES128-SHA",
            ... ...
            ... ...   
            "ECDH-RSA-CAMELLIA256-SHA384",
            "DH-RSA-ARIA128-GCM-SHA256"
        ]
    }
}

Stop and start your Z ChatOps for the configuration to take effect. See Starting and stopping Z ChatOps for specific steps.