policytool(1)						      General Commands Manual						     policytool(1)

NAME

       policytool - policy file creation and management tool

SYNOPSIS

       policytool

DESCRIPTION

       The  policy for a Java runtime (specifying which permissions are available for code from various sources, when executing as various princi-
       pals) 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 here. Using the Policy Tool
       saves typing and eliminates the need for you to know the required policy file syntax thus reducing errors.

   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 pol-
       icy 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, option-
       ally 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 OK 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, type the following file: URL into the text box  labeled
       "New KeyStore URL".

	      file:/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

       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

       o      an  optional CodeBase entry indicating the URL location where the code originates from. For example, to indicate code from the local
	      /JavaSoft/TESTS/ directory, type the following file URL into the CodeBase text box:

	      file:/JavaSoft/TESTS

       o      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

       o      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.

       o      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.

   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  but-
       ton. 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 Pol-
       icy 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 OK 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  com-
       mand 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.

SEE ALSO

       http://rhea.sfbay:91/j2se/1.5.0/docs/guide/security/permissions.html   http://java.sun.com/j2se/1.5/docs/tooldocs/solaris/policytool.html
       http://rhea.sfbay:91/j2se/1.5.0/docs/tooldocs/solaris/keytool.html

								   24 June 2004 						     policytool(1)