If you must resort to low-level debugging options, we recommend that you enable the JVM's support for TLS debugging. Many of the command-line tools that are provided with PingDirectory Server, such as ldapsearch, offer an --enableSSLDebugging argument that simplifies this process. For other tools, perform the following steps:

  1. In the config/java.properties file, add the following line to the set of properties for the appropriate tool:

    -Djavax.net.debug=all
  2. To make the change take effect, run the bin/dsjavaproperties command.

The next time the tool is run, it generates voluminous output detailing the TLS-related processing that the JVM is performing. Potential clues in the output might allow you or the team to identify the issue.

To enable low-level debugging within the server, perform the following steps:

  1. In the config/java.properties file, add the following line to the start-server.java-args property:

    -Djavax.net.debug=all
  2. Run bin/dsjavaproperties.
  3. Restart the server.

Because this approach requires multiple server restarts, it is not highly attractive. However, you might be able to obtain more information without a restart by using the debugging support that is built into the server. To enable this level of support, make the following configuration changes:

dsconfig create-debug-target \
     --publisher-name "File-Based Debug Logger" \
     --target-name com.unboundid.directory.server.extensions.TLSConnectionSecurityProvider \
     --set debug-level:verbose
 
dsconfig set-log-publisher-prop \
     --publisher-name "File-Based Debug Logger" \
     --set enabled:true

After you make these changes, the logs/debug file captures a substantial amount of information about the TLS-related processing that the server is performing. Although this file does not provide as much detail as the JVM's built-in debugging information, it might help to pinpoint the cause of the problem, and to identify potential solutions. When you no longer require this level of debugging, disable the debug log publisher and remove the debug target, as follows:

dsconfig set-log-publisher-prop \
     --publisher-name "File-Based Debug Logger" \
     --set enabled:false
 
dsconfig delete-debug-target \
     --publisher-name "File-Based Debug Logger" \
     --target-name com.unboundid.directory.server.extensions.TLSConnectionSecurityProvider

To troubleshoot TLS communication with a non-Java client that does not offer its own TLS debugging mechanism, and if the server-side debugging support is insufficient, use a network protocol analyzer to capture the communication between the client and the server, and to examine its content. The free open-source Wireshark utility is an excellent graphical tool that runs on a variety of platforms and provides excellent support for understanding TLS communication. Even if you cannot decipher the encrypted content, you can view at least some of the handshake messages. Unfortunately, more of the handshake is encrypted in TLS version 1.3 than in earlier versions of the protocol. Although this change improves security and privacy, it may interfere with troubleshooting attempts.