Required updates to enable TLS V1.3 protocol support

There are a few required updates that must be done when updating a z/OS System SSL application to support TLS V1.3. Application updates can be done via environment variables (if supported) or calling System SSL gsk_attribute_set_*() routines. If application code is to be updated, there is sample application code in Writing a System SSL source program.

Enabling TLS V1.3 protocol support

Enable TLS V1.3 protocol support by setting the GSK_PROTOCOL_TLSV1_3 setting to ON.

Cipher specifications

Update the application to support 4-character ciphers because the TLS V1.3 ciphers are all 4-character ciphers. System SSL applications must programmatically enable support for 4-character ciphers by running gsk_attribute_set_enum() with GSK_V3_CIPHERS and GSK_V3_CIPHERS_CHAR4 values. If the application is using 2-character cipher specifications and has set the GSK_V3_CIPHER_SPECS setting, it is necessary to convert those 2-character cipher specifications to 4-character ciphers and use the GSK_V3_CIPHER_SPECS_EXPANDED setting. In addition, one or more of the supported TLS V1.3 cipher specifications must be specified when enabled for the TLS V1.3 protocol.

In this example configuration, the application is configured to use ciphers 3D, 39, 38, 37, and 35.

GSK_V3_CIPHER_SPECS=3D39383735

If the application has not set the GSK_V3_CIPHER_SPECS or GSK_V3_CIPHER_SPECS_EXPANDED settings, it is using the System SSL default ciphers. The TLS V1.3 cipher specifications have not been added to the System SSL default cipher list. In these cases, specify one or more TLS V1.3 ciphers along with the default cipher list values in the GSK_V3_CIPHER_SPECS_EXPANDED setting. See SSL/TLS protocol for the current System SSL default cipher list.

For example, if the current System SSL default cipher specification list for the GSK_V3_CIPHER_SPECS_EXPANDED setting is:

GSK_V3_CIPHER_SPECS_EXPANDED=003500380039002F00320033

The application must be updated to specify the GSK_V3_CIPHER_SPECS_EXPANDED setting with one or more TLS V1.3 ciphers in the list. This example shows the addition of ciphers 1302 and 1303 to the beginning of the System SSL cipher specification list above:

GSK_V3_CIPHER_SPECS_EXPANDED=13021303003500380039002F00320033

See Table 2 and Table 3 for the supported cipher specifications.

Key shares

System SSL has two settings GSK_CLIENT_TLS_KEY_SHARES and GSK_SERVER_TLS_KEY_SHARES that specify the key share groups supported within the client and server respectively. The client or server side settings are required when TLS V1.3 handshakes are attempted in that application. If the key share settings are not specified, TLS V1.3 handshakes will fail.

The following is an example configuring secp256r1 (0023) and x25519 (0029) in a client application:

GSK_CLIENT_TLS_KEY_SHARES=00230029

The following is an example configuring secp256r1 (0023), secp521r1 (0025), and x25519 (0029) in a server application:

GSK_SERVER_TLS_KEY_SHARES=002300250029

See Table 5 for the supported key share groups.

Supported certificate types

When updating an application to support TLS V1.3, this is a good time to examine the local and remote peer certificates that are in use. As documented in RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3 RFC 8446, System SSL only supports RSA key sizes 2048 bits and larger and ECC keys 256 bits and larger when attempting to do a TLS V1.3 handshake. RSA keys with a PKCS #1 v1.5 signature or with an RSASSA-PSS signature are supported. TLS V1.3 no longer supports DSA or DH certificates.

If the certificates currently being used in your environment do not adhere to these TLS V1.3 requirements, new RSA or ECC certificates must be obtained from the certificate authority (CA) and installed in the certificate repository to allow for successful TLS V1.3 secure connections. These new certificates should be obtained from the same CA to avoid possibly having the peer needing to install CA certificates from another certificate authority.

If the certificate to be used for the TLS connection is of type RSA with its private key stored in the PKDS and was created or added to the RACF database prior to z/OS V2R4, the certificate will not be usable for TLS 1.3 connections. The RSA key needs to be protected using the ECC master key. Ensure that the ECC master key is activated in the CCA coprocessor and either recreate or re-import (PKCS#12) the certificate into the RACF database or convert the existing private key to be protected under the ECC master key. See Translate and replace an RSA key for RSA PSS for information on how to convert the private key. To ensure that the key can continue to be used for RSA PKCS 1.5 signature generation (for example, used for TLS 1.2 and prior connections), the format restriction keyword FR-NONE should be used when converting the private key.