Summary

Introduce new decorator options for the java.security.debug system property

Problem

To gather debug information from the JDK security libraries, one can launch the JDK with the java.security.debug system property. The options passed to the property can be viewed via launching JDK with the -Djava.security.debug=help option. None of the output contains information relating to time of event, thread information performing operation or the caller site origin. Such metadata information can be valuable when debugging issues in JDK security libraries which might relate to thread races or events happening at particular times or intervals.

In comparison, the TLS logging option, javax.net.debug, contains thread caller information and timestamp information by default.

Solution

Improve the java.security.debug output so that options exist to add thread ID, thread name, source of log record and timestamp information.

Two new strings can be appended to each security component option to decorate the output as desired:

• +thread : decorate output with details relating to thread id (in hex notation), thread name and information relating to calling site in source code
• +timestamp : decorate output with date and time for each line logged

Examples:

format without patch :

properties: Initial security property: package.definition=sun.misc.,sun.reflect.
properties: Initial security property: krb5.kdc.bad.policy=tryLast 
keystore: Creating a new keystore in PKCS12 format

format with +thread decorator option

properties[0x10|main|Security.java:122]: Initial security property: package.definition=sun.misc.,sun.reflect.
properties[0x10|main|Security.java:122]: Initial security property: krb5.kdc.bad.policy=tryLast 
keystore[0x10|main|KeyStoreDelegator.java:216]: Creating a new keystore in PKCS12 format

format with +thread+timestamp decorator option:

properties[0x10|main|Security.java:122|2024-03-01 14:59:42.859 UTC]: Initial security property: package.definition=sun.misc.,sun.reflect.
properties[0x10|main|Security.java:122|2024-03-01 14:59:42.859 UTC]: Initial security property: krb5.kdc.bad.policy=tryLast

It's a similar format to what can be seen when the TLS javax.net.debug debug logging option is used.

Current proposal is to keep the thread and timestamp decorating off by default.

The extra decorator info is controlled by appending option to each component specified in the "java.security.debug" option list.

e.g

-Djava.security.debug=properties+timestamp+thread turns on logging for the properties component and also decorates the records with timestamp and thread info

-Djava.security.debug=properties+thread+timestamp,keystore would decorate the properties component but no decorating performed for the keystore component.

JDK security documentation will be updated to capture these new decorator options. A release note would also be generated.

It's planned that this supportability enhancement could also be backported to JDK LTS update releases.

Specification

Update the java.security.debug help output with following new section:

+timestamp can be appended to any of above options to print
              a timestamp for that debug option
+thread can be appended to any of above options to print
              thread information for that debug option

The all option is treated differently. If the all option gets appended with the timestamp decorator option, -Djava.security.debug=all+timestamp, then all output will have timestamp information.

If the all option gets appended with the thread decorator option, -Djava.security.debug=all+thread, then all output will have thread information.

Similarly, if -Djava.security.debug=all+thread+timestamp is used, then both the timestamp and thread decorator information is appended to each line no matter what other options might have been appended to other security options.