API Gateway: Log and debug SSL/TLS traffic on the Gateway

book

Article ID: 132334

calendar_today

Updated On:

Products

CA API Gateway

Issue/Introduction

This article will discuss enabling logging and debugging for SSL and TLS traffic on the API Gateway appliances. In some cases, reviewing SSL communication executed by the underlying Gateway Java system is necessary to troubleshoot handshake issues between (for example) an application client and the API Gateway. In order to do so, Java SSL debug must be turned on.

This is recommended only for troubleshooting purposes.

Environment

This article applies to all supported versions of the API Gateway. Please pay special attention to the steps which differ for version 10.0 CR03 and newer.

Resolution

Follow the steps below to enable extra logging and debugging for SSL/TLS traffic to the API Gateway.

  1. Set the following cluster-wide properties (CWPs):
    1. io.debugSsl = true
    2. If running version 10.0 CR02 and earlier:
      1. log.stdoutLevel = FINE
      2. Add the following line to the bottom of the log.levels CWP: STDOUT.level = FINE
    3. If running version 10.0 CR03 and later:
      1. log.stderrLevel = FINE
      2. Add the following line to the bottom of the log.levels CWP: STDERR.level = FINE
  2. Create a new log sink for SSL debug logs:
    1. Click on Tasks > Logging and Auditing > Manage Log/Audit Sinks
    2. Click on Create and create a new custom log with the following properties:
      1. Name: ssl
      2. Description: SSL debug logs
      3. Severity Threshold: FINE
      4. Add two filters:
        1. Filter Type = Category, Filter Details = Gateway Log
        2. If running version 10.0 CR02 and earlier:
          1. Filter Type = Package, Filter Details = STDOUT
        3. If running version 10.0 CR03 and later
          1. Filter Type = Package, Filter Details = STDERR
      5. Check the Enabled option to enable the new log
      6. Click OK to save the log sink configuration
  3. Configure the JVM from the Gateway privileged shell:
    1. Append javax.net.debug=<options> to the system.properties file.
      1. Open the properties file using vi /opt/SecureSpan/Gateway/node/default/etc/conf/system.properties
      2. Set javax.net.debug=<options> according to the options specified in Java 8 Secure Socket Extension (JSSE) Reference Guide > Debugging Utilities
        • Example values:    javax.net.debug=all    or    javax.net.debug=ssl:handshake:verbose.      
        • Note: Do not to use the option help. It may cause some providers to terminate the JVM.
      3. Save the changes
      4. Restart the Gateway service:  service ssg restart
  4. Verify SSL debug logging is enabled by consuming a service using an HTTPS Listen Port.
    1. The debug logs are sent only to the configured log sink, and will appear in files based on the log sink name configured earlier. For example:     /opt/SecureSpan/Gateway/node/default/var/logs/ssl_0_0.log

Attachments