Skip to content

Commit 394961c

Browse files
koushikthirupatturseanjmullan
koushikthirupattur
authored and
seanjmullan
committed
8328914: Document the java.security.debug property in javadoc
Reviewed-by: mullan
1 parent cf0db96 commit 394961c

File tree

2 files changed

+200
-1
lines changed

2 files changed

+200
-1
lines changed

‎src/java.base/share/classes/java/security/doc-files/debug-system-property.html‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
<!doctype html>
2+
<!--
3+
Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
4+
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5+
6+
This code is free software; you can redistribute it and/or modify it
7+
under the terms of the GNU General Public License version 2 only, as
8+
published by the Free Software Foundation. Oracle designates this
9+
particular file as subject to the "Classpath" exception as provided
10+
by Oracle in the LICENSE file that accompanied this code.
11+
12+
This code is distributed in the hope that it will be useful, but WITHOUT
13+
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14+
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15+
version 2 for more details (a copy is included in the LICENSE file that
16+
accompanied this code).
17+
18+
You should have received a copy of the GNU General Public License version
19+
2 along with this work; if not, write to the Free Software Foundation,
20+
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21+
22+
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
23+
or visit www.oracle.com if you need additional information or have any
24+
questions.
25+
-->
26+
<html lang="en">
27+
<head>
28+
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
29+
<title>The java.security.debug system property</title>
30+
<style>
31+
#debug {
32+
border: 1px solid black;
33+
border-collapse: collapse;
34+
margin: 0 auto;
35+
}
36+
#debug caption {
37+
font-weight: bold;
38+
font-size: smaller;
39+
}
40+
#debug, #debug th, #debug td {
41+
border: 1px solid black;
42+
padding: 2px .5em;
43+
}
44+
#debug tbody th {
45+
font-weight: normal;
46+
text-align:left;
47+
}
48+
</style>
49+
</head>
50+
<body LANG="en-US" DIR="LTR">
51+
<h1><B>{@systemProperty java.security.debug}</B></h1>
52+
<p> To monitor security access, you can set the <code>java.security.debug</code>
53+
system property, which determines what trace messages are printed during
54+
execution. The value of the property is one or more options separated by a
55+
comma.
56+
</p>
57+
58+
<h2>Printing Thread and Timestamp Information</h2>
59+
<p>
60+
You can append the following strings to any option specified in the
61+
<code>java.security.debug</code> system property to print additional
62+
information:
63+
<ul>
64+
<li><code>+thread</code>: Print thread and caller information</li>
65+
<li><code>+timestamp</code>: Print timestamp information</li>
66+
</ul>
67+
<p>
68+
For example, to add thread, caller, and timestamp information to all
69+
debugging output, set the <code>java.security.debug</code> system property
70+
on the command line as follows:
71+
<pre><code>java -Djava.security.debug=all+thread+timestamp MyApp</code></pre>
72+
73+
<p>The following table lists the <code>java.security.debug</code> options:</p>
74+
75+
<table id="debug">
76+
<caption><b>Security Debug Options</b></caption>
77+
<thead>
78+
<tr>
79+
<th scope="col">Option</th>
80+
<th scope="col">Description</th>
81+
</tr>
82+
</thead>
83+
<tbody>
84+
<tr>
85+
<th scope="row"><code>all</code></th>
86+
<td>Turn on all the debugging options</td>
87+
</tr>
88+
<tr>
89+
<th scope="row"><code>certpath</code></th>
90+
<td>Turns on debugging for the PKIX <code>CertPathValidator</code> and
91+
<code>CertPathBuilder</code> implementations. The following sub-options
92+
can be used with the <code>certpath</code> option:
93+
<ul>
94+
<li><code><b>ocsp</b></code>: Dump OCSP protocol exchanges</li>
95+
<li><code><b>verbose</b></code>: A hexadecimal dump of the OCSP
96+
request and response bytes is displayed.</li>
97+
</ul>
98+
</td>
99+
</tr>
100+
<tr>
101+
<th scope="row"><code>configfile</code></th>
102+
<td>JAAS (Java Authentication and Authorization Service) configuration file loading</td>
103+
</tr>
104+
<tr>
105+
<th scope="row"><code>configparser</code></th>
106+
<td>JAAS configuration file parsing</td>
107+
</tr>
108+
<tr>
109+
<th scope="row"><code>gssloginconfig</code></th>
110+
<td>Java GSS (Generic Security Services) login configuration file debugging</td>
111+
</tr>
112+
<tr>
113+
<th scope="row"><code>jar</code></th>
114+
<td>JAR file verification</td>
115+
</tr>
116+
<tr>
117+
<th scope="row"><code>jca</code></th>
118+
<td>JCA engine class debugging</td>
119+
</tr>
120+
<tr>
121+
<th scope="row"><code>KeyStore</code></th>
122+
<td><code>KeyStore</code> debugging</td>
123+
</tr>
124+
<tr>
125+
<th scope="row"><code>logincontext</code></th>
126+
<td><code>LoginContext</code> results</td>
127+
</tr>
128+
<tr>
129+
<th scope="row"><code>pcsc</code></th>
130+
<td>Java Smart Card I/O and SunPCSC provider debugging</td>
131+
</tr>
132+
<tr>
133+
<th scope="row"><code>pkcs11</code></th>
134+
<td>PKCS11 session manager debugging</td>
135+
</tr>
136+
<tr>
137+
<th scope="row"><code>pkcs11keystore</code></th>
138+
<td>PKCS11 <code>KeyStore</code> debugging</td>
139+
</tr>
140+
<tr>
141+
<th scope="row"><code>pkcs12</code></th>
142+
<td>PKCS12 <code>KeyStore</code> debugging</td>
143+
</tr>
144+
<tr>
145+
<th scope="row"><code>properties</code></th>
146+
<td><code>java.security</code> configuration file debugging</td>
147+
</tr>
148+
<tr>
149+
<th scope="row"><code>provider</code></th>
150+
<td>Security provider debugging. The following sub-option can be used
151+
with the <code>provider</code> option: <code>engine=(engines)</code>
152+
: The output is displayed only for a specified list of one or more JCA
153+
engines, separated by a comma. The supported values for (engines) are:
154+
<ul>
155+
<li><code>Cipher</code></li>
156+
<li><code>KDF</code></li>
157+
<li><code>KeyAgreement</code></li>
158+
<li><code>KeyGenerator</code></li>
159+
<li><code>KeyPairGenerator</code></li>
160+
<li><code>KeyStore</code></li>
161+
<li><code>Mac</code></li>
162+
<li><code>MessageDigest</code></li>
163+
<li><code>SecureRandom</code></li>
164+
<li><code>Signature</code></li>
165+
</ul>
166+
</td>
167+
</tr>
168+
<tr>
169+
<th scope="row"><code>securerandom</code></th>
170+
<td><code>SecureRandom</code> debugging</td>
171+
</tr>
172+
<tr>
173+
<th scope="row"><code>sunpkcs11</code></th>
174+
<td>SunPKCS11 provider debugging</td>
175+
</tr>
176+
<tr>
177+
<th scope="row"><code>ts</code></th>
178+
<td>Timestamping debugging</td>
179+
</tr>
180+
<tr>
181+
<th scope="row"><code>x509</code></th>
182+
<td>X.509 certificate debugging. The following sub-option can be used
183+
with the <code>X.509</code> option.
184+
<ul>
185+
<li><code><b>ava</b></code>: Embed non-printable/non-escaped
186+
characters in AVA components as hex strings</li>
187+
</ul>
188+
</td>
189+
</tr>
190+
</tbody>
191+
</table>
192+
</body>
193+
</html>

‎src/java.base/share/classes/java/security/package-info.java‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 1998, 2024, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 1998, 2025, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -71,6 +71,12 @@
7171
*
7272
* </ul>
7373
*
74+
* <h2>Additional Specification</h2>
75+
* <ul>
76+
* <li><a href="doc-files/debug-system-property.html">
77+
* The {@code java.security.debug} System Property</a></li>
78+
* </ul>
79+
*
7480
* @spec security/standard-names.html Java Security Standard Algorithm Names
7581
* @since 1.1
7682
*/

0 commit comments

Comments
 (0)