z/OS
Communcation Server
A typical message would look like one of the following:
EZZ6035I TELNET DEBUG CLIENT
IPADDR..PORT 129.255.16.30..1297
395
RCODE: 6002-00
SSL/TLS handshake failed.
PARM1: 00000191 PARM2:
PARM3: GSK_SECURE_SOCKET_INIT
EZZ6035I TELNET DEBUG CLIENT
IPADDR..PORT 9.24.106.91..1290
747
RCODE: 600E-00 SSL handshake Timed
out.
PARM1: FFFFFFEA PARM2: 00000000 PARM3: 00000000
The RCODEs are explained in z/OS V1R6 Communcation Server Messages Vol. 4. Parm1 is also an important field. It is the return code from System SSL. The most common return codes are listed in the Vol 4 Messages book. All the others are listed in z/OS V1R6.0 System SSL Programming. The return code in PARM1 is presented as a hexadecimal number but they are listed in the System SSL Programming manual as a decimal number. It is usually best to use the search function to find the decimal return code in System SSL Programming..
In the above examples, System SSL Programing interpretes the above PARM1 codes as follows:
401 Certificate is expired or
is not valid yet.
Explanation: The current time is
either before the certificate
start time or after the certificate end
time.
User Response: Obtain a new
certificate if the certificate is expired
or wait until the certificate
becomes valid if it is not valid yet.
-22 Socket closed by remote partner.
Explanation: The remote partner
closed the socket.
User Response: None.
Most of these problems trace back to a configuration issue. In the TELNET server, there are two required parameters for SSL support, SECUREPORT and KEYRING, and one optional parameter, CONNTYPE, for TLS support. They are fully explained in z/OS V1R6.0 CS: IP Configuration Reference.
The majority of the configuration involves managing the certificates. The Communcation Server Implementation Guide, Vol. 7, Security RedBook has a step by step process for the most commonly used certificate activities. Additionally, there is a document on our IBM Software - z/OS Communications Server - Support website titled Telnet SSL/TLS Quick Debug Reference that will be helpful.
SSL uses a public/private key pair to set up a secure connection. Date encrypted with a public key requires the private key for decryption and vise versa. The X.509 certificate contains the server’s public key and (among other things) the digital signature of the issuer of the certificate. The client will then use the issuer’s digital signature (sometimes called a trusted root) to decrypt the server’s certificate and thus obtain the server’s public key. This public key is then used to encrypt data with the server. The server can decrypt this data with it’s private key. So, at a minimum, the server must have and use a certificate and the client must have and use the trusted root from the certificate issuer (sometimes know as the Certificate Authority).
Most of the configuration issues revolve around creating or importing a certificate into the server’s keyring file (sometimes managed by SAF and sometimes by GSKKYMAN) or importing the ‘trusted root’ into the client. When client authentication is used, there is also a client certificate that will be imported into both the client and the server.