policytool(1)
NAME
policytool - policy file creation and management tool
SYNOPSIS
policytool
DESCRIPTION
The policy for a Java runtime (specifying which permis
sions are available for code from various sources, when
executing as various principals) is represented by a Pol
icy 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 policy
file, it reports the situation and displays a blank "Pol
icy Tool" window (that is, a window with headings and but
tons 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 sav
ing 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 cur
rently open policy file (if any, after first prompting you
to save it if needed) and bring up a new policy tool win
dow, 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 cre
ated manually), the tool will bring up a window without
any data in it. - Once you have a new policy tool window, you can then cre
ate 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 nav
igate the directory structure until you get to the direc
tory 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 pro
prietary 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
- · an optional CodeBase entry indicating the URL loca
tion 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 - · 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 Princi
pals 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 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, sim
ply retype it (for the CodeBase and SignedBy values) or
use the buttons (for the Principals and Permissions val
ues). - 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 dif
ferent 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 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.
SEE ALSO
- More extensive documentation for PolicyTool is available
online at
http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/policy
tool.html