AT-TLS controlling application considerations

Applications that need to control AT-TLS behavior, using the SIOCTTLSCTL IOCTL with the TTLS_INIT_CONNECTION, TTLS_RESET_SESSION, TTLS_RESET_CIPHER, TTLS_RESET_WRITE_CIPHER, or TTLS_SEND_SESSION_TICKET request flags, must have the ApplicationControlled parameter set to ON in their TTLSEnvironmentAdvancedParms or TTLSConnectionAdvancedParms statement. This causes AT-TLS to postpone the TLS handshake. After the connection is established, the application can issue the SIOCTTLSCTL IOCTL to get the current AT-TLS connection status and determine whether or not AT-TLS support is available on this connection. When the application is ready for AT-TLS to perform the TLS handshake, it issues the SIOCTTLSCTL IOCTL with request type TTLS_INIT_CONNECTION. The SIOCTTLSCTL IOCTL initiates an AT-TLS policy lookup, if one has not yet been done, and assigns a rule and actions to the connection if a match is found. For more IOCTL information, see z/OS Communications Server: IP Programmer's Guide and Reference.

Some application protocols provide a way for the client and server programs to negotiate whether to use the TLS or SSL protocol to protect data on the connection. This cleartext negotiation typically occurs very early in the connection. When both partners agree to use TLS, they initiate the handshake. These applications can take advantage of AT-TLS. The policy must indicate ApplicationControlled ON. After the connection is established, the application can use the SIOCTTLSCTL IOCTL to determine whether AT-TLS support is configured, policy covers the connection, and the policy specifies ApplicationControlled ON. The application can then send and receive cleartext data to negotiate the use of TLS. When both partners agree, they each must initiate a secure connection. The AT-TLS application can use the SIOCTTLSCTL ioctl with TTLS_INIT_CONNECTION to initialize the secure connection. AT-TLS performs the initial handshake and provides encryption and decryption services for the application. The application can simply send and receive cleartext over the socket as it would if it were not a secure connection.

The application can also use the SIOCTTLSCTL IOCTL to reset the cipher or the session. Resetting the session clears any cached session IDs or session tickets preventing session resumption with this session’s credentials. Resetting the cipher causes the encryption key to be updated.

For TLSv1.2 and earlier versions, it causes AT-TLS to initiate another handshake. If the session is reset first, the subsequent handshake is a full handshake. If the session has not been reset, a short handshake is attempted for the subsequent handshake. The partner application must agree to the short handshake.
For TLSv1.3, there are two types of reset requests that can be specified on the SIOCTTLSCTL IOCTL – TTLS_RESET_CIPHER and TTLS_RESET_WRITE_CIPHER. TTLS_RESET_CIPHER causes the encryption key to be updated and a Key Update message to be sent to the session partner, requesting that the session partner also update its encryption key. The TTLS_RESET_WRITE_CIPHER causes the encryption key to be updated and a Key Update message to be sent to the session partner but there is no request that the session partner update its encryption key.

For TLSv1.3, the application can also use the SIOCTTLSCTL IOCTL to request that a session ticket be sent from the server to the client. The TTLS_SEND_SESSION_TICKET request can be used when the server is configured to enable session tickets but the count of session tickets automatically sent when the initial handshake completes is 0 (GSK_SESSION_TICKET_SERVER_ENABLE and GSK_SESSION_TICKET_SERVER_COUNT on the TTLSGskAdvancedParms statement). The session ticket is cached and used for session resumption.