The Security Properties File

A security properties file is a text file that contains names of security properties and their values. You can customize certain aspects of Java security by setting these properties.

When you launch a Java application from a JDK located in $JAVA_HOME, by default, the JVM will set the set the security properties to the values specified in $JAVA_HOME/conf/security/java.security, which is known as the master security properties file. It's possible to specify another security properties file; see Specifying an Alternative Security Properties File.

A security property set in a security properties file is statically set. You can dynamically set security properties by setting their values in your application's code. See Statically Setting a Security Property in a Security Properties File and Dynamically Setting a Security Property in Application Code.

See Troubleshooting Security Properties for information about enabling logging for security properties and viewing them.

By default, the master security properties file sets security properties that customize certain aspects of Java, which include the following:

  • Registering a security provider: A security provider is a package or set of packages that supply a concrete implementation of a subset of the cryptography aspects of the Java Security API. The master security properties file sets several security properties in the form security.provider.n, where n is the provider's preference order. The preference order is the order in which providers are searched for requested algorithms (when no specific provider is requested).

    See Step 8.1: Configure the Provider for more information.

  • Algorithm restrictions: This covers restricted and legacy algorithms for certificate path validation, TLS, signed JAR files, and XML signature validations. For example, jdk.certpath.disabledAlgorithms and jdk.tls.disabledAlgorithm list which algorithms to disable during certification path validation and TLS/DTLS protocol negotiation.

  • Java Secure Socket Extension (JSSE): JSSE enables secure Internet communications. It provides a framework and an implementation for a Java version of the TLS and DTLS protocols and includes functionality for data encryption, server authentication, message integrity, and optional client authentication. Related security properties include:

    • jdk.tls.keyLimits, which limits the amount of data algorithms may encrypt with a set of keys
    • ssl.KeyManagerFactory and ssl.TrustManagerFactory, which specify the default key and trust manager factory algorithms for the javax.net.ssl package

    See Customizing JSSE for more information.

  • Other aspects of Java security: This includes default keystore type, configuration of SecureRandom implementations, and Kerberos.

Specifying an Alternative Security Properties File

You can specify an alternate java.security properties file from the command line with the system property java.security.properties=<URL>. This properties file is appended to the master security properties file. If you specify a properties file with java.security.properties==<URL> (using two equals signs), then that properties file will completely override the master security properties file.

Statically Setting a Security Property in a Security Properties File

To statically set a security property value in a security properties file, add or modify an existing line in the following form:

propertyName=propertyValue

For example, suppose that you want to specify a different key manager factory algorithm name than the default SunX509. You do this by specifying the algorithm name as the value of a security property named ssl.KeyManagerFactory.algorithm. For example, to set the value to MyX509, add the following line: 

ssl.KeyManagerFactory.algorithm=MyX509

To comment out a line in a security properties file, which means the JVM ignores it when it sets security properties from a security properties file, insert the number sign (#) at the beginning of the line.

By default, the master security properties file contains many comments that describe in detail the security properties specified in it. Sometimes, these security properties themselves are commented out. These security properties that are commented out might have a value specified or no value at all.

Note:

A security property that has been set to no value is set to the empty string. A security property that has been commented out is set to a null value. In this case, the security property might be assigned a default value. The comments in the master security properties file should specify whether a security property has a default value.

Dynamically Setting a Security Property in Application Code

To set a security property dynamically in application code, call the java.security.Security.setProperty method: 

Security.setProperty("propertyName," "propertyValue");

For example, a call to the setProperty() method corresponding to the previous example for specifying the key manager factory algorithm name would be: 

Security.setProperty("ssl.KeyManagerFactory.algorithm", "MyX509");

Note:

Some security properties cannot be set dynamically if they have already been read from a security properties file and cached, which happens when the java.security.Security class is initialized. No exception will be thrown if your code attempts to do this.

Troubleshooting Security Properties

Enable logging for security properties by specifying the command-line option -Djava.security.debug=properties. Messages prefixed by properties contain the final values for all security properties and information on how include directives have been processed. See The java.security.debug System Property.

The command-line option -XshowSettings:security prints an overview of the security settings that are effective in the JDK. See The java -XshowSettings:security Option.

You can use the Java Flight Recorder (JFR) event jdk.InitialSecurityProperty to obtain the initial values for security properties on a running JDK.