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 (Enhancement - P4)
• JDK-8350128: Document the java.security.debug property in javadoc (CSR)

Reviewers

• Sean Mullan (@seanjmullan - Reviewer)

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]

@koushikthirupattur This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

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

Reviewed-by: mullan

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 345 new commits pushed to the master branch:

• 6b553ac: 8277424: javax/net/ssl/TLSCommon/TLSTest.java fails with connection refused
• 09cae5f: 8354407: Test com/sun/management/OperatingSystemMXBean/GetProcessCpuLoad.java still fails on Windows
• 2ad639f: 8356021: Use Double::hashCode in java.util.Locale::hashCode
• ... and 342 more: https://git.openjdk.org/jdk/compare/f955a8cbd2d1233af7f7e4b4e4bfcdbb5a8cacae...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@Michael-Mc-Mahon, @seanjmullan) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

[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

• 17: Full - Incremental (f53973f7)
• 16: Full - Incremental (dc7f34fa)
• 15: Full - Incremental (00efddca)
• 14: Full - Incremental (ba6caeb6)
• 13: Full - Incremental (a365c04d)
• 12: Full - Incremental (76669c40)
• 11: Full - Incremental (c8597cf1)
• 10: Full - Incremental (e40dcd7f)
• 09: Full - Incremental (aa6a8992)
• 08: Full - Incremental (11a0f818)
• 07: Full - Incremental (228d35be)
• 06: Full - Incremental (b731a126)
• 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.

[bridgekeeper]

@koushikthirupattur This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

[openjdk]

⚠️ @koushikthirupattur the full name on your profile does not match the author name in this pull requests' HEAD commit. If this pull request gets integrated then the author name from this pull requests' HEAD commit will be used for the resulting commit. If you wish to push a new commit with a different author name, then please run the following commands in a local repository of your personal fork:

$ git checkout 8328914
$ git commit --author='Preferred Full Name <you@example.com>' --allow-empty -m 'Update full name'
$ git push

[koushikthirupattur]

/integrate

[openjdk]

@koushikthirupattur
Your change (at version f53973f) is now ready to be sponsored by a Committer.

[seanjmullan]

/sponsor

[openjdk]

Going to push as commit 394961c.
Since your change was applied there have been 346 commits pushed to the master branch:

• cf0db96: 8354084: Streamline XPath API's extension function control
• 6b553ac: 8277424: javax/net/ssl/TLSCommon/TLSTest.java fails with connection refused
• 09cae5f: 8354407: Test com/sun/management/OperatingSystemMXBean/GetProcessCpuLoad.java still fails on Windows
• ... and 343 more: https://git.openjdk.org/jdk/compare/f955a8cbd2d1233af7f7e4b4e4bfcdbb5a8cacae...master

Your commit was automatically rebased without conflicts.

[openjdk]

@seanjmullan @koushikthirupattur Pushed as commit 394961c.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.