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

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
    4. If running version 10.1 and later:
      1. log.stderrLevel = FINEST
      2. Add the following line to the bottom of the log.levels CWP: STDERR.level = FINEST
    5.  If running version 11.0 and later:
      1. log.stderrLevel = FINEST
      2. Add the following line to the bottom of the log.levels CWP: STDERR.level = FINEST

     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  ( for Gateway 10.1 FINEST)
      4. Add two filters:
        1. Filter Type = Category, Filter Details = Gateway Log
        2. If running version 10.0 CR02 and earlier:
          1.  
          2. Filter Type = Package, Filter Details = STDOUT
        3. If running version 10.0 CR03 and later: 
          • Filter Type = Package, Filter Details = STDERR
        4. If running version 11.0 and later: 
          • 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. For Appliance Gateway , 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.    ( for Gateway 10.1  use  javax.net.debug=ssl:handshake:verbose.  for ssl )
        • 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
    2. For software Gateway,  Edit the ssgruntimedefs.sh script:   
        1. Open the file using vi /opt/SecureSpan/Gateway/runtime/etc/profile.d/ssgruntimedefs.sh
        2. Append the following line: "SSG_JAVA_OPTS="$SSG_JAVA_OPTS -Djavax.net.debug=all"  just before the "unset default_java_opts"
        3. 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.    ( for Gateway 10.1  use  javax.net.debug=ssl:handshake:verbose.  for ssl )
          • javax.net.debug=all ( Gateway 11.x )
          • Note: Do not to use the option help. It may cause some providers to terminate the JVM.
        4. Save the changes
        5. Restart the Gateway service:  /opt/SecureSpan/Gateway/runtime/bin/gateway.sh stop and /opt/SecureSpan/Gateway/runtime/bin/gateway.sh start

 

      4. Verify SSL debug logging is enabled by consuming a service using an HTTPS Listen Port.

              - 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

For container gateway: 

Modify yaml file: 

in config section 

add the option

-Djavax.net.debug=ssl:handshake:verbose 
to javaArgs. 

Additional Information

With -Djavax.net.debug you get

     all             turn on all debugging
     ssl            turn on ssl debugging

The following can be used with ssl:

    record             enable per-record tracing
    handshake      print each handshake message
    keygen            print key generation data
    session           print session activity
    defaultctx        print default SSL initialization
    sslctx              print SSLContext tracing
    sessioncache print session cache tracing
    keymanager   print key manager tracing
    trustmanager print trust manager tracing
    pluggability    print pluggability tracing

    handshake debugging can be widened with:
    data              hex dump of each handshake message
    verbose        verbose handshake message printing

    record debugging can be widened with:
    plaintext       hex dump of record plaintext
    packet          print raw SSL/TLS packets

Powered by Wolken Software