Configuring Java Security

Java applets are not normally allowed to access your disk, access your clipboard, or make a network connection to any host except for the server from which they were loaded. This is a design feature of the language. Unlike traditional programs which you must download to your computer, install, and then decide to run, (and which you can first scan with an anti-virus program or somehow authenticate), Java applets are run directly from a server on the Internet. If you have the Java feature enabled in your browser, it will automatically run applets on web pages you access. Since anyone can create an applet and put it onto a web page where it can be accessed by the public, wittingly or otherwise, there would be a significant potential for and danger of malicious programming were it not for the Java security manager.

The security manager is a part of the Java Runtime Environment (JRE). It sits between the Java code and the operating system, and decides what operations the Java code is allowed to carry out. In the case of applets, for maximum protection of both your privacy and your disk contents, by default it allows no disk access whatsoever. This is necessary for the language to be widely used, but it makes life difficult for programmers and users alike when disk access is needed for an applet to be useful. Case in point: a role-playing game isn't much use if you can't save your character somehow. (The game author has helpfully provided an option to save your game to the server, as well as to local disk).

In Java 1.1 and earlier versions the security policy is hard-coded into the security manager and therefore the security policy is essentially fixed in the most restrictive state. You have to change the security manager in order to change the policy. In Java2 (Java 1.2) and subsequent releases the security manager works with another mechanism called the access controller. The access controller allows the security policy to be specified in a file. By editing this file, you can tell the access controller what rights are allowed to specific Java classes. A Java class is a file containing Java bytecode, and an applet will typically consist of many classes which are loaded as needed. So you can grant permission for disk access to applets that you trust by giving the appropriate classes of that applet read and/or write file access.

Although it is theoretically possible to edit the policy file by hand using a text editor, the format is so arcane as to make this thoroughly impractical. Fortunately, Sun Microsystems provides a program called policytool as part of the JRE, with which the policy file can be edited. Unfortunately, they didn't make the program particularly easy to find.

As an example, let's assume that you are running Windows95 on a PC and that you have downloaded and installed the Java 1.2 JRE to the default location: C:\Program Files\JavaSoft\Jre\1.2. Regardless of where you actually installed it, there will be two subdirectories, bin and lib. The policytool program is located in the bin subdirectory, while the policy file is located in subdirectory security under  the lib subdirectory. So in this example, the full pathname for the policytool program is
    C:\Program Files\JavaSoft\Jre\1.2\bin\policytool
and the full pathname for the policy file is
    C:\Program Files\JavaSoft\Jre\1.2\lib\security\java.policy

You can invoke the policytool program by typing the name on a command line (in this example from within a DOS window) or by drilling down through folders from the desktop until you reach the bin folder and then clicking on the program icon. When policytool starts it will probably complain that it could not find the policy file. If it does, then dismiss the error message, pull down the File menu and click on Open. In the file selection pop-up, go to the directory mentioned above for the policy file. If you are in the bin subdirectory, then you will have to go up one directory level, then down two levels into the lib and then the security  subdirectories. Then click on java.policy to open the policy file.

In a window of the policytool program you will see some lines displayed which look like this:
    CodeBase "file:${java.home}/lib/ext/-"
    CodeBase <ALL>
Do not mess with these policy entries. They control access to the native libraries and are required for the JRE to work properly.

Click on the "Add Policy Entry" button. You'll get a pop-up dialog window entitled "Policy Entry". At the top of the window are fields labeled "CodeBase:" and "SignedBy:". The CodeBase is the location of the class files for which the policy entry applies. Specifying the CodeBase limits the permissions you will add in the next step to just the RangeLaw applet. The CodeBase can be a local directory as in the case of the native libraries, or it can be a site on the web. Type in the URL where the classes for the RangeLaw applet are located: "http://www.rangelaw.com/game/jars/range.jar". If you leave this field blank, you will give the new permissions to all Java applets, thereby bypassing the Java security. The second field, "SignedBy:", must be left blank. This field provides an opportunity to specify a trusted certification authority which authenticates a "seal of approval" on the class files. If the class files have been tampered with, then the permissions will not be granted. RangeLaw does not currently support this feature, although adding such support in the future is planned.

Click on the "Add Permission" button. You'll get another pop-up dialog window entitled "Permissions". In the combo box field labeled "Permission:", pull down the list of possibilities and then select "AllPermission". In the previously empty text field to the right of that combo box, you should now see the text "java.security.AllPermission". Note that when you select "AllPermission", the following fields "Target Name:" and "Actions:" become unchangeable because they are not needed. What you are doing is giving the RangeLaw applet all the possible permissions: it will be allowed to read from and write to your disks (in order to save and load characters) and it will also be allowed to establish network connections to any servers (although it currently does not need to do this, it could be useful in the future to allow saving characters to a server). Click on the "OK" button.

Upon return to the "Policy Entry" dialog window you should now see the line "permission java.security.AllPermission;". Click on the "Done" button.

Upon return to the policytool program main window you should now see an additional line. In this example, you would see these three lines:
    CodeBase "file:${java.home}/lib/ext/-"
    CodeBase <ALL>
    CodeBase "http://www.rangelaw.com/jars/range.jar/"

Pull down the File menu and click on Save, then pull the File menu down again and click on Exit. Congratulations. You have configured the Java security.

A note of warning. If you add a policy entry without entering anything in the "CodeBase:" field, then in the policytool program the CodeBase will be shown as <ALL>. You might do this if you want to give all applets permission to read files from your disks. In that case, in the policytool main window in the above example you would see these three lines:
   CodeBase "file:${java.home}/lib/ext/-"
    CodeBase <ALL>
    CodeBase <ALL>
Although the second and third lines look the same, they do not confer the same permissions. Do not delete one of them in the mistaken belief that there is a redundant line. Furthermore, if you decide to revoke the permissions which you have just granted, be sure to delete the line you added - the third line in this example - and never delete the original one.

The latest version of the JRE for Win95/98/Me actually has two JREs in it, versions 1.2 and 1.3, in corresponding subdirectories. You should set up the policy file for both.

If you are a developer and have installed the Java Development Kit (JDK) in addition to the standalone JRE, note that the JDK has its own bundled JRE.  If you use the JDK's JRE to run your Java programs (and the IDE tools which wrap around the JDK will do this), then you'll have to configure the policy file for the JDK's JRE as well. The JDK may also be referred to as the Software Development Kit (SDK) - it would be nice if Sun would just settle on a name.

If Java2 is directly supported by your browser (Netscape 6, for example), the browser may have some easy-to-use options for configuring Java security in the Preferences menu. If the options only support giving permissions to signed applets then you'll still have to use the policytool because the RangeLaw applet is not yet signed (this is a whole other big can of worms...).

back to Game Requirements

go to Home Page

Email: RangeMaster@rangelaw.com

Web page last updated February 11, 2001