Application Transparent Transport Layer Security (AT-TLS)

Application Transparent Transport Layer Security (AT-TLS) creates a secure session on behalf of an application. Instead of implementing TLS in every application that requires a secure connection, AT-TLS provides encryption and decryption of data based on policy statements that are coded in the Policy Agent. The application sends and receives cleartext (unencrypted data) as usual while AT-TLS encrypts and decrypts data at the TCP transport layer. For more information about AT-TLS and AT-TLS policy setup, see the Application Transparent Transport Layer Security (AT-TLS) information in z/OS Communications Server: IP Configuration Guide and the Policy Agent information in z/OS Communications Server: IP Configuration Reference.

Most applications do not need any awareness of the security negotiations and encryption that is done by TCP/IP on its behalf. However, you might want some applications to be aware of AT-TLS or have control over the security functions that are being performed by TCP/IP. For example, if the application is a server requesting client authentication, you might want the application to get the partner certificate or the user ID associated with the partner certificate. Or the application might negotiate in cleartext with its partner to decide whether a secure session is necessary. If both agree to a secure session, then the application needs to tell AT-TLS to set up a secure session. The SIOCTTLSCTL ioctl provides the interface for the application to query or control AT-TLS.

Applications that are taking advantage of AT-TLS can be separated into three different types (basic, aware and controlling) as described in Table 1. An application's type is based on whether an awareness of the service is needed and, if so, the amount of control that the application is given over the security functions. Basic applications are unchanged. Aware applications are changed to invoke the SIOCTTLSCTL ioctl to query a socket about AT-TLS status using a TTLSi_Req_Type value of TTLS_QUERY_ONLY or TTLS_RETURN_CERTIFICATE. Controlling applications are changed to invoke the SIOCTTLSCTL ioctl to control the secure session on a socket using a TTLSi_Req_Type value of TTLS_INIT_CONNECTION, TTLS_RESET_SESSION, TTLS_RESET_CIPHER, TTLS_RESET_WRITE_CIPHER, or TTLS_SEND_SESSION_TICKET.

Table 1. Application types
Application type SIOCTTLSCTL ioctl calls issued ApplicationControlled setting in AT-TLS policy
Basic application does not issue any AT-TLS ioctl calls Off
Aware query requests Off
Controlling query and control requests On
  • A basic application is unaware that AT-TLS is performing encryption or decryption of data. Most applications can match this model.
  • An aware application is aware of AT-TLS and can query information such as AT-TLS status, partner certificate, and derived RACF® user ID without any advanced setting in AT-TLS policy. A server that requires a RACF user ID derived from a partner certificate matches this model.
  • A controlling application is aware of AT-TLS and needs to control the secure session. It must have the ApplicationControlled parameter in AT-TLS policy set to ON. Any application that must control when the initial handshake is done, when sessions or ciphers must be reset, or when a TLS 1.3 session ticket is sent matches this model.

The SIOCTTLSCTL ioctl blocks during the initial handshake if the socket is in blocking mode. If the socket is non-blocking, SIOCTTLSCTL returns EWouldBlock during the initial handshake.

Applications that use non-blocking sockets can use the select function to wait for the socket to become writable. When the socket becomes writable, the initial handshake is complete.

The following APIs are supported by AT-TLS:
  • Macro API (EZASMI)
  • CALL instruction API (EZASOKET) supporting COBOL, PL/I, and System/370 assembler languages
  • REXX socket API
  • Language Environment® C socket call [ioctl( )]
  • UNIX System Services Assembler Callable Service (BPX1IOC or BPX4IOC)
  • CICS® C socket calls
  • CICS CALL instruction API (EZASOKET - by including EZACICAL or EZACICSO)
  • IMS CALL instruction API (EZASOKET)
Restriction: The following APIs are not supported by AT-TLS:
  • TCP C Socket API
  • X/Open Transport Interface (XTI)
  • Pascal API