Why would a TN3270 session fail establishment with error code 6002 when SSL is enabled?

With this type of problem you typically see TCPIP issuing this diagnostic error message:

EZZ6034I TELNET CONN connid LU N/A CONN DROP ERR 6002 IP..PORT: ipaddr..port

Error code 6002 reported in the message indicates that the SSL handshake process performed between the server and the client failed. This handshake for the server is performed by the System SSL component of z/OS, and can indicate a problem with the certificates being used (either locally or by the client system) or the SSL configuration.

A common cause of this problem is expired certificates, such as:

• server certificate

• the client certificate (if CLIENTAUTH is configured)

• any of the certificates used in signing these

In addition, when using a locally created (self-signed) certificate instead of a well-known certificate authority, that root certificate must be available and marked as trusted on the keyring of both the client and server. If any of those conditions are not satisfied, this failure can occur.

Finally, the server certificate must be on the keyring, marked as the default certificate and must contain the private key. If any of those conditions are not satisfied, this failure can occur as well.

To pinpoint the source of the problem, enable DEBUG DETAIL in the applicable Telnet parameters section (TELNETGLOBALS, TELNETPARMS, or PARMSGROUP). When a subsequent failure occurs, an EZZ6035I message will be generated with additional details about the failure:

EZZ6035I TELNET DEBUG DETAIL CLIENT 101 IP..PORT: aa.bb.cc.dd..ppp CONN: xxxxxxxx LU: MOD: EZBTTSMT RCODE: 6002-00 SSL/TLS handshake failed. PARM1: nnnnnnnn PARM2: 00000000 PARM3: GSK_rrrrrrrrrrrr

The PARM1 value (which is in hexadecimal) will be the SSL Function Return Code indicating the nature of the failure. PARM3 identifies the System SSL API function that returned this failure. The most common functions returning this failure are:

• GSK_ENVIRONMENT_INIT, which is most likely due to setup or access (SAF/RACF) to the specified KEYRING.

• GSK_SECURE_SOCKET_INIT, which is likely due to a rejection of (one of) the certificate(s) being used.

If Application Transparent TLS (AT/TLS) is being used for the TN3270 server (TTLSPORT is used instead of SECUREPORT), debugging should be enabled in the associated policies. See the section in the IP Diagnosis manual for a list of actions to perform.

Additional diagnostic data can be obtained by collecting a System SSL trace. The GSKSRVR CTRACE must be used to capture this, which requires having the GSKSRVR started task active before starting TN3270 (or TCPIP, if running the server in the stack). The sample proc provided in the SGSKSAMP library can be used without modification if no other features are going to be enabled.

Review the certificates being accessed on both the server and the affected clients. If using a UNIX Key Database, then the gskkyman command should be used to report the certificate contents. If using RACF keyrings to store the certificates, then the RACDCERT command (from an appropriately authorized user) should be used. For security products from other vendors (or on the TN3270 client software), consult their documentation.

IBM Q&A support for System SSL may be used to assist in interpreting the collected diagnostic data and establishing the proper configuration.

Related information

• Avoiding SSL Certificate Expiration

• TN3270 SSL Common Problems

• IP Configuration Guide Appendix B - TLS/SSL Security