Files to Administer by Hand (Java Security)

A.4. Files to Administer by Hand

There are two security-related files in the Java platform that must be modified by hand (rather than by a tool). We've talked about these files throughout the book, but for reference, we'll discuss the files and the information they hold.

A.4.1. The java.security File

The java.security file must be in the $JAVAHOME/lib/security directory. This file is consulted for the following information:

A list of security providers

You may have any number of entries in this file that specify a security provider that should be installed into the virtual machine. By default, there is one security provider specified by this entry:

security.provider.1=sun.security.provider.Sun

You may specify additional security providers by listing their full class name in this file. Make sure that all security providers are numbered consecutively starting with 1; additional providers can be added before the Sun provider as long as the number assigned to the Sun provider is adjusted accordingly (or the Sun provider could be removed altogether). Remember that this list of providers is consulted when the virtual machine first starts, but that programs with sufficient permissions may add and delete providers from this list.

A KeyStore type

You must have and entry in this file that lists the default type of keystore that an application should use. By default, that type is listed as:

keystore.type=jks

If you change the type listed in this entry, the new type will be used whenever anyone requests the default keystore implementation.

A Policy class implementation

You must have an entry in this file that lists the class that should be used to provide the implementation of the Policy class. By default, that class is listed as:

policy.provider=sun.security.provider.PolicyFile

If you change the class listed in this entry, the new class will be instantiated when the policy object is required (i.e., when the permissions for a given codebase are first used). There can be only one policy entry in this file.

The names of the default policy files

When the default implementation of the Policy class reads in permissions, it will read them from the URLs listed as this set of properties:

policy.url.1=file:${java.home}/lib/security/java.policy

policy.url.2=file:${user.home}/.java.policy

You may specify any number of files in this manner, but the list must start at 1 and be numbered consecutively. The set of permissions will be the aggregate of all permissions found in these URLs.

Remember that these URLs contain only global permissions. You may also specify on the command line a file containing policies with the -Djava.security.policy argument. If the name following the -Djava.security.policy argument begins with an equals sign, the URLs listed in the java.security file are ignored:

-Djava.security.policy=/globals/java.policy

adds the policies in the /globals/java.policy file to the set of policies in force, but:

-Djava.security.policy==/globals/java.policy

sets the policy only to the entries contained in the /globals/java.policy file. The -Djava.security.policy argument must be with the -Djava.security.manager; if you want to use only the files listed in the java.security file, specify -Djava.security.manager without -Djava.security.policy.

Other implementations of the Policy class may or may not use these properties.

Whether or not property substitution is allowed

The ability to make property substitutions for entries in the java.security file or in the java.policy file depends on this entry:

policy.expandProperties=true

Whether or not the -Djava.security.policy argument can be used

The ability to use the -Djava.security.policy argument depends on this entry:

policy.allowSystemProperty=true

A.4.2. The java.policy File

In many cases, you'll use policytool to modify the entries in a java.policy file (or create a new one). However, if you need to add custom permissions to this file that aren't supported by policytool, you must edit it by hand.

The format of the java.policy file is as follows:

Class Definition

keystore "<keystore_url>";

grant [signedBy "<signer1[, signer2]>"] [codeBase "<URL>"] {
	permission <classname> ["<name>"] [, "<actions>"]
					[, signedBy "<signer1[, signer2]>"];
	...
};
...

Items in square brackets are optional. Items in angled brackets are replaced by specific information, e.g., a signer must be a valid alias in the keystore. Within a grant block, there may be any number of permissions, and within a file, there may be any number of grant blocks.

For example, here are some typical entries in the java.policy file:

Class Definition

grant {
	permission java.util.PropertyPermission "java.version", "read";
}

grant signedBy "sdo", codeBase "http://piccolo/" {
	permission java.io.FilePermission "${/}tmp${/}-", "read, write, delete";
	permission XYZPayrollPermission "*", "read, write";
}

grant codeBase "http://www.sun.com" {
	permission java.io.FilePermission "${/}tmp${/}-", "read";
	permission java.io.FilePermission "${/}tmp${/}-",
				"read, write, delete", signedBy "sdo";
}

In the first block, permission is given to code that comes from any location to access the java.version property. The second block grants permissions (including a custom XYZ payroll permission) to any code that is loaded from the site piccolo and that is signed by sdo. The third block grants permission to any code that is loaded from www.sun.com to read files in the /tmp directory (or any of its subdirectories); if that code is signed by sdo, it is allowed to read, write, and delete such files.