This document provides an alternative to Java's TLS/SSL debug flag by using jSSLKeyLog and Wireshark. 

GOAL

When debugging a network issue related to TLS/SSL, we often use Server's Private key(server.key) which is explained in Decrypting SSL on Wireshark

Pros:

• It's easy to get primary server's private key and add it to Wireshark's RSA Keys List.

Cons:

• Need to change the tomcat server configuration to exclude any Diffie Hellman based encryption ciphers (TLS_DHE, TLS_ECDHE etc) since those can not be decrypted by Wireshark
• For Satellite Servers(Configured with any of the SSL roles)we need to extract the private key from jetty-keystore.jks
  
  

The current document provides steps to debug SSL/TLS traffic using jSSLKeyLog which doesn't require RSA Keys List and no need to change the tomcat server configuration to exclude any Deffie Hellman based encryption ciphers

PROCEDURE

How does it work?

TLS/SSL handshake uses asymmetric (public/private) keys to negotiate a symmetric key. After the handshake is complete, the symmetric key is used to encrypt/decrypt the application data (payload) to be transmitted over the wire. jSSLKeyLog is a Java agent which can be injected into the JVM to dump the symmetric key to a file, which then is used later by Wireshark to decode the SSL traffic. 

Steps:

1) Download jSSLKeyLog from http://jsslkeylog.sourceforge.net/ (or) https://jsslkeylog.github.io/, unzip it and copy the jar file to a local directory on ZENworks Primary or Satellite servers.

     eg: On Windows : C:\jSSLKeyLog\jSSLKeyLog.jar

           On Linux: /tmp/jSSLKeyLog.jar

 2) Configure jSSLKeyLog as a Java parameter (JVM Flag)

      eg:  1. On Windows Primary Server Server add the following to ZENServer Service Manager Java Options. ( Double click ZENServerw.exe → Java tab → Java Options)                      

                   -javaagent:C:\jSSLKeyLog\jSSLKeyLog.jar==C:\jSSLKeyLog\jssl-key.log   and restart the ZENServer Service

             2. On Linux Primary Server add the following to JAVA_PROPS in "systemd.zenserver"  file.

                  JAVA_PROPS="-Djava.awt.headless=true -Dcatalina.home=$CATALINA_HOME -Djava.io.tmpdir=$TMP_DIR -javaagent:/tmp/jSSLKeyLog.jar==/tmp/jssl-key.log" and restart the ZENServer Service

             3. On Windows Satellite Server (Configured with any of the SSL roles) add the following to Jetty Service Manager Java Options. ( Double click ZENJettyServerw.exe → Java tab → Java Options)

                  -javaagent:C:\jSSLKeyLog\jSSLKeyLog.jar==C:\jSSLKeyLog\jssl-key.log   and restart the Novell ZENworks Jetty Server Service.

            4. On Linux Satellite Server (Configured with any of the SSL roles) add the following to EXTRA_OPTS in "systemd-xplatzmd"  file.

                 -javaagent:/tmp/jSSLKeyLog.jar==/tmp/jssl-key.log and restart the xplatzmd service.

            In all of the above jssl-key.log is the file that jSSLKeyLog writes the symmetric keys to.

3) Capturing network traffic between agent and primary server (or) satellite server using tcpdump or wireshark tool. 

     (a)  If you are capturing network traffic on the primary server or satellites, then in WireShark, choose menu "Preferences" -> "Protocols" -> "SSL" -> "(Pre)-Master-Secret log filename" -> browse to the jSSLKeyLog output file.(jssl-key.log)

            Note: In latest versions of WireShark, the Protocol is called "TLS" instead of the previous "SSL".

 (b) After capturing the traffic, opening it in WireShark, the encrypted "Application Data" now shown as clear text.

Note: in some versions of WireShark, the Application Data is still encrypted. You need to select the encrypted frame, look at the byte view, and specifically the tabs underneath the view. You should see a tab "Decrypted TLS" where you will be able to see the decrypted data.

Write mouse click on an entry "Follow" -> "SSL Stream" (or) "TLS Stream"

You will see the complete clear text HTTP payload.

With this approach, we are able to easily capture only (say to a certain host:port) the traffic we needed and decode the TLS/SSL traffic to troubleshoot HTTPS related issues. It is recommended to use latest version of WireShark and note that for decoding ECDSA ciphers, at least Wireshark 1.11.3 is required.