Summary

Fix the the javax.net.debug TLS debug system property to work as per documentation in help output menu. Update the help menu to remove old debug options and add new ones also.

Problem

Use of the javax.net.debug TLS debug system property is buggy since TLSv1.3 implementation was introduced.

Where "ssl" was previously a property value to obtain all TLS debug traces (except network packet type dumps, verbose data), it now (incorrectly) prints only a few lines for a standard client TLS connection.

The property parsing was also lax and allowed users to declare verbose logging options by themselves where the documentation stated that such verbose options were only meant to be used in conjunction with other TLS options as per the help output menu.

The help menu printed via the javax.net.debug=help setting is inaccurate also. It contains options which are obsolete. It's also missing valid options.

Solution

Fix up the javax.net.debug logging implementation to log TLS debug output as per help output. Main change here is to restore the behaviour where javax.net.debug=ssl will log all TLS debug output except data deemed too verbose: data that's controlled via extra 'expand' debug property settings. The 'expand' options currently are: "verbose", "plaintext" and "packet".

Create a release note to highlight the tightening of debug options and how the expand options only work with parent options first being specified. The security documentation will also be updated to highlight these changes.

While the lack of logging output with javax.net.debug=ssl should be fixed in all JDK releases back to and including JDK 8 Updates, the tightening of parsing options is not proposed for backporting due to behavioural changes that could impact current deployment models.

The help menu will also be corrected to capture missing options and delete old, obsolete options. The missing respmgr option is added. The obsolete keygen and pluggability options are removed. The obsolete data option is also removed from the verbose options section of the help output.

Specification

For the JDK feature release fix, the below options are now adhered to more strictly. The "ssl : turn on ssl debugging" option is now implemented correctly also.

E.g. for plaintext expand option, -Djavax.net.debug=plaintext would have displayed such data in the past, now that option needs to be: -Djavax.net.debug=ssl:record:plaintext

help           print this help message and exit

all            turn on all debugging
ssl            turn on ssl debugging

The following can be used with ssl:
        defaultctx   print default SSL initialization
        handshake    print each handshake message
        keymanager   print key manager tracing
        record       enable per-record tracing
        respmgr      print OCSP response tracing
        session      print session activity
        sslctx       print SSLContext tracing
        trustmanager print trust manager tracing

        handshake debugging can be widened with:
        verbose      verbose handshake message printing

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