Steps for diagnosing AT-TLS problems

Diagnose AT-TLS problems.

Procedure

Perform the following steps:

  1. Issue pasearch -t to see all AT-TLS policies that are active in Policy Agent. See z/OS Communications Server: IP System Administrator's Commands for more information about the pasearch -t command. If you are running multiple stacks, ensure that pasearch is reporting on the stack you are interested in. If you do not see the AT-TLS policies that you expected, see z/OS Communications Server: IP System Administrator's Commands for more information about displaying policy based networking information.
  2. Issue Netstat TTLS COnn connid or Netstat -x COnn connid to determine whether the stack mapped a connection to AT-TLS policy and, if so, to which policy it was mapped. For more information about the netstat commands, see z/OS Communications Server: IP System Administrator's Commands. Ensure that your AT-TLS policies are correctly defined. See the AT-TLS information in z/OS Communications Server: IP Configuration Guide and the AT-TLS Policy statements in z/OS Communications Server: IP Configuration Reference for more information about configuring AT-TLS policies.
  3. In cases where AT-TLS connections do not map to any policy, verify that TCPCONFIG TTLS has been specified. Netstat configuration shows the current setting of AT-TLS.
    AT-TLS connection mapping is performed based on the following attributes:
    • Local IP Address
    • Remote IP address
    • Local Port
    • Remote Port
    • Direction
    • Job name
    • User ID

    The AT-TLS policy rules are searched, starting with the highest priority rules, for the first match.

    Then the internal SecondaryMap table is searched by process ID and the two IP addresses used on the connection. The SecondaryMap table contains entries for active connections that are mapped by the AT-TLS policy rule to a policy with the SecondaryMap attribute specified as On. If entries are found using both methods, the one found by the AT-TLS policy rule is used unless the one found by the SecondaryMap value has a higher priority.

    If a TCP connection is not matching the expected rule, do one of the following:
    • Ensure that the AT-TLS policies are active and that no errors occurred. Message EZZ8438I is issued if Policy Agent encountered any errors while processing the AT-TLS policy. If errors occurred, review the Policy Agent logs for details on the error and correct the AT-TLS policy. You can use OBJERR to search the Policy Agent logs to find the errors.
    • Verify the rule and actions that the policy mapped to and the priority of the rule. You can use the pasearch command can be used to view the active AT-TLS policy. AT-TLS message EZD1281I is issued with all the parameters used to map to the AT-TLS policy, if trace level 4 is on.
  4. If an error message was issued by AT-TLS, review the syslogd files for message EZD1286I or the TCP/IP joblog for message EZD1287I. The error message might provide information about correcting the problem.
  5. Start of changeIf an error occurred when processing the remote peer's certificate during the TLS negotiation, review the syslogd files for certificate diagnostics message EZD2052I. These errors can occur when the TLS client is validating the server's certificate. Or if client authentication is being used for the negotiation, the error can occur when the TLS server is validating the client's certificate.
    Message EZD2052I provides a description of the error that occurred, detailed return codes, and information about the failing certificate which includes the subject DN, issuer DN, and serial number. If additional certificate information is needed, increase the AT-TLS trace to include Event (8). Recreate the error to get messages EZD2053I and EZD2054I that identify the chain of certificates used in the failed certificate validation.     End of change
  6. If the error is re-creatable, turn on an AT-TLS trace for the connection. Turn on the trace by coding a TTLSRule specific to the failing connection. Include a TTLSConnectionAction statement that has the Trace statement set to 255 (All). If configuring using the IBM® Configuration Assistant for z/OS® Communications Server, the trace level can be set in each Connectivity Rule.
  7. If the problem cannot be resolved from the trace, perform a packet trace or a CTRACE with option TCP to provide additional debugging information and contact IBM service.
  8. If System SSL tracing is needed, enable the GSKSRVR CTRACE with option Level=255. The JOBNAME specification needs to be the TCP/IP stack name. The GSK_TRACE and GSK_TRACE_FILE environment variables cannot be used to capture System SSL tracing when using AT-TLS. For more information about this trace, see Obtaining diagnostic information in Cryptographic Services System Secure Sockets Layer Programming manual.