AT-TLS errors

While establishing a connection with a remote RRSF node, the initiating system issues a socket connect() call and the receiving system issues an accept(). Then, both sides of the connection issue a select() on the established socket. The select causes TCP/IP to perform the TLS handshake with the assistance of System SSL. The handshake process determines the AT-TLS policy rule used to protect the connection on each system and applies that policy. The policy identifies the RACF® key ring that contains the digital certificates required to authenticate each server to the other.

If the handshake fails, RRSF usually issues message IRRI031I. AT-TLS tracing, by default, logs errors and provides an error code. See z/OS Communications Server: IP Diagnosis Guide for more information about the error code. The AT-TLS trace level is specified in the AT-TLS rule for a connection. Because the TLS handshake is performed on both systems and the error might have occurred on only one of the systems, be sure to look in the trace log on the remote system if there is no helpful information about the system you are currently logged on to.

TLS handshake errors are usually caused by certificate or key ring setup errors, and this might not always be obvious from the error code description. The following checks generally identify the problem:

On each system, use the RACDCERT LISTRING command to check that the key ring specified in the policy rule (the sample policy that RACF provides in the IRRSRRSF member of SYS1.SAMPLIB specifies IRR.RRSF.KEYRING and if using IBM® Configuration Assistant, it specifies tlsKeyring) is defined for the RACF subsystem user ID. Note that key ring names are case-sensitive.
Verify that the key ring contains a digital certificate for the RRSF server (the RACF subsystem user ID) as the default.
Verify that the key ring contains the RRSF signing certificate and it is trusted.
Verify that the RACF subsystem user ID has authority to read its own key rings (this is generally accomplished by granting READ access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class). Note that this permission is required even if the RACF subsystem started task definition specifies TRUSTED or PRIVILEGED.

Other problems that might occur are:

A certificate has expired.
The key type associated with the certificate is not valid for the cipher algorithm requested in the policy.
Some aspect of the AT-TLS policy requires ICSF, (for example, if the certificate private key is stored in the ICSF PKDS), but ICSF was not started when RRSF connections were attempted.
There is a logical inconsistency between the policy files as they exist on the local and the remote system. Typically, both systems should have the same policy statements for RRSF, both for the "client" and "server" portions of the policy.

After correcting any key ring problems, including an authorization problem, make sure that the policy agent reads the contents of the key ring again, by changing the EnvironmentUserInstance value in the policy rule. If you are using Configuration Assistant, click Reaccess Key Rings... under image level settings, for a given image. After the policy is updated, refresh the policy agent by issuing the following command from the console:

F PAGENT,UPDATE

After correcting an ICSF problem (such as starting ICSF after an RRSF connection has failed because ICSF was not available), you must change the GroupUserInstance value, and then update the policy agent as shown above. Your system configuration must start ICSF earlier in the IPL sequence (before the policy agent starts) so that you avoid this problem on the next IPL.

Note that these keywords might not be in your policy. Specifically, if using the sample policy, the GroupUserInstance keyword is not specified. If so, see for information about where to add this statement in your policy.