Enabling TLS 1.3 in CICS

TLS 1.3 differs from earlier versions of the protocol. To migrate to TLS 1.3 from an earlier version, you need to update your resource definitions to use the cipher suite specification file before enabling TLS 1.3.

Before you begin

To enable TLS 1.3, you must ensure:

You are at z/OS® 2.4 or later.
ICSF must be active.
If you use RSA certificates, the RSA keys held in the PKDS must be secured using the ECC master key.
You are at CICS® TS 6.1 or later.
Important: If you're at a CICS release earlier than CICS TS 6.1, it is important to avoid enabling TLS 1.3 until you complete your upgrade to CICS TS 6.1. You can then focus on enabling TLS 1.3 in isolation from any other work.

Recommended: The increased security provided by TLS 1.3 can have a higher CPU cost than earlier versions of TLS. To avoid performance problems, it's recommended that you fulfill the following requirements before enabling TLS 1.3 in production:

6.2 and later Enable sysplex caching for TLS 1.3. See SSLCACHE system initialization parameter.
Use RSA certificates.

About this task

TLS 1.3 differs from earlier versions of the protocol as follows. For more information, see RFC 8446 The Transport Layer Security (TLS) Protocol Version 1.3.

No ciphers exist in common between TLS 1.3 and earlier versions of the TLS protocol.
The ciphers for TLS 1.3 are 4-digit ciphers that can be defined in CICS only by using the TLS cipher suite specification files, which are XML files.
Enabling TLS 1.3 might affect performance.
There is an increase in the number of CWXN transactions that execute when you use TLS 1.3 compared to when you use TLS 1.2.

Procedure

Prepare the TLS cipher suite specification file:

Copy the sample default cipher suite specification file (defaultciphers.xml) from usshome/security/ciphers to ussconfig/security/ciphers.

where

usshome

Is the directory specified on the USSHOME SIT parameter.

ussconfig

Is the directory specified on the USSCONFIG SIT parameter. It must be different from the value on USSHOME.

You need to create the folders in ussconfig if there are none.

This defaultciphers.xml file is used as the default cipher suite specification file for new resource definitions that require the CIPHERS options. In CICS TS 5.6 and earlier, it defaulted to two-digit ciphers.
In ussconfig/security/ciphers, customize the defaultciphers.xml file to ensure that the ciphers in use conform to your compliance rules.

Note: The defaultciphers.xml file is used in this example to show a simple route. You can define multiple cipher suite specification files for different connections.

Prepare resource definitions for TLS 1.3:

Specify at least one of the following new TLS 1.3 ciphers in your cipher suite specification file, in this case, ussconfig/security/ciphers/defaultciphers.xml.
```
    <cipher number="1301">
       
    </cipher>
    <cipher number="1302">
       
    </cipher>
    <cipher number="1303">
       
    </cipher>
```
If you have multiple cipher suite specification files, ensure that they all have at least one of the TLS 1.3 ciphers, in addition to your existing TLS 1.2 ciphers.
Ensure the CIPHERS option in all IPCONN, TCPIPSERVICE, and URIMAP resource definitions references your cipher suite specification file, in this case defaultciphers.xml, regardless of whether TLS 1.3 is used for the connection.

Because the TLS 1.3 ciphers can be defined only in the cipher suite specification file, you must update any definitions that use ciphers to use an cipher suite specification file on the CIPHERS option.

If you're using CEDA to alter definitions, you can blank out the ciphers in a resource definition. CEDA replaces the existing ciphers with defaultciphers.xml.

If you use applications with the WEB OPEN commands, you might still have some ciphers defined and see a message DFHWB0767 that indicates the CIPHERS and NUMCIPHERS options are deprecated on the command. The CIPHERS or NUMCIPHERS option on WEB OPEN is ignored for TLS 1.3. The WEB OPEN connection obtains the cipher either from the URIMAP defined on the URIMAP option of the WEB OPEN command, or if that option is not defined, from defaultciphers.xml. Ensure that the cipher suite specification cipher file in use contains ciphers appropriate for this connection.

Any existing URIMAP resources defined with CIPHERS() will use ciphers from the defaultciphers.xml file as soon as TLS 1.3 is enabled.

If you need specific ciphers for a specific connection, ensure you have the corresponding cipher suite specification file in the ciphers subdirectory and it is referenced correctly in the CIPHERS option on the matching IPCONN, TCPIPSERVICE, and URIMAP resource definition.

Update your certificates:

TLS 1.3 requires certificates to have a minimum key size of 2048.

Check that any certificates in your key rings are at least SIZE(2048). If they are smaller, they need to be reissued.

You can use the RACDCERT command to list key rings and certificates.

Enable TLS 1.3:

Set the SIT parameter MAXTLSLEVEL=TLS13.

The SIT parameter MAXTLSLEVEL defaults to TLS12. This value enables an upgrade to CICS TS 6.1 or later to take place without affecting any existing TLS connections or programs that open TLS connections.
Check that all of your connections are established. The connection uses the highest level of TLS supported by both sides. If any connection does not use TLS 1.3, you need to reconfigure or upgrade that client or server.

You can see which clients or servers are not using TLS 1.3 by using diagnostics. See Changing TLS protocol level or ciphers safely.

Disable earlier versions of TLS:

When you are sure that all connections are using TLS 1.3, disable earlier versions of TLS by setting MINTLSLEVEL=TLS13.
After you complete setting MINTLSLEVEL=TLS13 in all of your regions, remove non-TLS 1.3 ciphers from all the cipher suite specification files.