#
Policy Tool -

#
Policy File Creation and Management Tool

Creates and modifies the external policy configuration files that define your installation's Java security policy.

## Table of Contents

  Introduction
  Policy Tool Usage
    Starting Policy Tool
    Creating a new Policy File
    Opening a Different Policy File
    Specifying the Keystore
    Adding a New Policy Entry
      Adding a New Principal
      Editing a Principal
      Removing a Principal
      Adding a New Permission
      Editing a Permission
      Removing a Permission
      Completing the Addition of a Policy Entry
    Editing a Policy Entry
    Removing a Policy Entry
    Saving the Policy File
    Exiting the Policy Tool
    Viewing the Warning Log
  Examples
    Starting Creation of the User Policy File
    Adding a Policy Entry
    Specifying a Keystore
    Adding a Policy Entry with a SignedBy Alias
    Adding a Policy Entry with a Principal
    Saving the User Policy File
    Exiting Policy Tool
  See Also

## Introduction

> The policy for a Java runtime (specifying which permissions are available for code from various sources, when executing as various principals) is represented by a Policy object. The default Policy implementation obtains its information from static ASCII policy configuration files.

> A policy file can be composed via a simple text editor, or via the graphical Policy Tool utility described in this document. Using the Policy Tool saves typing and eliminates the need for you to know the required policy file syntax thus reducing errors.

> The Policy Tool Usage section describes how to use the Policy Tool to create and modify policy files.

> The Examples section provides detailed examples of the use of Policy Tool.

> The See Also section provides links to related documentation.

## Policy Tool Usage

> ### Starting Policy Tool

> > To start Policy Tool, simply type the following at the command line.

> >       policytool

> > This brings up the "Policy Tool" window.

> > Whenever Policy Tool is started, it tries to fill in this window with policy information from what is sometimes referred to as the "user policy file". The user policy file is by default a file named `.java.policy` in your home directory. If Policy Tool cannot find the user policy file, it reports the situation and displays a blank "Policy Tool" window (that is, a window with headings and buttons but no data in it):

> > You can then proceed to either open whatever policy file you want to work on or create a new policy file, by adding policy entries, optionally specifying a keystore, and saving the file).

> > The first time you run the Policy Tool, there will not be a user policy file (unless you created one manually).

> ### Creating a new Policy File

> > To create a new policy file, start by simply selecting the New command from the File menu. This will close the currently open policy file (if any, after first prompting you to save it if needed) and bring up a new policy tool window, that is, a window with headings and buttons but no data in it.

> > Please Note: this is not necessary the first time you run the Policy Tool. Since the tool tries to open the user policy file and one doesn't exist yet (unless it was created manually), the tool will bring up a window without any data in it.

> > Once you have a new policy tool window, you can then create the policy entries, and specify the keystore (if any of the policy entries specify a keystore alias). At any point, you can save the policy file.

> ### Opening a Different Policy File

> > To work on a different policy file than the one currently being worked on (if any), use the Open command in the File menu.

> > This will close the currently open policy file (if any, after first prompting you to save it if needed) and will present you with an Open dialog, which you can use to navigate the directory structure until you get to the directory containing the policy file you want to work on. Select that file, then select the Open button.

> > The "Policy Tool" window will then be filled in with information from the policy file, including the policy file name, the keystore URL (if any), and the CodeBase, SignedBy and Principal parts of each policy entry in the policy file.

> ### Specifying the Keystore

> > To specify the keystore containing the key information for the aliases specified in the SignedBy parts of policy entries, select the Change Keystore command in the Edit menu.

> > This brings up a dialog box in which you specify the new keystore URL and optionally the keystore type.

> > As an example, to specify the keystore named "mykeystore" in the `tests` directory on the `D:` drive, type the following `file:` URL into the text box labeled "New KeyStore URL".

> >       file:/D:/tests/mykeystore

> > To also specify that the keystore type is "JKS" (the proprietary keystore type supported by Sun Microsystems), type the following into the text box labeled "New KeyStore Type".

> >       JKS

> > Note: the "New KeyStore URL" value is a URL and thus should always utilize slashes (never backslashes) as the directory separator, even when the keystore is actually on a Microsoft Windows system.

> > When you are done specifying the keystore URL and type (if any), select OK (or you can select Cancel to cancel the operation). If you didn't cancel, the text box labeled "Keystore:" is now filled in with the keystore URL and type.

> ### Adding a New Policy Entry

> > To add a new policy entry, select the Add Policy Entry button in the main "Policy Tool" window.

> > This brings up a "Policy Entry" dialog box:

> > Using this dialog box, you specify

> > - an optional CodeBase entry indicating the URL location where the code originates from. For example, to indicate code from the local `JavaSoft\TESTS\` directory on the `D:` drive, type the following file URL into the CodeBase text box:

> >         file:/D:/JavaSoft/TESTS/

> >   Note: a CodeBase value contains a URL and thus should always utilize slashes (never backslashes) as the directory separator, even when the code source is actually on a Microsoft Windows system.

> > - an optional SignedBy entry indicating the alias name from the keystore used to reference the signer whose private key was used to sign the code. For example, to indicate the alias named "duke", simply type the following into the SignedBy text box:

> >         duke

> > - an optional Principals entry indicating the list of principals that the code has to be executed as in order for the permission(s) to be granted. See Adding a New Principal.

> > - one or more permission entries indicating which permissions are granted to the code from the source indicated by the CodeBase and SignedBy values (or to any code if no such values are specified) when running as the specified principals in the Principals list. See Adding a New Permission.

> > The SignedBy value is a string alias that is mapped (using the keystore) to a set of public keys that are associated with the signers. These keys are used to verify that classes from the specified code source are really signed by these signers.

> > The SignedBy value can be a comma-separated string containing names of multiple signers, an example of which is "Adam,Eve,Charles", which means "signed by Adam and Eve and Charles" (i.e., the relationship is AND, not OR).

> > The SignedBy value is optional in that, if it is omitted, it signifies "any signer," or in other words, it doesn't matter whether the code is signed or not. Similarly, if there is no CodeBase entry, then it signifies "any code"; it doesn't matter where the code originates from.

> > Thus, if there is no CodeBase entry, then all code signed by the specified alias(es) will be granted the specified permissions. If there is no SignedBy entry, then all code from the specified CodeBase will be granted the specified permissions, regardless of whether the code is signed or not, and by whom. If there is no CodeBase entry, and also no SignedBy entry, then all code will be granted the specified permissions.

> > Note: The exact meaning of a CodeBase value depends on the characters at the end. A CodeBase with a trailing "/" matches all class files (not JAR files) in the specified directory. A CodeBase with a trailing "/*" matches all files (both class and JAR files) contained in that directory. A CodeBase with a trailing "/-" matches all files (both class and JAR files) in the directory and recursively all files in subdirectories contained in that directory.

> > The Principals entry specifies a list of "principal values". Each principal value specifies a principal_type/principal_name pair which must be present within the executing thread's principal set. The Principals entry is optional in that, if it is omitted, it signifies "any principals".

> > If there is no principal_type specified and the principal_name is a quoted string, the string is treated as a keystore alias when the policy file is processed at runtime. The keystore is consulted and queried (via the alias) for an X509 Certificate. If one is found, the principal type is automatically assumed to be javax.security.auth.x500.X500Principal, and the actual principal name is assumed to be the subject distinguished name from the certificate. If an X509 Certificate mapping is not found, the entire policy entry granting permissions to the specified principal is ignored.

> > #### Adding a New Principal

> > > To add a new principal, select the Add Principal button in the "Policy Entry" dialog box. This brings up the "Principals" dialog box:

> > > To add the principal:

> > > 1. Type or select a principal type.

> > >    The drop-down list labeled "Principal Type:" contains a list of built-in principal types. If you want such a type, select it from the list, and the complete principal type name appears in the text box to the right of the drop-down list.

> > >    If you instead want to specify a principal type defined by you or others, type the principal type into the text box.

> > > 2. Type a principal name.

> > >    Type the principal name directly into the text box to the right of the "Principal Name:" text box. For example, to specify the principal named `duke`, type

> > >        duke

> > > When you are done specifying the principal information, select the OK button (or Cancel to cancel). The new principal appears in a line in the "Principals" entry.

> > > You can then add additional principals by following the same sequence of steps. Or you can edit or remove an existing principal.

> > #### Editing a Principal

> > > To edit an existing principal, select the line for that principal in the "Principals:" entry, then select the Edit Principal button. Alternatively, you can simply double-click the line for that principal.

> > > This brings up the same type of "Principals" dialog box as appears when you are adding a new principal, except in this case the dialog box is filled in with the existing principal information. To change the information, either make new selections from the drop-down lists or replace the information in the text boxes.

> > > When you are done, select the OK button (or Cancel to cancel changes). The Principals:" entry now shows the principal with your modifications.

> > #### Removing a Principal

> > > To remove an existing principal, select the line for that principal in the "Principals:" entry, then select the Remove Principal button.

> > #### Adding a New Permission

> > > To add a new permission, select the Add Permission button in the "Policy Entry" dialog box. This brings up the "Permissions" dialog box:

> > > To add the permission:

> > > 1. Type or select a permission type.

> > >    The drop-down list labeled "Permission:" contains a list of built-in permission types. If you want such a type, select it from the list, and the complete permission type name appears in the text box to the right of the drop-down list.

> > >    If you instead want to specify a permission type defined by you or others, type the permission type into the text box.

> > > 2. Type or select a permission target name.

> > >    If you selected a built-in permission from the "Permission:" drop-down list, and permissions of that type have specific target name values, then the drop-down list labeled "Target Name:" contains a list of those values, from which you can choose.

> > >    In some cases, where the target name possibilities are infinite but there are some built-in target name specifications that have special meaning, such target names will appear in the drop-down list. For example, the special target name of "<<All Files>>" will appear in the list for File Permissions.

> > >    To specify a target name not available in the drop-down list, type the target name directly into the text box to the right of the "Target Name:" drop-down list. For example, to specify the file named `data` in the `JavaSoft\ptTest\` directory on the `D:` drive, type

> > >          D:\JavaSoft\ptTest\data

> > > 3. Type or select one or more actions, if actions are relevant.

> > >    Some permissions just have a target name, but no actions. For such permissions, leave the text box to the right of the "Actions:" drop-down list blank. (It will automatically be darkened and unavailable for this type of built-in permission.)

> > >    For permissions requiring action specifications, type the comma-separated list of actions into the text box, or select them from the drop-down list. For example, to specify both read and write access to a file specified for a File Permission, first select `read` (or `write`, order doesn't matter) from the list. The word "read" appears in the text box. Then select `write`, and the word "write" will be appended, preceded by a comma and a space.

> > > 4. Type a SignedBy alias into the text box to the right of the "Signed By" label, if required. The SignedBy value for a permission entry is optional. If present, it indicates a signed permission. That is, the permission class itself must be signed by the given alias(es) in order for the permission to be granted.
> > > When you are done specifying the permission information, select the OK button (or Cancel to cancel). The new permission appears in a line in the "Policy Entry" dialog.

> > > You can then add additional permissions by following the same sequence of steps. Or you can edit an existing permission or remove a permission.

> > #### Editing a Permission

> > > To edit an existing permission, select the line for that permission in the "Policy Entry" dialog box, then select the Edit Permission button. Alternatively, you can simply double-click the line for that permission.

> > > This brings up the same type of "Permissions" dialog box as appears when you are adding a new permission, except in this case the dialog box is filled in with the existing permission information. To change the information, either make new selections from the drop-down lists or replace the information in the text boxes.

> > > When you are done, select the OK button (or Cancel to cancel changes). The "Policy Entry" dialog now shows the permission with any modifications you made.

> > #### Removing a Permission

> > > To remove an existing permission, select the line for that permission in the "Policy Entry" dialog box, then select the Remove Permission button.

> > #### Completing the Addition of a Policy Entry

> > > Once you are done adding a policy entry, select the Done button in the "Policy Entry" dialog, or Cancel to cancel.

> > > If you selected Done, the "Policy Tool" window now contains a line representing the policy entry. The line contains the CodeBase, SignedBy and Principals information (if any). If none was specified in the "Policy Entry" dialog, just

> > >       CodeBase <ALL>

> > > appears.

> > > Note: a warning is displayed upon closing the policy entry if it contains any SignedBy aliases that don't yet exist in your keystore. Select OK and make a note to create such an alias, or edit the policy entry to fix the alias if was wrong.

> ### Editing a Policy Entry

> > To edit an existing policy entry, select the line for that entry in the main "Policy Tool" window, then select the Edit Policy Entry button. Alternatively, you can simply double-click the line for that entry.

> > This brings up the same type of "Policy Entry" dialog box as appears when you are adding a new policy entry, except in this case the dialog box is filled in with the existing policy entry information. To change the information, simply retype it (for the CodeBase and SignedBy values) or use the buttons (for the Principals and Permissions values).

> > When you are done, select the Done button (or Cancel to cancel).

> ### Removing a Policy Entry

> > To delete a policy entry from the policy file, select the line for that entry in the main "Policy Tool" window, then select the Remove Policy Entry button.

> > The complete policy entry is displayed, and you can then either select OK to remove the entry, or Cancel to keep it.

> ### Saving the Policy File

> > To save changes to an existing policy file, simply select the Save command in the File menu.

> > To save a new policy file you've been creating, or to copy an existing policy file to a new policy file with a different name, select the Save As command from the File menu. This brings up the Save As dialog box.

> > Navigate the directory structure to get to the directory in which you want to save the policy file. Type the desired file name, then select the Save button. The policy file is now saved, and its name and path are shown in the text box labeled "Policy File:"

> ### Exiting the Policy Tool

> > To exit Policy Tool, select the Exit command from the File menu.

> ### Viewing the Warning Log

> > If Policy Tool ever reports that warnings have been stored in the Warning Log, you can view the log by selecting the View Warning Log command in the Edit menu.

> > For example, if you have a policy file with a Keystore URL specifying a keystore that doesn't yet exist, you will get such a warning at various times, e.g., when you open the file. You can continue to work on the policy file even if warnings exist.

> ### Note Regarding File Specifications

> > Note: On Microsoft Windows systems, when you type a file name and path into a Policy Tool dialog box (e.g., as a FilePermission target name), you can use any of the following as the directory separator:

> > - a single backslash, as in `D:\Temp\data`
> > - a double backslash, as in `D:\\Temp\\data`
> > - a slash, as in `D:/Temp/data`
> > Single backslashes are the "normal" Microsoft Windows directory separators, and slashes are also accepted.

> > However, policy files themselves cannot contain single backslashes. When a policy file is read, the strings are processed by a tokenizer, which allows "\" to be used as an escape string (e.g., "\n" to indicate a new line) and which thus requires two backslashes to indicate a single backslash.

> > If you use single backslashes as your separators, Policy Tool automatically converts them to double backslashes (e.g., after you select OK in the Permissions dialog box), for your convenience.

> ### Note Regarding Microsoft Windows "Home" Directories

> > The user policy file is by default the file named `.java.policy` in your "home directory," as determined by the user.home system property value. Given user name uName, the user.home property value defaults to

> >       C:\Winnt\Profiles\uName on multi-user Windows NT systems
> >       C:\Windows\Profiles\uName on multi-user Windows 95 systems
> >       C:\Windows on single-user Windows 95 systems

> > Thus, if the user name is "cathy", user.home defaults to

> >       C:\Winnt\Profiles\cathy on multi-user Windows NT systems
> >       C:\Windows\Profiles\cathy on multi-user Windows 95 systems
> >       C:\Windows on single-user Windows 95 systems

## Examples

> The following examples show how to
> - create the user policy file from scratch

> - add a policy entry

> - specify a keystore

> - add a policy entry for signed code

> - add a policy entry for authenticated code

> - save the user policy file, and

> - exit the Policy Tool

> ### Starting Creation of the User Policy File

> > Initially, there is no user policy file (unless you created one manually). So to create the user policy file, first simply start Policy Tool by typing the following at the command line.

> >       policytool

> > This brings up the "Policy Tool" window.

> > Whenever Policy Tool is started, it tries to fill in this window with policy information from what is sometimes referred to as the "user policy file". The user policy file is by default a file named `.java.policy` in your home directory. If Policy Tool cannot find the user policy file, it reports the situation and displays a blank "Policy Tool" window (that is, a window with headings and buttons but no data in it):

> > You can now create the user policy file by adding entries and saving the file.

> ### Adding a Policy Entry

> > Suppose you want to grant all classes from the `tests\` directory on the `D:` drive permission to read the file named `mydata` in the `D:\temp\data\` directory. To do so, first select the Add Policy Entry button in the main "Policy Tool" window.

> > This brings up a "Policy Entry" dialog box:

> > Using this dialog box, type the file URL

> >       file:/D:/tests/

> > into the CodeBase text box. (Note, this is a URL and thus must always have slashes, not backslashes.)

> > Leave the SignedBy text box blank, since you aren't requiring the code to be signed.

> > Leave the Principals list blank, since you aren't requiring the code to be authenticated.

> > To add the permission, select the Add Permission button. This brings up the "Permissions" dialog box:

> > To add the permission:

> > 1. Select "File Permission" from the "Permission:" drop-down list. The complete permission type name (java.io.FilePermission) now appears in the text box to the right of the drop-down list.

> > 2. Type the following in the text box to the right of the list labeled "Target Name:":

> >          D:\temp\data\mydata

> > 3. Specify read access by either selecting "read" from the "Actions:" drop-down list or directly typing "read" into the text box to the right of the "Actions:" drop-down list.
> > Now the "Permission" dialog box looks like the following:

> > When you are done specifying the permission information, select the OK button. The new permission appears in a line in the "Policy Entry" dialog.

> > Note: Each backslash in the file path you typed has been replaced with two backslashes, as described in Note Regarding File Specifications.

> > You are now done specifying this policy entry, so select the Done button. The "Policy Tool" window now contains a line representing the policy entry. The line just contains the CodeBase value:

> ### Specifying a Keystore

> > Suppose you also want to grant any code from the URL "http://java.sun.com/" and signed by the alias "duke" read access to all files in the `D:\tmp\` directory. Suppose you also want to give such code permission to initiate outgoing socket connections to any hosts. You need to do two things:
> > 1. Specify the keystore containing the alias, and

> > 2. Create the policy entry granting the permissions.
> > To specify the keystore containing the key information for the aliases specified in any SignedBy parts of policy entries, select the Change Keystore command in the Edit menu of the main "Policy Tool" window.

> > This brings up a dialog box in which you specify the new keystore URL and optionally the keystore type.

> > As an example, to specify the keystore named "mykeystore" in the `tests` directory on the `D:` drive, type the following `file:` URL into the text box labeled "New KeyStore URL":

> >       file:/D:/tests/mykeystore

> > If the keystore type is the default type, as specified by the "keystore.type" property value in the security properties file, you don't need to type a "New KeyStore Type" value. The default value of that property is "JKS" (the proprietary keystore type supported by Sun Microsystems).

> > To specify the keystore type, type its value into the text box labeled "New KeyStore Type." For example, to indicate that the keystore type is "JKS" type

> >       JKS

> > The result is:

> > Note: the "New KeyStore URL" value is a URL and thus should always utilize slashes (never backslashes) as the directory separator, even when the keystore is actually on a Microsoft Windows system.

> > When you are done specifying the keystore URL and type, select OK. The text box labeled "Keystore:" is now filled in with the URL and type.

> > Next, you need to specify the policy entry:

> ### Adding a Policy Entry with a SignedBy Alias

> > Select the Add Policy Entry button in the main "Policy Tool" window. This brings up the "Policy Entry" dialog box. Type the following into the the CodeBase text box:

> >       http://java.sun.com/*

> > The "*" indicates that both class and JAR files in the specified directory are to be considered to match this CodeBase.

> > Now, type the following alias into the SignedBy text box:

> >       duke

> > Leave the Principals list blank, since you aren't requiring the code to be authenticated.

> > To add the first permission, select the Add Permission button. This brings up the "Permissions" dialog box. Do the following

> > 1. Select "File Permission" from the "Permission:" drop-down list. The complete permission type name (java.io.FilePermission) now appears in the text box to the right of the drop-down list.

> > 2. Type the following in the text box to the right of the list labeled "Target Name:" to specify all files in the `D:\tmp\` directory:

> >          D:\tmp\*

> > 3. Specify read access by selecting "read" from the "Actions:" drop-down list.
> > Now the "Permissions" dialog box looks like the following:

> > Select the OK button. The new permission appears in a line in the "Policy Entry" dialog.

> > Now you need to add the other permission. Select the Add Permission button. In the "Permissions" dialog box, do the following

> > 1. Select "Socket Permission" from the "Permission:" drop-down list. The complete permission type name (java.net.SocketPermission) now appears in the text box to the right of the drop-down list.

> > 2. Type the following in the text box to the right of the list labeled "Target Name:" to specify all hosts:

> >          *

> > 3. Specify permission to make connections by selecting "connect" from the "Actions:" drop-down list.
> > Now the "Permissions" dialog box looks like the following:

> > Select the OK button. The new permission appears in a line in the "Policy Entry" dialog.

> > Note: Each backslash in the file path you typed has been replaced with two backslashes, as described in Note Regarding File Specifications.

> > You are now done specifying this policy entry, so select the Done button in the "Policy Entry" dialog. The "Policy Tool" window now contains a line representing the policy entry, showing the CodeBase, SignedBy and Principals values.

> ### Adding a Policy Entry with a Principal

> > Suppose you want to grant the principal whose X500 name is

> > >     CN=Duke,OU=JavaSoft,O=Sun Microsystems,C=US

> > permission to write to the `/tmp/` directory.

> > Select the Add Policy Entry button in the main "Policy Tool" window. This brings up the "Policy Entry" dialog box.

> > Leave the CodeBase text box blank since you aren't limiting where the code comes from. Leave the SignedBy text box blank since you aren't requiring the code to be signed.

> > Select the Add Principal button. In the "Principals" dialog box, do the following

> > 1. Select "X500Principal" from the "Principal Type:" drop-down list. The complete principal type name (com.sun.security.auth.X500Principal) now appears in the text box to the right of the drop-down list.

> > 2. Type the following in the text box to the right of the list labeled "Principal Name:" to specify an X500 name for the X500Principal:

> >        CN=Duke,OU=JavaSoft,O=Sun Microsystems,C=US

> > Now the "Principals" dialog box looks like the following:

> > Select the OK button. The new principal appears in a line in the "Principals" list.

> > To add the permission, select the Add Permission button. This brings up the "Permissions" dialog box. Do the following

> > 1. Select "File Permission" from the "Permission:" drop-down list. The complete permission type name (java.io.FilePermission) now appears in the text box to the right of the drop-down list.

> > 2. Type the following in the text box to the right of the list labeled "Target Name:" to specify all files in the `tmp/` directory on `D:` drive:

> >          D:\tmp\*

> > 3. Specify write access by first selecting "write" from the "Actions:" drop-down list.

> > Select the OK button. The new permission appears in a line in the "Policy Entry" dialog.

> > You are now done specifying this policy entry, so select the Done button in the "Policy Entry" dialog. The "Policy Tool" window now contains a line representing the policy entry, showing the CodeBase, SignedBy and Principals values.

> ### Saving the User Policy File

> > Let's assume you're working on a Win95 system and you want to save the policy file you've been creating with the default name (.java.policy) in the default location (`C:\Windows\`).

> > To save the user policy file, select the Save As command from the File menu. This brings up the Save As dialog box.

> > Navigate the directory structure to get to the `Windows` directory on the `C:` drive. Type

> >       .java.policy

> > (note the initial period) as the file name, then select the Save button. The policy file is now saved, and its name and path are shown in the text box labeled "Policy File:".

> ### Exiting Policy Tool

> > When you want to exit Policy Tool, do so by selecting the Exit command from the File menu.

## See Also

> - Permissions in the Java 2 Platform

> - Default Policy Information and Policy File Syntax

> - keytool tool documentation

> - Security Architecture Specification

> - The Security trail of the Java Tutorial for examples of the use of the security tools including Policy Tool

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved. | Java Software