8328914: Document the java.security.debug property in javadoc

[koushikthirupattur]

java.security.debug is a widely used debug system property for JDK security libs. It's time to capture details about this property via javadoc.

NOTE : We are adding a new html file (similar to the Networking Properties here) for documenting security-related properties, and over time, we will add more properties to this page.

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change requires CSR request JDK-8350128 to be approved

Issues

• JDK-8328914: Document the java.security.debug property in javadoc (Task - P4)
• JDK-8350128: Document the java.security.debug property in javadoc (CSR)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/23569/head:pull/23569
$ git checkout pull/23569

Update a local copy of the PR:
$ git checkout pull/23569
$ git pull https://git.openjdk.org/jdk.git pull/23569/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 23569

View PR using the GUI difftool:
$ git pr show -t 23569

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/23569.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back koushikthirupattur! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

[openjdk]

@koushikthirupattur The following label will be automatically applied to this pull request:

• security

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

[mlbridge]

Webrevs

• 05: Full - Incremental (46954537)
• 04: Full - Incremental (dbedca43)
• 03: Full - Incremental (e950afb8)
• 02: Full - Incremental (7f1f76c1)
• 01: Full - Incremental (1067f1a1)
• 00: Full (57901731)

[seanjmullan]

@koushikthirupattur I think this will require a CSR. Even though it is a property that we have supported for a long time, I am pretty sure it is the first time we have documented it in the javadocs. Contact me if you need help writing the CSR.

[seanjmullan]

/csr

[openjdk]

@seanjmullan has indicated that a compatibility and specification (CSR) request is needed for this pull request.

@koushikthirupattur please create a CSR request for issue JDK-8328914 with the correct fix version. This pull request cannot be integrated until the CSR request is approved.

[wangweij]

Like what java/net did, we need a link from java/security/package-info.java to this new file.

[wangweij]

Please also mention the +thread and +timestamp modifiers. Also, at the beginning, there is no default value for this system property. It is not false.

[wangweij]

The ava sub-option for x509 is not included. BTW, I see the rows are in alphabetical order now, this is great. Can we also reorder the help output at

jdk/src/java.base/share/classes/sun/security/util/Debug.java

Line 85 in 940aa7c

public static void Help() {

?

[koushikthirupattur]

Like what java/net did, we need a link from java/security/package-info.java to this new file.

Added.

[koushikthirupattur]

Please also mention the +thread and +timestamp modifiers. Also, at the beginning, there is no default value for this system property. It is not false.

Added.

[wangweij]

The name and title should not be "Security Properties". This is about the debug system property.

[wangweij]

Also, now we have the same content in 3 places:

1. Here
2. In the Security Guide at https://docs.oracle.com/en/java/javase/23/security/troubleshooting-security.html#GUID-05F3E865-20FF-46EB-AC35-84D4B552CA48
3. At

   jdk/src/java.base/share/classes/sun/security/util/Debug.java

   Line 85 in 940aa7c

   public static void Help() {

   .
   Do we need to keep all of them? @seanjmullan

[seanjmullan]

Also, now we have the same content in 3 places:

1. Here

2. In the Security Guide at https://docs.oracle.com/en/java/javase/23/security/troubleshooting-security.html#GUID-05F3E865-20FF-46EB-AC35-84D4B552CA48

3. At https://github.com/openjdk/jdk/blob/940aa7c4cf1bf770690660c8bb21fb3ddc5186e4/src/java.base/share/classes/sun/security/util/Debug.java#L85
   .
   Do we need to keep all of them? @seanjmullan

Well, I still find #3 valuable as it is useful as a command-line help option.

For #2, we don't need the duplication, but I think it is useful to still have a pointer from the guides to this new html file, so @koushikthirupattur please file a subtask (in the docs/guides category) to have the section in the security guide link to this new properties file in the javadoc.

[seanjmullan]

The name and title should not be "Security Properties". This is about the debug system property.

Yes, this is because "Security Properties" are different than system properties, and are listed in the java.security file. We may want to someday also add them to this file, but not now. So, I would change it to "Security System Properties" or maybe "Security-Related System Properties"

[koushikthirupattur]

Also, now we have the same content in 3 places:

1. Here

2. In the Security Guide at https://docs.oracle.com/en/java/javase/23/security/troubleshooting-security.html#GUID-05F3E865-20FF-46EB-AC35-84D4B552CA48

3. At https://github.com/openjdk/jdk/blob/940aa7c4cf1bf770690660c8bb21fb3ddc5186e4/src/java.base/share/classes/sun/security/util/Debug.java#L85
   .
   Do we need to keep all of them? @seanjmullan

Well, I still find #3 valuable as it is useful as a command-line help option.

For #2, we don't need the duplication, but I think it is useful to still have a pointer from the guides to this new html file, so @koushikthirupattur please file a subtask (in the docs/guides category) to have the section in the security guide link to this new properties file in the javadoc.

Created here 8350384

[koushikthirupattur]

The name and title should not be "Security Properties". This is about the debug system property.

Yes, this is because "Security Properties" are different than system properties, and are listed in the java.security file. We may want to someday also add them to this file, but not now. So, I would change it to "Security System Properties" or maybe "Security-Related System Properties"

Changed.

[wangweij]

The +thread and +timestamp are modifiers that can be added to any value. I'd like them to be described outside the table.

[wangweij]

Do you want to show some examples on how the options are specified? Especially when there are multiple options.

[Michael-Mc-Mahon]

As a regular user of the property, this change is a great idea. I think the text accompanying the table should describe the syntax of the property value. Is it a comma separated list etc?

[seanjmullan]

As a regular user of the property, this change is a great idea. I think the text accompanying the table should describe the syntax of the property value. Is it a comma separated list etc?

The syntax has always been a bit loosely specified. So I suggest we don't say anything too specific, but just something like: "The value of the property is one or more options separated by a comma. Some options also have additional sub-options; see the list below for more details on the syntax of each."