Enable Java SSL Debug Logging

1. Overview

Java Secure Socket Layer (SSL) debugging is crucial for developers and administrators to diagnose and troubleshoot issues related to establishing secure connections in applications. Enabling SSL debugging provides insights into the handshake process, cipher suites negotiation, and other security-related activities. 

In this tutorial, we’ll explore various ways of enabling Java SSL debugging through a series of practical examples.

2. Why Enable SSL Debug Logging?

The SSL/TLS protocols are fundamental for securing data transmission over the internet.

When using these protocols in applications, we can use SSL debugging to enhance both the security and efficiency of SSL-protected communications in our systems. Some of the ways it can help us include:

• Identifying anomalies such as certificate mismatches and connection failures
• Monitoring against malicious activity
• Ensuring we’re using the appropriate implementation of an encryption algorithm
• Optimizing performance

An output snippet might look like this:

%% Initialized: [Session-1, SSL_RSA_WITH_AES_256_CBC_SHA]
Cipher Suite: SSL_RSA_WITH_AES_256_CBC_SHA
ServerKeyExchange: EC Diffie-Hellman Server Params: [...]
*** ServerHelloDone
Cert chain length: 1
*** Certificate chain
[...]
Application data: "Hello, World!"

In this example, the output begins with session initialization, followed by details on the chosen cipher suite, key exchange parameters, and the completion of the handshake. It also includes information about the certificate chain and application data being transferred securely.

3. Using Command-Line Options

One straightforward way to enable SSL debug logging is through the command-line option. Java allows us to configure it via the javax.net.debug system property. This property accepts various debugging options, allowing users to customize the level of detail in the debugging output:

java -Djavax.net.debug=ssl -jar MyApp.jar

This command activates debugging for all SSL-related activities. For more detailed debugging, some other useful options are:

• handshake for detailed information during SSL handshake
• keygen for key generation details
• record for information about record layer processing

The entire list of options is available in the official documentation.

Let’s utilize the handshake option to generate SSL logs that pertain to the handshake process:

java -Djavax.net.debug=ssl:handshake -jar MyApp.jar

When the above command is executed, the output contains details of the handshake. It’s useful when troubleshooting issues during the initial phase that establishes the SSL/TLS connection between a client and a server. Below is a snippet of the log:

Allow unsafe renegotiation: false
Allow legacy hello messages: true
Is initial handshake: true
Is secure renegotiation: false
...
main, READ: TLSv1.2 Handshake, length = 232
...
*** ClientHello, TLSv1.2
...

The output includes information about the negotiation process, the protocol version being used (in this case, TLSv1.2), and details about the initial handshake messages exchanged between the client and the server.

4. Using System Properties

In some scenarios, we may want to enable SSL debug logging dynamically at runtime. We can do this by changing the value of the javax.net.debug system property programmatically:

static void enableSSLDebugUsingSystemProperties() {
    System.setProperty("javax.net.debug", "ssl");
}

Let’s attempt to initiate a dummy HTTPS request to retrieve the logs:

static void makeHttpsRequest() throws Exception {
    String url = "https://github.com/eugenp/tutorials";
    URL httpsUrl = new URL(url);
    HttpsURLConnection connection = (HttpsURLConnection) httpsUrl.openConnection();

    try (BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
        String line;
        logger.info("Response from " + url + ":");
        while ((line = reader.readLine()) != null) {
            logger.info(line);
        }
    }
}

This approach allows us to toggle logging on and off based on specific events or conditions in our application:

@Test
void givenSSLDebuggingEnabled_whenUsingSystemProperties_thenEnableSSLDebugLogging() {
    ByteArrayOutputStream outContent = new ByteArrayOutputStream();
    System.setErr(new PrintStream(outContent));

    SSLDebugLogger.enableSSLDebugUsingSystemProperties();
    assertEquals("ssl", System.getProperty("javax.net.debug"));
    
    SSLDebugLogger.makeHttpsRequest();
    assertTrue(outContent.toString().contains("javax.net.ssl|DEBUG|"));
    outContent.reset();

    System.clearProperty("javax.net.debug");
    assertNull(System.getProperty("javax.net.debug"));
    
    SSLDebugLogger.makeHttpsRequest();
    assertEquals(outContent.toString(),"");
}

Enabling SSL debugging using system properties offers a quick setup that doesn’t require any configuration files and allows for on-the-fly debugging.

5. Using Logging Configuration File

We can also configure Java Logging to capture SSL debugging information. By creating a logging.properties file and placing it in the classpath, we can customize the logging behavior.

Let’s add the following lines to the logging.properties file to enable logging:

java.util.logging.ConsoleHandler.level=ALL
java.net.ssl.handlers=java.util.logging.ConsoleHandler
javax.net.ssl.level=ALL

These properties tell the console handler to capture messages at all levels.

Let’s test the new behavior with a unit test:

@Test
void givenSSLDebuggingEnabled_whenUsingConfigurationFile_thenEnableSSLDebugLogging() throws IOException {
    InputStream configFile = SSLDebugLoggerUnitTest.class.getClassLoader().getResourceAsStream("logging.properties");
    LogManager.getLogManager().readConfiguration(configFile);

    Logger sslLogger = Logger.getLogger("javax.net.ssl");
    ConsoleHandler consoleHandler = (ConsoleHandler) sslLogger.getHandlers()[0];
    Level consoleHandlerLevel = consoleHandler.getLevel();

    assertEquals(Level.ALL, consoleHandlerLevel, "SSL ConsoleHandler level should be ALL");
}

This approach provides granular control over SSL debugging settings, but any changes typically require an application restart.

6. Conclusion

In this article, we saw various ways of enabling SSL debug logging in Java, which can be leveraged to gain valuable insights into the handshake process, certificate validation, and other aspects of secure communication. This facilitates the prevention and resolution of security-related issues.

As always, the full source code is available over on GitHub.