On Sat, 1 Mar 2025 00:00:21 GMT, Koushik Muthukrishnan Thirupattur <d...@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. >> >>  >> >> >> 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
