RFR: 8328914: Document the java.security.debug property in javadoc [v9]
Weijun Wang
weijun at openjdk.org
Tue Feb 25 15:54:09 UTC 2025
On Tue, 25 Feb 2025 00:29:35 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.
>>
>> 
>>
>>
>> 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 29:
> 27: <head>
> 28: <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
> 29: <title>Security-Related System Property</title>
Not what I expected. Either you keep the old name and add a few new system properties, or, just change the whole title to something like "Troubleshooting" or "Printing Debug Information".
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 58:
> 56: and therefore are best set using the <code>-D</code> option of the java command,
> 57: while others have a more dynamic nature and can also be changed using
> 58: the <a href="../../lang/System.html#setProperty(java.lang.String,java.lang.String)">System.setProperty()</a> API.
The `System.setProperty()` call should be in `<code>`.
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 63:
> 61: <H2>Debug</H2>
> 62: <p><B>{@systemProperty java.security.debug}</B><BR></p>
> 63: <H2>Printing Thread and Timestamp Information</H2>
This is still a big `<H2>`, which is at the same level as `<H2>Debug</H2>`.
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 68:
> 66: system property to print additional information:
> 67: <ul>
> 68: <li><code>+thread:</code>Print thread and caller information</li>
Put `:` outside `<code>`.
Hi @coffeys and @seanjmullan, now that we have a formal format for options and sub-options, shall we have one for these modifiers? Should it always be appended after the sub-option(s)? Like
x509:ava+thread,certpath:ocsp,verbose+timestamp+thread
Also, how do we specify multiple engines in `provider`? Should it look like this?
provider:engine=Cipher,Mac
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 74:
> 72: For example, to add thread, caller, and timestamp information to all debuging output,
> 73: set the <code>java.security.debug</code> system property on the command line as follows:<br>
> 74: <code>java -Djava.security.debug=all+thread+timestamp MyApp</code>
For the code in its own paragraph, should it be something like `<pre>`?
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 79:
> 77: which determines what trace messages are printed during execution. The value of the property is one or more options separated by a comma.
> 78: 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.
> 79: 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>.
Do we need `"` inside `<code>`?
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 94:
> 92: <tr>
> 93: <th scope="row"><code>all</code></th>
> 94: <td><code>Turn on all the debugging options</code></td>
Remove `<code>` from the line above.
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 102:
> 100: <ul>
> 101: <li><code><b>ocsp:</b></code> Dump OCSP protocol exchanges</li>
> 102: <li><code><b>verbose:</b></code> Print additional debugging information</li>
Move `:` out of `<code>`.
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 128:
> 126: <tr>
> 127: <th scope="row"><code>KeyStore</code></th>
> 128: <td><code>Keystore</code> debugging</td>
it's `KeyStore`.
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 157:
> 155: <th scope="row"><code>provider</code></th>
> 156: <td>Security provider debugging. The following engines can be used with the <code>`provider`</code> sub-option:
> 157: <code>`engine=(engines)`</code> : The output is displayed only for a specified list of JCA engines.
Remove extra "`".
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 190:
> 188: <tr>
> 189: <th scope="row"><code>x509</code></th>
> 190: <td><code>X.509</code> certificate debugging. You can use the following sub-option with <code>X.509</code>
No need for "X.509" in `<code>`.
src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 192:
> 190: <td><code>X.509</code> certificate debugging. You can use the following sub-option with <code>X.509</code>
> 191: <ul>
> 192: <li><code><b>ava:</b></code> Embed non-printable/non-escaped characters in AVA components as hex strings</li>
Move `:` out of `<code>`.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970006546
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970034740
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970008007
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970023633
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970055051
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970051804
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970053286
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970059952
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970056086
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970057231
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970058092
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970059105
More information about the security-dev
mailing list