Synopsis

policytool

Description

policytool displays a Swing user interface that makes it easy to edit security policy configuration files. The Java security architecture is based on policy files, which specify sets of permissions to be granted to code from various sources. By default, the Java security policy is defined by a system policy file stored in the jre/lib/security/java.policy file and a user policy file stored in the .java.policy file in the user's home directory. System administrators and users can edit these files with a text editor, but the syntax of the file is somewhat complex, so it is usually easier to use policytool to define and edit security policies.

Selecting the policy file to edit

When policytool starts up, it opens the .java.policy file in the user's home directory by default. Use the New, Open, and Save commands in the File menu to create a new policy file, open an existing file, and save an edited file, respectively.

Editing the policy file

The main policytool window displays a list of the entries contained in the policy file. Each entry specifies a code source and the permissions that are to be granted to code from that source. The window also contains buttons that allow you to add a new entry, edit an existing entry, or delete an entry from the policy file. If you add or edit an entry, policytool opens a new window that displays the details of that policy entry.

With the addition of the JAAS API to the core Java platform in Java 1.4, policytool allows the specification of a Principal to whom a set of permissions is granted.

Every policy file has an associated keystore from which it obtains the certificates it needs when verifying the digital signatures of Java code. You can usually rely on the default keystore, but if you need to specify the keystore explicitly for a policy file, use the Change Keystore command in the Edit menu of the main policytool window.

Adding or editing a policy entry

The policy entry editor window displays the code source for the policy entry and a list of permissions associated with that code source. It also contains buttons that allow you to add a new permission, delete a permission, or edit an existing permission.

When defining a new policy entry, the first step is to specify the code source. A code source is defined by a URL from which the code is downloaded and/or a list of digital signatures that must appear on the code. Specify one or both of these values by typing in a URL and/or a comma-separated list of aliases. These aliases identify trusted certificates in the keystore associated with the policy file.

After you have defined the code source for a policy entry, you must define the permissions to be granted to code from that source. Use the Add Permission and Edit Permission buttons to add and edit permissions. These buttons bring up yet another policytool window.

Defining a permission

To define a permission in the permission editor window, first select the desired permission type from the Permission pulldown menu, then select an appropriate target value from the Target Name menu. The choices in this menu are customized depending on the permission type you selected. Some types of permissions, such as FilePermission, do not have a fixed set of possible targets, and you usually have to type in the target you want. For example, you might type "/tmp" to specify the directory /tmp, "/tmp/*" to specify all the files in that directory, or "/tmp/-" to specify all the files in the directory, and, recursively, any subdirectories. See the documentation of the individual Permission classes for a description of the targets they support.

Depending on the type of permission you select, you may also have to select one or more action values from the Actions menu. When you have selected a permission and appropriate target and action values, click the Okay button to dismiss the window.

See also

jarsigner, keytool