Providing support to update to TLS 1.3

TLS 1.3 differs from prior versions of the protocol. 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.

1. Upgrade to CICS Transaction Server 6.1.

   Ensure your CICS upgrade to version 6.1 is complete. This step covers the background information that you need to ensure is configured before you prepare RDO definitions.

   The SIT parameter USSCONFIG must specify a directory in which you create definitions. This directory must include a security subdirectory. The security subdirectory must include a ciphers subdirectory. XML cipher definitions exist in the ciphers subdirectory. USSCONFIG cannot be set to the same value as USSHOME.

   You must copy the sample default ciphers file from usshome/security/ciphers/defaultciphers.xml to ussconfig/security/ciphers/defaultciphers.xml and customize to ensure that the ciphers used conform to your compliance rules.

   This file is used as the default value for new definitions that require the CIPHERS options; in previous releases of CICS this parameter defaults to two-digit ciphers.

2. Preparing RDO definitions before you upgrade to TLS 1.3.

   To use TLS 1.3, you must specify at least one of the following new TLS 1.3 ciphers in the CIPHERS option on all IPCONN, TCPIPSERVICE, and URIMAP resource definitions, regardless of whether TLS 1.3 is used for the connection. Because the TLS 1.3 ciphers can be defined only in an XML file, it is necessary to update any definitions that use ciphers to use an XML file in the CIPHERS option.

       <cipher number="1301">
          <!-- TLS_AES_128_GCM_SHA256 -->
       </cipher>
       <cipher number="1302">
          <!-- TLS_AES_256_GCM_SHA384 -->
       </cipher>
       <cipher number="1303">
          <!-- TLS_CHACHA20_POLY1305_SHA256 -->
       </cipher>
   

   You can blank out the ciphers in a resource definition by using CEDA. CEDA replaces these ciphers with defaultciphers.xml.

   If you require specific ciphers for a selected IPCONN, TCPIPSERVICE, and URIMAP resource definition, you need to create an XML file in the ciphers subdirectory and change the CIPHERS option of the selected definition to that name.

   Ensure that all of the XML cipher files that you are using, including defaultciphers.xml have at least one of the TLS 1.3 ciphers, in addition to your existing TLS 1.2 ciphers.

   If you use applications with the WEB OPEN commands, you might still have some CIPHERS defined and see a message DFHWB0767 to indicate that the CIPHERS option is deprecated. The CIPHERS option is ignored for TLS 1.3. The cipher that you use for the WEB OPEN connection is either obtained from the URIMAP defined in the URIMAP option on the WEB OPEN command, or if that option is not defined, from defaultciphers.xml. Ensure that the XML cipher file used contains ciphers appropriate for this connection.

3. Upgrade your certificates.

   TLS 1.3 requires certificates to have a minimum key size of 2048. Check that any certificates in your keyrings are at least SIZE(2048). If they are smaller, they need to be reissued.

   The RACDCERT command can be used to list keyrings and certificates. For more information about RACDCERT, see Using the RACDCERT command.

4. Enable TLS 1.3.

   Set the SIT option MAXTLSLEVEL=TLS13.

   Check that each of your connections is established. The connection uses the highest level of TLS supported by both sides. If any of the connections do not use TLS 1.3, you need to reconfigure or upgrade that client or server.

5. Disable TLS 1.2.

   When all connections have been checked to use TLS 1.3, you can disable lower versions of TLS by setting MINTLSLEVEL=TLS13.

   After these changes are complete for all of your regions, change all XML cipher files to remove non-TLS 1.3 ciphers.