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.

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.

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");

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.

To include a security properties file in another security properties file, use an include directive. This feature enables security properties to be defined in multiple files and can facilitate the centralized management of security profiles across multiple JDKs.

For example, on Linux and macOS, to include the security properties file /usr/lib/jvm/jdk-24/conf/security/extra.security in another security properties file, add the following include directive:

include /usr/lib/jvm/jdk-24/conf/security/extra.security

On Windows, to include the security properties file C:\Java\jdk-24\conf\security\extra.security in another security properties file, add the following include directive:

include C:\\Java\\jdk-24\\conf\\security\\extra.security

A file system path in an include directive can be absolute, like the previous examples, or relative. When it's a relative path, the location of the file that contains the include directive is used as the base. You can't use a relative path if the include directive is in a URL stream. For example, if you specify the following option on the command line when launching a Java application, then the security properties file extra.java.security can't contain any include directives that specify a relative path:

-Djava.security.properties=https://example.com/extra.java.security

On Linux and macOS, forward slashes (/) are supported.

On Windows, double backward slashes (\\), single forward slashes (/) and UNC paths are supported. For example:

include C:\\Program Files\\Java\\jdk-24\\java.config
include C:/Program Files/Java/jdk-24/additional.java.config
include \\\\WindowsHost\\Share\\unc.path.java.config

URL file paths (for example, those that start with file://) are not supported.

include directives support property expansion. This is similar to expanding variables in a shell. When a string like ${some.property} appears in an include directive, it will be expanded to the value of the system property. For example:

include ${java.home}/extra.security

This will expand ${java.home} to use the value of the java.home system property. If that property's value is /usr/lib/jvm/jdk-24, then the previous example is equivalent to:

include /usr/lib/jvm/jdk-24/conf/security/extra.security

To assist in platform-independent policy files, you can also use the special notation of ${/}, which is a shortcut for ${file.separator}. This allows directives like the following:

include ${java.home}${/}extra.security

When the JVM encounters an include directive, it processes it immediately irrespective of preceding or subsequent occurrences. Its position in the file may affect security properties values as described in Order of include Directives in Security Properties Files. However, include directives don't interfere with each other; the JVM always processes them. By contrast, security properties defined later in a security properties or brought in by a following inclusion would override a previous definition if their names are the same.

The JVM generates an error if a file can't be included. This may happen if the file can't be resolved, doesn't exist, is a directory, has insufficient permissions for the JVM to read it, is recursively included more than once, or for any other reason.

Included security properties files can include others recursively as long as it doesn't lead to a cycle. For example, suppose that java.security includes the security properties file A.security, and A.security includes the security properties file B.security. The security properties file B.security can't include A.security as this would create a cycle.