AT-TLS return codes

AT-TLS error message EZD1286I is issued to syslogd to report any errors that occur on an AT-TLS connection when the trace level 2 (Error) is set. AT-TLS error message EZD1287I is issued to the TCP/IP job log to report any errors that occur on an AT-TLS connection when the trace level 1 (Error) is set. These messages include the event that AT-TLS was processing and the return code that indicates a failure. Return codes 5001–5999 describe AT-TLS errors that can be corrected by the user. For more information about these return codes, see Table 2. Return codes 6001–6999 describe internal AT-TLS errors. Contact IBM® with the error message and syslog information, if available. Any other return code is defined by System SSL. For more information about these return codes, see z/OS Cryptographic Services System SSL Programming.

Table 1 lists some common System SSL return codes and possible causes.

Table 1. Common System SSL return codes
Return code	Event	Possible cause and solution
202	Environment Init	The key ring cannot be opened because the user does not have permission. Check the following items: Look at message EZD1281 to verify the user ID being used for this connection and the TTLSEnvironmentAction statement that is mapped to this connection. If you are configuring by using the IBM Configuration Assistant for z/OS® Communications Server, you can specify the key ring on either the AT-TLS: Image Level Settings panel or on each Traffic Descriptor. Ensure that the correct key ring is specified. If you are using a RACF® key ring, verify that all the steps in z/OS Communications Server: IP Configuration Guide are followed for this user ID.
402	Connection Init	An SSL cipher suite could not be agreed upon between the client and server. Check the following items: If V2Ciphers or V3Ciphers are coded, verify that the remote end supports at least one of the cipher suites coded. If you are configuring by using the IBM Configuration Assistant for z/OS Communications Server, the ciphers are selected for each Security Level. Verify that the certificate that is being used for the connection supports the cipher suites. For example, V3 Cipher suite TLS_DH_DSS_WITH_DES_CBC_SHA(0C) requires a certificate that is defined with a Diffie-Hellman key. If ClientCurves is coded, verify that the server is using a certificate that supports one of the elliptic curves. For ciphers defined as exportable, verify that the proper FMIDs to support the encryption level are installed.
406	Connection Init	An I/O error occurred on the socket. An I/O error occurs if the TCP socket is closed underneath the SSL protocol, such as when a reset is received. Check the following items: Ensure that the remote partner is enabled for secure connections. Determine whether the secure negotiation completed. Use the AT-TLS Data trace level to determine whether the secure negotiation completed. Verify that the TCP data flows are sent by the remote partner. Use a TCP/IP packet trace to verify that the TCP data flows are sent by the remote partner.
412	Connection Init	A common SSL protocol type cannot be agreed upon by both partners. This disagreement occurs if both partners do not support the same SSL protocol, as when the client supports only SSLv2 and the server supports only TLSv1. AT-TLS supports only SSLv2, SSLv3, and TLSv1. Check the following items: Determine the protocols that are supported by the remote partner. Code a TTLSEnvironmentAdvancedParms statement, which enables the common protocols. If you are configuring by using the IBM Configuration Assistant for z/OS Communications Server, use a Security Level with cipher levels supported by the remote partner.
422	Connection Init	A v3Cipher that is not valid is found. Check the following items: Determine whether the v3Cipher statement is coded. Verify that the proper SSL FMIDs are installed to support the ciphers specified.
428	Connection Init	The private key cannot be obtained from the certificate. If the private key is stored in ICSF, ensure that ICSF was started before the Policy Agent starting. The TCP/IP job log contains a message that indicates whether System SSL detected ICSF services as available. If ICSF was not started before the Policy Agent, see technote 1433201 for instructions on how to update the AT-TLS policy to detect that ICSF is now available.
434	Connection Init	The certificate key is not compatible with the negotiated cipher suite. Ensure that the certificate that is being used supports the cipher suites that are coded with V2Ciphers or V3Ciphers. If you are configuring by using the IBM Configuration Assistant for z/OS Communications Server, the ciphers are selected in each Security Level.

Table 2 lists some common AT-TLS return codes and possible causes.

Table 2. AT-TLS return codes
Return code	Possible cause and solution
5001	ClientAuthType is set to Required or SAFCheck, but the client did not provide a certificate. Verify that the client supports client authentication and is configured to send its certificate during secure negotiation.
5002	ClientAuthType is set to SAFCheck, but the certificate that is supplied by the client is not defined to SAF subsystem. If you are using RACF, define the client certificate with the RACDCERT command. For more information about using the RACDCERT command, see z/OS Security Server RACF Security Administrator's Guide.
5003	Clear text data is received on the connection from the remote partner instead of secure data. The connection is terminated. Check the following items: Ensure that the remote client is enabled for secure connections. If the policy is defined with ApplicationControlled `On`, ensure that the application read all the cleartext data before it started the secure handshake. If you are configuring by using the IBM Configuration Assistant for z/OS Communications Server, the Application Controlled setting is done in each Traffic Descriptor.
5004	The first HandshakeTimeout interval expired without receiving secure data from the remote partner. The timer is set for the number of seconds specified by the HandshakeTimeout value when the secure connection is initiated. When the first secure data is received from the remote partner, the timer is canceled. Check the following items: This return code can occur if both sides of the connection are configured to be the server in the secure handshake. Review the configuration to ensure that one side acts as the client. For AT-TLS, you can specify the HandshakeRole value in either the TTLSEnvironmentAction or the TTLSConnectionAction statement. If you are configuring by using the IBM Configuration Assistant for z/OS Communications Server, configure the Handshake Role value in each Traffic Descriptor. Increase the HandshakeTimeout value if the remote partner is not responding within the time interval. If you are configuring by using the IBM Configuration Assistant for z/OS Communications Server, you can set the Timeout value in each Traffic Descriptor; you can override the value in each Connectivity Rule.
5005	The second HandshakeTimeout interval expired and the secure handshake is not finished. This interval is set to 10 times the HandshakeTimeout interval. The secure negotiation is started and the initial secure message is received from the remote partner. If the remote partner is an interactive application, such as requiring the user to select a certificate, either increase the HandshakeTimeout value or have the user try the connection again. The HandshakeTimeout value might need to be increased if LDAP is being used to manage certificates. Increasing the value provides more time for the LDAP processing to occur. If you are configuring by using the z/OS Network Configuration Assistant, the Handshake Timeout value can be set in each Traffic Descriptor and can be overridden in each Connectivity Rule.
5006	The connection is using a TTLSEnvironmentAction statement that failed to initialize a System SSL environment. Use the syslog to determine why the System SSL environment failed to initialize. If the TTLSEnvironmentAction statement is in error, make the necessary corrections. A System SSL environment is initialized for the corrected TTLSEnvironmentAction statement and new connections use that environment. If a SAF configuration change is needed (such as changing a certificate in the key ring), make the change and then update the EnvironmentUserInstance parameter in the TTLSEnvironmentAction statement to reflect a changed action. A System SSL environment is initialized by using the modified RACF configuration and new connections use that environment. If you are configuring by using the z/OS Network Configuration Assistant to pick up changes that are made to a key ring, go to the AT-TLS Image Level Settings panel and click the Reaccess Key Rings button and update the Instance ID for the changed key ring.
5007	Application data is read during processing of ciphertext negotiation. Collect the syslogd output or job log output and contact IBM.
5008	Application data was received after the local application closed the TCP connection. The data could not be presented to the application. Review the local and remote applications to ensure that the TCP sockets are being closed correctly in the application flow. If further diagnostic information is needed, set the trace level to 255, to trace the data flow and AT-TLS processing.
5009	AT-TLS was unable to obtain TCPIP private storage. Obtain a console dump of TCPIP and contact IBM
5010	AT-TLS was unable to obtain the ACEE for an application. Save the syslogd output and contact IBM
5011	AT-TLS does not have an Envar object for the applications ACEE. Save the syslogd output and contact IBM
5012	An internal AT-TLS error occurred. Save the syslogd output and contact IBM
5013	AT-TLS was unable to clone the SAF environment for the application. Save the syslogd output and contact IBM.
5014	AT-TLS was unable to extract ACEE into ENVAR value. Save the syslogd output and contact IBM.
5015	AT-TLS was unable to process the connection because the connection is already terminated. Review the syslogd output to determine whether the connection is terminated by the remote partner. TTLS trace level 8 (flow) and 16 (event) can be used to gather more information.
5016	AT-TLS attempted to read ciphertext negotiation data, but an internal error occurred. Save the syslogd output and contact IBM
5017	The application tried to write data on a secure connection that is closed by the remote application. Review the local and remote applications to ensure that the TCP sockets are being closed correctly in the application flow. If further diagnostic information is needed, set the trace level to 255, to trace the data flow and AT-TLS processing.
5018	An internal error occurred processing a TTLSGroupAction. Save the syslogd output and contact IBM.
5019	Task level security could not be created. BPX1TLS failed. Save the syslogd output and contact IBM.
5020	AT-TLS was unable to load the GSKSSL library. Ensure that the SIEALNKE PDSE library is available to the TCPIP started task. For more information, see z/OS Cryptographic Services System SSL Programming.
5021	The HandshakeTimeout interval expired for the SIOCTTLSCTL TTLS_Stop_Connection request without receiving a close notify alert from the remote peer. The timer is set for the number of seconds that the HandshakeTimeout value specifies when the TTLS_Stop_Connection request is initiated. The timer is canceled when a close notify alert is received from the remote peer. Increase the HandshakeTimeout value if the remote peer is not responding within the time interval. If you are configuring by using the IBM Configuration Assistant for z/OS Communications Server, you can set the timeout value in each Traffic Descriptor; you can override the value in each Connectivity Rule.
5022	Encrypted application data is received from the remote peer when the SIOCTTLSCTL TTLS_Stop_Connection request is being processed. All application data that needs to be encrypted must be sent before the TTLS_Stop_Connection request. The application protocol needs to ensure all sending and receiving of secure data on the connection is complete before TTLS_Stop_Connection is requested. Review the application protocol to determine why the secure data is sent on the connection.
5023	AT-TLS called initACEE with a nested ENVR object and requested a managed ACEE, which is not supported. If AT-TLS was processing a data connection from the FTP server, ensure the AT-TLS policy has SecondaryMap On coded for the FTP control connection. A separate TTLSRule for the FTP data connection is not supported. Otherwise, save the syslogd output and contact IBM.
5024	AT-TLS was unable to enable FIPS 140 support. See message EZD2026I for more details about the error that is received from System SSL.
Return codes 6001–6999 describe internal AT-TLS errors.	An internal AT-TLS error occurred. Contact IBM with the error message and syslog information, if available.