Documentation

You are viewing the documentation for the 2.5.4 release in the 2.5.x series of releases. The latest stable release series is 3.0.x.

§Debugging SSL Connections

In the event that an HTTPS connection does not go through, debugging JSSE can be a hassle.

WS SSL provides configuration options that will turn on JSSE debug options defined in the Debugging Utilities and Troubleshooting Security pages.

To configure, set the play.ws.ssl.debug property in application.conf:

play.ws.ssl.debug = {
    # Turn on all debugging
    all = false
    # Turn on ssl debugging
    ssl = false
    # Turn certpath debugging on
    certpath = false
    # Turn ocsp debugging on
    ocsp = false
    # Enable per-record tracing
    record = false
    # hex dump of record plaintext, requires record to be true
    plaintext = false
    # print raw SSL/TLS packets, requires record to be true
    packet = false
    # Print each handshake message
    handshake = false
    # Print hex dump of each handshake message, requires handshake to be true
    data = false
    # Enable verbose handshake message printing, requires handshake to be true
    verbose = false
    # Print key generation data
    keygen = false
    # Print session activity
    session = false
    # Print default SSL initialization
    defaultctx = false
    # Print SSLContext tracing
    sslctx = false
    # Print session cache tracing
    sessioncache = false
    # Print key manager tracing
    keymanager = false
    # Print trust manager tracing
    trustmanager = false
    # Turn pluggability debugging on
    pluggability = false
}

Note: This feature changes the setting of the java.net.debug system property which is global on the JVM. In addition, this feature changes static properties at runtime, and is only intended for use in development environments.

§Verbose Debugging

To see the behavior of WS SSL, you can configure the SLF4J logger play.api.libs.ws.ssl for debug output. For example, if you are using Logback, in conf/logback.xml you would configure:

<logger name="play.api.libs.ws.ssl" value="DEBUG"/>

§Dynamic Debugging

If you are working with WSClient instances created dynamically, you can use the SSLDebugConfig class to set up debugging using a builder pattern:

val debugConfig = SSLDebugConfig().withKeyManager().withHandshake(data = true, verbose = true)

§Further reading

Oracle has a number of sections on debugging JSSE issues:

Next: Loose Options