Skip to main content

Enabling TLS 1.3 in System SSL Applications

Major updates were introduced in the TLS 1.3 protocol. To take advantage of the security updates within the TLS 1.3 protocol, updates are required to your System SSL application.  

Security padlock

The Transport Layer Security (TLS) 1.3 protocol is a major rewrite of prior TLS protocol standards. After being in the works for many years in the Internet Engineering Task Force (IETF) TLS working group, TLS 1.3 became a formal standard in August 2018 when RFC 8446 was published. In z/OS 2.4, System SSL added support for the TLS 1.3 protocol in order for z/OS applications to take advantage of the security updates.

TLS 1.3 includes the following updates:
  • All handshake messages after the initial client and server handshake messages are now encrypted. In prior protocols, messages were not encrypted until after the final handshake messages were exchanged between the client and server.
  • Encrypted handshake messages are presented as payload messages and must be decrypted in order to determine whether the message is a handshake, payload or alert message.
  • The RSA key exchange is no longer supported. It was replaced with Elliptic Curve Diffie-Hellman Ephemeral (ECDHE), which provides forward secrecy.
  • Prior to TLS 1.3, the negotiated key exchange was part of the cipher suite. In TLS 1.3, the negotiated key exchange is no longer part of the cipher suite and is negotiated separately.

Required Updates to Enable TLS 1.3 

If an existing z/OS System SSL application is being updated to support TLS 1.3, there are required updates. If the application supports parsing environment variables, they can be set to enable TLS 1.3. Otherwise, the application will need to be updated to call the System SSL gsk_attribute_set_**() routines.
Enabling TLS 1.3 

To enable TLS 1.3, set the new GSK_PROTOCOL_TLSV1_3 setting to ON.

Cipher specifications 

TLS 1.3 introduced new ciphers that are only supported in TLS 1.3. Existing TLS 1.2 and prior ciphers are not supported in TLS 1.3. System SSL applications must programmatically enable support for 4-character ciphers by invoking gsk_attribute_set_enum() with GSK_V3_CIPHERS and GSK_V3_CIPHERS_CHAR4 values.

Because the new TLS 1.3 ciphers were not added to the default cipher list, the GSK_V3_CIPHER_SPECS_EXPANDED setting must be updated to specify at least one of the new cipher specifications. The new cipher specifications are listed in Table 1.  

Table 1: New TLS 1.3 ciphers in System SSL
Key shares 

The client and server sides each specify a key share group list with asymmetric groups. When the client attempts a TLS 1.3 handshake, it generates a public/private key pair for each supported group. The generated public values are put into the client’s initial handshake message. The server selects a group in common with the client’s groups and then generates its own public/private key pair for the selected group. The server takes its private value and the client’s public value to generate a shared secret, which is used to generate keys for encrypting and decrypting handshake messages. Likewise, the client generates the same shared secret with its private value associated with the server’s public value that is transmitted in the server’s initial handshake message.

System SSL has two new settings, GSK_CLIENT_TLS_KEY_SHARES and GSK_SERVER_TLS_KEY_SHARES. They specify the key share groups that are supported within the client and server, respectively. The client or server-side settings are required when TLS 1.3 handshakes are attempted in that application.

For the GSK_CLIENT_TLS_KEY_SHARES setting, keep the number of share key groups to a minimum. Public/private key pairs are generated for each key share group, which can be computationally expensive and might impact performance. For the GSK_SERVER_TLS_KEY_SHARES setting, you should list all desired supported key share groups to allow as many TLS 1.3 clients to successfully establish a secure connection.

Table 2: Supported key share groups
Supported certificate types 

As documented in the TLS 1.3 standard, System SSL only supports RSA key sizes 2048 bits and larger and ECC keys 256 bits and larger. RSA keys with a PKCS #1 v1.5 signature or with an RSASSA-PSS signature are supported.

TLS 1.3 no longer supports DSA or DH certificates. If these certificates are used in your environment, new RSA or ECC certificates must be obtained and installed in the certificate repository.

Optional Considerations for Certain Configurations

Depending on the current configuration of the application, the following might need to be considered when you migrate the System SSL application to TLS 1.3.

Supported groups or elliptic curves 

A client application may specify the list of supported groups or elliptic curves with the GSK_CLIENT_ECURVE_LIST setting. When TLS 1.3 is enabled, the default GSK_CLIENT_ECURVE_LIST setting appends 0029 (x25519) to the end of the list. If the GSK_CLIENT_TLS_KEY_SHARES setting specifies 0030 (x448), you must manually update the GSK_CLIENT_ECURVE_LIST setting to include 0030 so that the key share is sent to the server. Any groups that are specified in the GSK_CLIENT_TLS_KEY_SHARES must be reflected in the GSK_CLIENT_ECURVE_LIST.

Signature and hash algorithms

The GSK_TLS_SIG_ALG_PAIRS setting indicates the list of supported hash and signature algorithms for use in digital signatures of X.509 certificates and TLS handshake messages. When an RSA end entity certificate is used, the TLS 1.3 handshake messages must be signed with an RSASSA-PSS signature algorithm. When enabled for TLS 1.3, the GSK_TLS_SIG_ALG_PAIRS default setting now includes the three new RSASSA-PSS signature and hash algorithms at the end of the list. If an application specified a GSK_TLS_SIG_ALG_PAIRS setting, it must be updated to include at least one of the RSASSA-PSS signature algorithms when an RSA certificate is used.

Table 3: New RSASSA-PSS signature algorithms
 In z/OS 2.4, System SSL introduced the GSK_TLS_CERT_SIG_ALG_PAIRS optional setting. It lists the supported hash and signature algorithms that can be used in digital signatures of X.509 certificates. If the GSK_TLS_CERT_SIG_ALG_PAIRS setting is specified, it overrides the GSK_TLS_SIG_ALG_PAIRS setting when the X.509 certificate signature algorithm is checked.

TLS 1.3 Session Key Updates

TLS 1.3 no longer supports renegotiation to update session keys. Instead, it performs session key updates by exchanging a keyUpdate protocol message. 

The local application can update its write key by calling gsk_secure_socket_misc() with a GSK_RESET_CIPHER value. A keyUpdate protocol message is then sent to notify the peer to update its read key. If the peer decides to update its write key, it responds with its own keyUpdate message, which then updates the local application’s read key.

With TLS 1.3, you can update the local application’s write key (peer’s read key) by calling gsk_secure_socket_misc() with a GSK_RESET_WRITE_CIPHER value.

TLS 1.3 Session Resumption

In previous protocols, the client and server sides each maintained a session ID cache. When a client attempted to reestablish a previous connection, its cache was queried to obtain the session ID to put into the initial handshake message. When the server received the session ID, it queried its own cache to determine whether it existed and whether the connection parameters were the same. If they were the same, the server retrieved the previous connection state from its cache and indicated its acceptance by putting the same session ID in its initial handshake message that was sent to the client.

In TLS 1.3, the server no longer maintains session state in a cache. After a successful TLS 1.3 handshake, the server optionally sends a session ticket, which contains an encrypted data block of the TLS 1.3 session information, to the client. The client stores any received session tickets in its cache. When the client attempts to reestablish a previous TLS 1.3 connection, it queries the cache to obtain a valid session ticket and attaches it to the client’s initial handshake message, which the server attempts to decrypt. If the session ticket is successfully decrypted and is still valid, the server resumes the previously established connection and indicates a successfully resumed session in its initial handshake message. If the session ticket cannot be decrypted or is no longer valid, a full TLS 1.3 handshake is attempted underneath the covers.

There are new session ticket settings for the client:
  • GSK_SESSION_TICKET_CLIENT_ENABLE allows session tickets to be stored in the client cache. The default is ON.
  • GSK_SESSION_TICKET_CLIENT_MAXSIZE specifies the maximum size in bytes of a session ticket that can be stored in client cache. The default is 8192.
There are also new session ticket settings for the server:  
  • GSK_SESSION_TICKET_SERVER_ALGORITHM specifies the session ticket encryption algorithm. The default is AESCBC128.
  • GSK_SESSION_TICKET_SERVER_COUNT specifies the number of session tickets that are sent after an initial TLS 1.3 handshake. The default is 2.
  • GSK_SESSION_TICKET_SERVER_ENABLE specifies whether the server is to send session tickets after a completed TLS 1.3 handshake. The default is ON.
  • GSK_SESSION_TICKET_SERVER_KEY_REFRESH specifies the key refresh interval in seconds. The default is 300 seconds.
  • GSK_SESSION_TICKET_SERVER_TIMEOUT specifies the maximum time in seconds that a TLS 1.3 session resumption attempt is allowed. The default is 300 seconds.

Take Advantage of TLS 1.3 Updates 

To accompany the TLS 1.3 updates done in System SSL, Application Transparent—TLS (AT-TLS) was updated to support TLS 1.3 in its policy definitions.

Major updates were introduced in the TLS 1.3 protocol. To take advantage of the security updates within the TLS 1.3 protocol, updates are required to your System SSL application.  

For more information about the AT-TLS updates, see “z/OS Communications Server: IP Configuration Guide.” See “z/OS Cryptographic Services System SSL Programming for more information about System SSL.
IBM Systems Webinar Icon

View upcoming and on-demand (IBM Z, IBM i, AIX, Power Systems) webinars.
Register now →