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.

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:

Table 1-8 java.security.debug Options

Option Description Further Information
all Turn on all the debugging options  None
access

Print all results from the AccessController.checkPermission method.

You can use the following options with the access option:

  • stack: Include stack trace
  • domain: Dump all domains in context
  • failure: Before throwing exception, dump stack and domain that do not have permission

You can use the following options with the stack and domain options:

  • permission=<classname>: Only dump output if specified permission is being checked
  • codebase=<URL>: Only dump output if specified codebase is being checked
Permissions in the JDK
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 the certpath option:

  • ocsp: Dump OCSP protocol exchanges
  • verbose: Print additional debugging information
PKI Programmer's Guide Overview
combiner SubjectDomainCombiner debugging Permissions in the JDK
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
policy Loading and granting permissions with policy file

Set up the Policy File to Grant the Required Permissions (Controlling Applications) from The Java Tutorials

Default Policy Implementation and Policy File Syntax

properties java.security configuration file debugging None
provider Security provider debugging

The following options can be used with the provider option:

engine=<engines> : The output is displayed only for a specified list of JCA engines.

The supported values for <engines> are:
  • Cipher
  • KeyAgreement
  • KeyGenerator
  • KeyPairGenerator
  • KeyStore
  • Mac
  • MessageDigest
  • SecureRandom
  • Signature
Java Cryptography Architecture (JCA) Reference Guide
scl Permissions that SecureClassLoader assigns Permissions in the JDK
securerandom SecureRandom debugging The SecureRandom Class
sunpkcs11 SunPKCS11 provider debugging PKCS#11 Reference Guide
ts Timestamping debugging None
x509 X.509 certificate debugging X.509 Certificates and Certificate Revocation Lists (CRLs)

Printing Thread and Timestamp Information

You can append the following strings to the value specified in the java.security.debug system property to print additional information:

  • +thread: Print thread and caller information
  • +timestamp: Print timestamp information

For example, to add thread, caller, and timestamp information to all debuging output, set the java.security.debug system property on the command line as follows:

java -Djava.security.debug=all+thread+timestamp MyApp

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-9 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

You can append +thread and +timestamp to the value true to print additional information.

Note:

You cannot add these strings to the value of the SSPI_BRIDGE_TRACE environment variable.

For example, to add thread, caller, and timestamp information to JGSS framework debugging output, you can set the sun.security.jgss.debug system property on the command line as follows:

java -Dsun.security.jgss.debug=true+thread+timestamp 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 and adds thread, caller, and timestamp information to the debugging output:

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