Troubleshooting Security

To monitor security access, you can set the java.security.debug system property, which determines what trace messages are printed during execution. To view security properties, security providers, and TLS-related settings, specify the -XshowSettings:security option in the java command. You can enable debugging in JGSS and other related technologies with various system properties or environment variables.

Topics

• The java.security.debug System Property
• Debug Statement Output Format
• The java -XshowSettings:security Option
• Enabling Debugging in Java Generic Security Services

The java.security.debug System Property

To see a list of all debugging options, use the help option as follows. MyApp is any Java application. The java command prints the debugging options and then exits before running MyApp.

java -Djava.security.debug=help MyApp

Note:

• To use more than one option, separate options with a comma.
• JSSE also provides dynamic debug tracing support for SSL/TLS/DTLS troubleshooting. See Debugging Utilities.

The following table lists java.security.debug options and links to further information about each option. See java.security.debug in the JavaDoc API documentation for additional information.

Table 1-5 java.security.debug Options

Option	Description	Further Information
all	Turn on all the debugging options	None
certpath	Turns on debugging for the PKIX CertPathValidator and CertPathBuilder implementations. Use the ocsp option with the certpath option for OCSP protocol tracing. A hexadecimal dump of the OCSP request and response bytes is displayed. You can use the following options with this option: ocsp: Dump OCSP protocol exchanges verbose: A hexadecimal dump of the OCSP request and response bytes is displayed	PKI Programmer's Guide Overview
configfile	JAAS (Java Authentication and Authorization Service) configuration file loading	Java Authentication and Authorization Service (JAAS) Reference Guide Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges
configparser	JAAS configuration file parsing	Java Authentication and Authorization Service (JAAS) Reference Guide Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges
gssloginconfig	Java GSS (Generic Security Services) login configuration file debugging	Java Generic Security Services: (Java GSS) and Kerberos JAAS and Java GSS-API Tutorial javax.security.auth.login.Configuration: A Configuration object is responsible for specifying which javax.net.ssl.SSLEngine should be used for a particular application, and in what order the LoginModules should be invoked. Appendix B: JAAS Login Configuration File Advanced Security Programming in Java SE Authentication, Secure Communication and Single Sign-On
jar	JAR file verification	Verifying Signed JAR Files from The Java Tutorials Note: Use the System property jdk.jar.maxSignatureFileSize to specify the maximum size, in bytes, of signature files in a signed JAR. Its default value is 16000000 (16 MB).
jca	JCA engine class debugging	Engine Classes and Algorithms
KeyStore	Keystore debugging	Keystores KeyStore
logincontext	LoginContext results	Java Authentication and Authorization Service (JAAS) Reference Guide Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges
pcsc	Java Smart Card I/O and SunPCSC provider debugging	The SunPCSC Provider and the javax.smartcardio package
pkcs11	PKCS11 session manager debugging	PKCS#11 Reference Guide
pkcs11keystore	PKCS11 KeyStore debugging	PKCS#11 Reference Guide
pkcs12	PKCS12 KeyStore debugging	None
properties	java.security configuration file debugging	None
provider	Security provider debugging You can use the engine=<engines> option with this option. It displays output only for the JCA engines specified by <engines>. This value is a comma-separated list. It can contain one or more of the following values: Cipher KDF KeyAgreement KeyGenerator KeyPairGenerator KeyStore Mac MessageDigest SecureRandom Signature	Java Cryptography Architecture (JCA) Reference Guide
securerandom	SecureRandom debugging	The SecureRandom Class
sunpkcs11	SunPKCS11 provider debugging	PKCS#11 Reference Guide
ts	Timestamping debugging	None
x509	X.509 certificate debugging You can use the ava option with this option. It embeds non-printable/non-escaped characters in AVA components as hex strings	X.509 Certificates and Certificate Revocation Lists (CRLs)

Debug Statement Output Format

Each debug output statement generated through the java.security.debug option is formatted as follows:

componentValue[threadId|threadName|sourceCodeLocation|timestamp]: <debug statement>

• componentValue is the security component value being logged.
• threadId is the hexadecimal value of the thread ID.
• threadName is the name of the thread running the log statement.
• sourceCodeLocation is the source file and line number making this log call in the format filename:lineNumber.
• timestamp is the date and time in the format yyyy-MM-dd kk:mm:ss.SSS.
• <debug statement> corresponds to the debug output from the security component.

The java -XshowSettings:security Option

You can specify the option -XshowSettings:security option in the java command to view security properties, security providers, and TLS-related settings. The option shows third-party security provider details if they are included in the application class path or module path and such providers are configured in the java.security file.

In addition, you can specify -XshowSettings:security:<subcategory> where <subcategory> is one of the following:

• all: show all security settings
• properties: show security properties
• providers: show static security provider settings
• tls: show TLS-related security settings

Enabling Debugging in Java Generic Security Services

Set the following system properties or environment variables to true to enable debugging in the Java Generic Security Services (JGSS) framework, Kerberos, SPNEGO, the native JGSS bridge, and the SSPI bridge on Windows:

Caution:

Debugging information may contain sensitive information.

Table 1-6 JGSS Debugging System Properties

System Property or Environment Variable	JGSS Feature to Debug
sun.security.jgss.debug system property	JGSS framework
sun.security.krb5.debug system property	Java Kerberos 5 mechanism
sun.security.spnego.debug system property	Java SPNEGO mechanism
sun.security.nativegss.debug system property	Native JGSS bridge
SSPI_BRIDGE_TRACE environment variable	SSPI bridge on Windows

For example, to enable debugging in the JGSS framework, set the sun.security.jgss.debug system property to true on the command line as follows:

java -Dsun.security.jgss.debug=true MyApp

In your JAAS login configuration file, you can specify debug=true in the Krb5LoginModule to enable debugging in the associated entry. For example, the following enables debugging for JassSample:

JaasSample {
    com.sun.security.auth.module.Krb5LoginModule required;
    debug=true;
};