RFR: 8328914: Document the java.security.debug property in javadoc [v11]

Sean Mullan mullan at openjdk.org
Wed Mar 5 21:33:03 UTC 2025 

On Sat, 1 Mar 2025 00:00:21 GMT, Koushik Muthukrishnan Thirupattur <duke at openjdk.org> wrote:

>> 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.
>> 
>> ![image](https://github.com/user-attachments/assets/0c9a79f3-4cb2-414c-af1d-eac2590740ea)
>> 
>> 
>> NOTE : We are adding a new html file (similar to the Networking Properties [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/net/doc-files/net-properties.html#networking-properties-heading)) for documenting security-related properties, and over time, we will add more properties to this page.
>
> Koushik Muthukrishnan Thirupattur has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8328914: Document the java.security.debug property in javadoc

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 1:

> 1: <!doctype html>

General comment - try to keep the length of lines to about 80 characters.

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 58:

> 56:     which determines what trace messages are printed during execution. The value of the property is one or more options separated by a comma.
> 57:     Some options also have additional sub-options. Sub-options are specified by appending a ":" to the option, followed by a list of one more sub-options separated by a comma.
> 58:     For example, to specify the <code>ocsp</code> and <code>verbose</code> options with the <code>certpath</code> option: set the property to "<code>certpath:ocsp,verbose</code>".

I think a ',' instead of a ':' after 'option' would read better.

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 63:

> 61: <H3>Printing Thread and Timestamp Information</H3>
> 62: <p>
> 63:     You can append the following strings to the value specified in the <code>java.security.debug</code>

s/the value/any option/

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 66:

> 64:     system property to print additional information:
> 65: <ul>
> 66:     <li><code>+thread</code>:Print thread and caller information</li>

Add space after ':'.

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 67:

> 65: <ul>
> 66:     <li><code>+thread</code>:Print thread and caller information</li>
> 67:     <li><code>+timestamp</code>:Print timestamp information</li>

Add space after ':'.

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 70:

> 68: </ul>
> 69: <p>
> 70:     For example, to add thread, caller, and timestamp information to all debuging output,

s/debuging/debugging/

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 74:

> 72:     <pre><code>java -Djava.security.debug=all+thread+timestamp MyApp</code></pre>
> 73: 
> 74: <p>The following table lists <code>java.security.debug</code> options table:</p>

s/lists/lists the/

Remove "table" at the end, you already have that word at the beginning.

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 91:

> 89:     <tr>
> 90:         <th scope="row"><code>certpath</code></th>
> 91:         <td>Turns on debugging for the PKIX <code>CertPathValidator</code> and <code>CertPathBuilder</code> implementations. Use the <code>ocsp</code> sub-option with the <code>certpath</code> option for OCSP protocol tracing. A hexadecimal dump of the OCSP request and response bytes is displayed.

Remove the last 2 sentences ("Use the ..." and "A hexadecimal ..."). Add similar text to the sub-option section where it makes more sense. Reword the section as "Dump OCSP protocol exchanges. A hexadecimal dump of the OCSP request and response bytes is displayed."

(I think that is all that as needed - the other text was redundant.)

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 92:

> 90:         <th scope="row"><code>certpath</code></th>
> 91:         <td>Turns on debugging for the PKIX <code>CertPathValidator</code> and <code>CertPathBuilder</code> implementations. Use the <code>ocsp</code> sub-option with the <code>certpath</code> option for OCSP protocol tracing. A hexadecimal dump of the OCSP request and response bytes is displayed.
> 92:             You can use the following sub-options with the <code>certpath</code> option:

Change this to: "The following sub-options can be used with the <code>certpath</code> option:"

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 149:

> 147:     <tr>
> 148:         <th scope="row"><code>provider</code></th>
> 149:         <td>Security provider debugging. The following engines can be used with the <code>provider</code> sub-option:

Change second sentence to: "The following sub-option can be used with the <code>provider</code> option:

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 150:

> 148:         <th scope="row"><code>provider</code></th>
> 149:         <td>Security provider debugging. The following engines can be used with the <code>provider</code> sub-option:
> 150:             <code>engine=(engines)</code> : The output is displayed only for a specified list of JCA engines.

s/JCA engines/one or more JCA engines, separated by a comma/

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 151:

> 149:         <td>Security provider debugging. The following engines can be used with the <code>provider</code> sub-option:
> 150:             <code>engine=(engines)</code> : The output is displayed only for a specified list of JCA engines.
> 151:             The supported values for (engines) are:

Add "KDF" to this list.

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 183:

> 181:     <tr>
> 182:         <th scope="row"><code>x509</code></th>
> 183:         <td>X.509 certificate debugging. You can use the following sub-option with <code>X.509</code>

Change the second sentence to "The following sub-option can be used with the <code>X.509</code> option:"

src/java.base/share/classes/java/security/package-info.java line 77:

> 75:  * <ul>
> 76:  *   <li><a href="doc-files/security-related-system-properties.html">
> 77:  *     Security-Related System Properties</a></li>

For now change this to "The {@code java.security.debug} System Property".

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982192240
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982181081
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982187987
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982188630
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982188810
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982189198
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982190366
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982195794
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982201726
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982201136
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982207469
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982203574
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982209097
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1982210022

More information about the security-dev mailing list