Introduction to Application Transparent Transport Layer Security (AT-TLS)

Application Transparent Transport Layer Security (AT-TLS) can be used to create secure socket sessions on behalf of CICS®. Instead of implementing Transport Layer Security (TLS) in CICS, AT-TLS provides encryption and decryption of data based on policy statements that are coded in the Policy Agent. When AT-TLS is used to secure socket sessions, CICS SSL/TLS start parameters such as KEYRING and MINTLSLEVEL/ENCRYPTION are no longer required as the implementation of TLS is provided by AT-TLS policy statements and all encryption and decryption is done outside of the CICS address space.

AT-TLS MODES

When AT-TLS is active for a CICS socket connection, CICS sends and receives cleartext (unencrypted data), while AT-TLS encrypts and decrypts data at the TCP transport layer. For more information about AT-TLS and AT-TLS policy setup, see AT-TLS policy configuration in z/OS Communications Server: IP Configuration Guide and Policy Agent and policy applications in z/OS Communications Server: IP Configuration Reference.

Most address spaces (such as CICS) do not need to be aware of the security negotiations and encryption that is done by TCP/IP on its behalf. However, some address spaces need to be aware of AT-TLS or have control over the security functions that are being performed by TCP/IP. For example, if the address space is a server that requires client authentication, it might want to access the client certificate and the user ID associated with the client certificate. CICS issues an AT-TLS query on a new client connection when a TCPIPSERVICE is defined with SSL(ATTLSAWARE).

Address spaces such as CICS that are taking advantage of AT-TLS can be separated into three different types (AT-TLS Basic mode, AT-TLS Aware mode, and AT-TLS Controlling mode) as described in Table 1. The type is based on whether awareness of the service is needed and, if so, the amount of control that the address space is given over the security functions.

AT-TLS Basic mode is where the address space (such as CICS) does not issue any AT-TLS calls to query a socket for its AT-TLS status.

AT-TLS Aware mode is where the address space issues an AT-TLS calls to query a socket for its AT-TLS status. The address space can access items such as the client certificate, and also the certificate User ID.

AT-TLS Controlling mode is where the address space issues AT-TLS calls to control the secure session on a socket.

Table 1. Detailed description of AT-TLS modes and their CICS support
Mode Type AT-TLS calls issued. ApplicationControlled setting in AT-TLS policy Supported by CICS TS for z/OS®
AT-TLS Basic Address space does not issue any AT-TLS calls Off All CICS releases
AT-TLS Aware Address space issues query requests Off From CICS TS V5.3
AT-TLS Controlling Address space issues query and control requests On No CICS releases

AT-TLS Basic

In the basic mode, the address space is unaware that AT-TLS is encrypting or decrypting data. The AT-TLS Basic mode is the only mode that can be used in earlier releases of CICS, from V5.2.

With basic mode, the address space (such as CICS) is oblivious to the fact that TCP/IP is performing a TLS handshake and encryption/decryption of message flows on the socket.

With the basic mode of AT-TLS, a CICS TCPIPSERVICE would be defined with SSL(NO) as CICS is not encrypting or decrypting the data, which flows on the socket. One drawback of this is that CICS cannot access client certificates as it is unaware of a certificate that is associated with the socket.  Also, when CICS uses HTTP redirection with this mode of operation, there are failures because CICS assumes that the client connection is HTTP rather than HTTPS. A problem that might arise (for example) is when you are using AUTHENTICATE(BASIC) on an HTTP TCPIPSERVICE, and CICS discovers that the user's password expired. A dialog is triggered with the user to request a new password. At the end of this dialog, there is an error because the resubmission of the original HTTP request specifies HTTP as the scheme instead of HTTPS.

AT-TLS Aware

CICS supports the AT-TLS Aware mode with the additional option of SSL(ATTLSAWARE) on the TCPIPSERVICE definition. SSL(ATTLSAWARE) is only allowed if the TCPIPSERVICE also specifies PROTOCOL(HTTP).

When a TCPIPSERVICE is defined with SSL(ATTLSAWARE), CICS issues an AT-TLS query to obtain information such as AT-TLS security status, negotiated CIPHER suite, partner certificate, and derived RACF® user ID.

When an HTTP TCPIPSERVICE is defined with SSL(ATTLSAWARE), CICS can access client certificates and their associated RACF USERIDs. The result is all the certificate-related TCPIPSERVICE AUTHENTICATE options (CERTIFICATE | AUTOREGISTER | AUTOMATIC) are supported by SSL(ATTLSAWARE).

When a TCPIPSERVICE is defined with SSL(ATTLSAWARE) CICS will detect that the client is using an HTTPS connection. This means that redirection failures which can occur when using AT-TLS in basic mode (such as the expired password dialog) are fixed by using SSL(ATTLSAWARE).

AT-TLS Controlling

CICS does not support AT-TLS Controlling mode.

For more information on AT-TLS modes (types), see Application Transparent Transport Layer Security data protection in z/OS Communications Server: IP Configuration Guide.

CICS AT-TLS query

All new client connections for the SSL(ATTLSAWARE) TCPIPSERVICE are queried to extract their AT-TLS attributes. When a client establishes a new connection to a CICS TCPIPSERVICE defined with SSL(ATTLSAWARE), it will trigger the query and CICS accepts the new client connection.
  • Connection status (AT-TLS secured/not secured).
  • Client Authentication type (NONE | PASSTHRU | FULL | REQUIRED | SAFCHECK).
  • Client certificate. If present, the client certificate is saved in the CICS certificate repository. Attributes of the certificate can be retrieved later on by applications that issue EXEC CICS EXTRACT CERTIFICATE.
  • Client certificate USERID can be used with the AUTHENTICATE option of the TCPIPSERVICE to establish the security context for the new web task. For example, AUTHENTICATE(CERTIFICATE) requires a CERTIFICATE USERID to be present to allow a web request to be processed.
  • Negotiated CIPHER number. This number is registered in a performance monitoring record in the existing field SOCIPHER.

Configurations for AT-TLS and CICS TCPIPService

There are certain combinations of AT-TLS policy and CICS TCPIPService, which are valid. The table here shows these valid combinations and expected results in CICS. It also shows combinations that are invalid.

Table 2. Combinations for AT-TLS and CICS TCPIPService
AT-TLS policy for the port CICS TCPIPSERVICE Valid combination Expected result in CICS
HandShakeRole=Server SSL(NO | ATTLSAWARE) Yes The connection is successfully established.

No client certificate is available.

HandShakeRole=Server

or

HandShakeRole=ServerWithClientAuth

SSL(YES | ClientAuth) No CICS issues DFHWB0732 and rejects the connection.
HandShakeRole=ServerWithClientAuth with ClientAuthType=(REQUIRED | SAFCHECK) SSL(ATTLSAWARE) Yes The connection is successfully established.

Client certificate is available.

HandShakeRole=ServerWithClientAuth with ClientAuthType=(FULL) SSL(ATTLSAWARE) Yes The connection is successfully established.

Client certificate is available if client sends it to the server.

HandShakeRole=ServerWithClientAuth with any of ClientAuthType SSL(NO) Yes The connection is successfully established.

No client certificate is available.

NO AT-TLS policy for the port, or the client is exempted from using an AT-TLS policy. SSL(ATTLSAWARE) No CICS rejects the connection with an HTTP 403 error.

CICS issues DFHSO0147 for the first connection and DFHWB0365 for every non-secure connection.

HandShakeRole=ServerWithClientAuth and ClientAuthType=PASSTHRU SSL(ATTLSAWARE) No CICS rejects the connection because this configuration bypasses client certificate validation.

CICS issues DFHSO0149 and TCPIPService is closed.

NO AT-TLS policy configured. SSL(YES | ClientAuth) Yes CICS processes SSL-connection as documented.
Note: For TCPIPService, configuring AT-TLS HandShakeRole=Client is incorrect.

When you are using a TCPIPSERVICE that specifies SSL(ATTLSAWARE), CICS expects all connections to be cryptographically secured by AT-TLS. If a client connection arrives which is not secured, it is rejected with an HTTP 403 error. CICS also logs the error with message DFHWB0365.

CICS does not support AT-TLS policies that use ClientAuthType=PassThru. This configuration bypasses client certificate validation, which is not acceptable to CICS. If CICS detects that this type of client authentication is being used when you are receiving a client connection, it closes the connection with the client then closes the TCPIPSERVICE. Message DFHSO0149 is written to the console when this error is detected.