AT-TLS diagnostics

There are a number of tools for diagnosing AT-TLS problems.

For diagnosing AT-TLS problems, see Diagnosing Application Transparent Transport Layer Security (AT-TLS) in z/OS Communications Server: IP Diagnosis Guide.

AT-TLS messages contain return codes that are useful in diagnosing problems. Return codes below 5000 come from system SSL. For more information on return codes, see SSL function return codes in z/OS Cryptographic Services System SSL Programming.

Socket Domain Trace Points for AT-TLS

The socket domain trace points listed, are relevant to AT-TLS. For more information, see, Socket domain trace points.

SO 0CAC (level-1)
SO 0CAB (EXC)
SO 0CA9 (level-2)
SO 0CAA (level-2)

Diagnostic Messages

The messages DFHSO0147 and DFHSO0149 are relevant to AT-TLS and detailed here, DFHSOnnnn messages. Also, message DFHWB0365 is detailed here, DFHWBnnnn messages.

CICS® provides some diagnostic messages when you encounter errors that are discovered by CICS:

DFHWB0365

date time applid tranid A client connects to a TCPIPSERVICE defined with SSL(ATTLSAWARE) but the connection is not secured by AT-TLS. Host IP address: hostaddr. Client IP address: clientaddr. TCPIPSERVICE: tcpipservice.

DFHSO0147 W

applid A non-secure client connection is received for ATTLSAWARE TCPIPSERVICE tcpipservice. Client IP address: clientaddr. TTLS_IOCTL value X'ttlsioctl'.

DFHSO0149 W

applid A client connection that uses CLIENTAUTHTYPE(PASSTHRU) is detected for ATTLSAWARE TCPIPSERVICE tcpipservice. TTLS_IOCTL value X'ttlsioctl'. The TCPIPSERVICE is closed.

Here are two examples of errors on AT-TLS connections:

The following diagnostics are seen when a client connects to an AT-TLS secured port, which is configured by using HandShakeRole ServerWithClientAuth and ClientAuthType Required. This configuration requires the client to provide a certificate. In this case, the client fails to provide a certificate. Here is the information that is shown in the AT-TLS message log:
```
EZD1287I TTLS Error RC:  403 Initial Handshake  034     
LOCAL: ::FFFF:9.20.5.0..25931  
REMOTE: ::FFFF:9.174.17.124..50077 
JOBNAME: SSYCZCCM RULE: CICSD    
USERID: HORN GRPID: 0000000D ENVID: 00000013 CONNID: 00395D99  
```
The return code of 403 is a system SSL error, and corresponds to error GSK_ERR_NO_CERTIFICATE, which means no certificate received from partner. Nothing is seen in the CICS log. CICS never receives this connection as it is being rejected by AT-TLS.
The following diagnostics appear when a client connection is made to a TCPIPSERVICE defined with SSL(ATTLSAWARE) where the TCPIPSERVICE port is NOT secured by AT-TLS. This time the client is connecting to a port, which is not policed by AT-TLS and means that there are no AT-TLS diagnostics. However, CICS detects that the client connection is not secured by AT-TLS so it issues the following messages:
- DFHSO0147 W IY2CZCCM 041 A non-secure client connection is received for ATTLSAWARE TCPIPSERVICE ATTLS2. Client IP address: 9.174.17.124. TTLS_IOCTL value X'0100000102010000'
- DFHWB0365 06/23/2015 10:14:22 IY2CZCCM CWXN A client connects to a TCPIPSERVICE defined with SSL(ATTLSAWARE) but the connection is not secured by AT-TLS. Host IP address: 9.20.5.0. Client IP address: 9.174.17.124. TCPIPSERVICE: ATTLS2.
The first message is only issued once for any TCPIPSERVICE. The second message is issued every time a client connects and CICS finds that the connection is NOT secured by AT-TLS.