Required updates to enable TLS V1.3 protocol support
- 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:
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=003500380039002F00320033
GSK_V3_CIPHER_SPECS_EXPANDED=13021303003500380039002F00320033
- 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 V1.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 V1.2 and prior connections), the format restriction keyword FR-NONE should be used when converting the private key.