Security: Quick tour of controlling Applets

Security

Trail: Security Features in Java SE

In this trail you'll learn how the built-in Java™ security features protect you from malevolent programs. You'll see how to use tools to control access to resources, to generate and to check digital signatures, and to create and to manage keys needed for signature generation and checking. You'll also see how to incorporate cryptography services, such as digital signature generation and checking, into your programs.

The security features provided by the Java Development Kit (JDK™) are intended for a variety of audiences:

• Users running programs:

  Built-in security functionality protects you from malevolent programs (including viruses), maintains the privacy of your files and information about you, and authenticates the identity of each code provider. You can subject applications and applets to security controls when you need to.

• Developers:

  You can use API methods to incorporate security functionality into your programs, including cryptography services and security checks. The API framework enables you to define and integrate your own permissions (controlling access to specific resources), cryptography service implementations, security manager implementations, and policy implementations. In addition, classes are provided for management of your public/private key pairs and public key certificates from people you trust.

• Systems administrators, developers, and users:

  JDK tools manage your keystore (database of keys and certificates); generate digital signatures for JAR files, and verify the authenticity of such signatures and the integrity of the signed contents; and create and modify the policy files that define your installation's security policy.

Observe Applet Restrictions

The Java Plug-in uses a Security Manager to keep viruses from accessing your computer through an applet. No unsigned applet is allowed to access a resource unless the Security Manager finds that permission has been explicitly granted to access that system resource. That permission is granted by an entry in a policy file.

Here's the source code for an applet named WriteFile that tries to create and to write to a file named writetest in the current directory. This applet will not be able to create the file unless it has explicit permission in a policy file.

Type this command in your command window:

appletviewer http://java.sun.com/docs/books/tutorial/security/tour1/examples/WriteFile.html

Type this command on a single line, without spaces in the URL.

You should see a message about a security exception, as shown in the following figure. This is the expected behavior; the system caught the applet trying to access a resource it does not have permission to access.

Set up a Policy File to Grant the Required Permission

A policy file is an ASCII text file and can be composed via a text editor or the graphical Policy Tool utility demonstrated in this section. The Policy Tool saves you typing and eliminates the need for you to know the required syntax of policy files, thus reducing errors.

This lesson uses the Policy Tool to create a policy file named mypolicy, in which you will add a policy entry that grants code from the directory where WriteFile.class is stored permission to write the writetest file.

Follow these steps to create and modify your new policy file:

1. Start Policy Tool

2. Grant the Required Permission

3. Save the Policy File

---

Note for UNIX Users: The steps illustrate creating the policy file for a Windows system. The steps are exactly the same if you are working on a UNIX system. Where the text says to store the policy file in the C:\Test directory, you can store it in another directory. The examples in the step See the Policy File Effects and in the lesson Quick Tour of Controlling Applications assume that you stored it in the ~/test directory.

Start 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 attempts to fill in this window with policy information from the user policy file. The user policy file is named .java.policy by default in your home directory. If Policy Tool cannot find the user policy file, it issues a warning and displays a blank Policy Tool window (a window with headings and buttons but no data in it), as shown in the following figure.

This figure has been reduced to fit on the page.
Click the image to view it at its natural size.

You can then proceed to either open an existing policy file or to create a new policy file.

The first time you run the Policy Tool, you will see the blank Policy Tool window, since a user policy file does not yet exist. You can immediately proceed to create a new policy file, as described in the next step.

Grant the Required Permission

To grant the WriteFile applet permission to create and to write to the writetest file, you must create a policy entry granting this permission. To create a new entry, click on the Add Policy Entry button in the main Policy Tool window. This displays the Policy Entry dialog box as shown in the following figure.
This figure has been reduced to fit on the page.
Click the image to view it at its natural size.

A policy entry specifies one or more permissions for code from a particular code source - code from a particular location (URL), code signed by a particular entity, or both.

The CodeBase and the SignedBy text boxes specify which code you want to grant the permission(s) you will be adding in the file.

• A CodeBase value indicates the code source location; you grant the permission(s) to code from that location. An empty CodeBase entry signifies "any code" -- it does not matter where the code originates.

• A SignedBy value indicates the alias for a certificate stored in a keystore. The public key within that certificate is used to verify the digital signature on the code. You grant permission to code signed by the private key corresponding to the public key in the keystore entry specified by the alias. The SignedBy entry is optional; omitting it signifies "any signer" -- it does not matter whether the code is signed, or by whom.

If you have both a CodeBase and a SignedBy entry, the permission(s) are granted only to code that is both from the specified location and signed by the named alias.

To grant WriteFile the permission it needs, you can grant permission to all code from the location (URL) where WriteFile.class is stored.

Type the following URL into the CodeBase text box of the Policy Entry dialog box:

http://java.sun.com/docs/books/tutorial/security/tour1/examples/

Note: This is a URL. Therefore, it must always use slashes as separators, not backslashes.

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

---

Note: To grant the permission to any code (.class file) not just from the directory specified previously but from the security directory and its subdirectories, type the following URL into the CodeBase box:

http://java.sun.com/docs/books/tutorial/security/-

---

You have specified where the code comes from (the CodeBase), and that the code does not have to be signed (since there is no SignedBy value). Now you are ready to grant permissions to that code.

Click on the Add Permission button to display the Permissions dialog box.

This figure has been reduced to fit on the page.
Click the image to view it at its natural size. Follow these steps to grant code from the specified CodeBase permission to write (and thus also to create) the file named writetest.

1. Choose File Permission from the Permission drop-down list. The complete permission type name (java.io.FilePermission) now displays 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 the file named writetest:

   writetest
   

3. Specify write access by choosing the write option from the Actions drop-down list.

The Permissions dialog box now looks like the following.
This figure has been reduced to fit on the page.
Click the image to view it at its natural size.

Click on the OK button. The new permission displays in a line in the Policy Entry dialog. So now the policy entry window looks like this.

This figure has been reduced to fit on the page.
Click the image to view it at its natural size.

You have now specified this policy entry, so click on the Done button in the Policy Entry dialog. The Policy Tool window now contains a line representing the policy entry, showing the CodeBase value.

This figure has been reduced to fit on the page.
Click the image to view it at its natural size.

Save the Policy File

To save the new policy file you've been creating, choose the Save As command from the File menu. This displays the Save As dialog box.

The examples in this lesson and in the Quick Tour of Controlling Applications lesson assume that you stored the policy file in the Test directory on the C: drive.

Navigate to the Test directory. Type the file name mypolicy and click on Save.

The policy file is now saved, and its name and path are shown in the text box labeled Policy File.

This figure has been reduced to fit on the page.
Click the image to view it at its natural size.

Exit Policy Tool by choosing Exit from the File menu.

See the Policy File Effects

Now that you have created the mypolicy policy file, you can execute the WriteFile applet to create and to write the file writetest, as shown in the following figure.

Whenever you run an applet, or an application with a security manager, the policy files that are loaded and used by default are the ones specified in the "security properties file", which is located in one of the following directories:

  Windows:
   java.home\lib\security\java.security
 UNIX:
   java.home/lib/security/java.security

Note: The java.home environment variable names the directory into which the JRE was installed.

The policy file locations are specified as the values of properties whose names take the form

policy.url.n

Where n indicates a number. Specify each property value in a line that takes the following form:

policy.url.n=URL

Where URL is a URL specification. For example, the default policy files, sometimes referred to as the system and user policy files, respectively, are defined in the security properties file as

policy.url.1=file:${java.home}/lib/security/java.policy
policy.url.2=file:${user.home}/.java.policy

---

Note: Use of the notation ${propName} in the security properties file is a way of specifying the value of a property. Thus ${java.home} will be replaced at runtime by the actual value of the "java.home" property, which indicates the directory into which the JRE was installed, and ${user.home} will be replaced by the value of the "user.home" property, for example, C:\Windows.

---

In the previous step you did not modify one of these existing policy files. You created a new policy file named mypolicy. There are two possible ways you can have the mypolicy file be considered as part of the overall policy, in addition to the policy files specified in the security properties file. You can either specify the additional policy file in a property passed to the runtime system, as described in Approach 1, or add a line in the security properties file specifying the additional policy file, as described in Approach 2.

---

Note: On a UNIX system, you must have DNS configured in order for the WriteFile program to be downloaded from the public web site, shown in the command below. You need to have dns in the list of lookup services for hosts in your /etc/nsswitch.conf file, as in

    hosts:    dns files nis

You also need a /etc/resolv.conf file with a list of nameservers. Consult your system administrator for more information.

---

Approach 1

You can use the appletviewer command-line argument, -J-Djava.security.policy, to specify a policy file that should be used, in addition to the ones specified in the security properties file. To run the WriteFile applet with your new mypolicy policy file included, type the following in the directory in which mypolicy is stored:

appletviewer -J-Djava.security.policy=mypolicy 
http://java.sun.com/docs/books/tutorial/security/tour1/examples/WriteFile.html

---

Notes:

• Type this command as a single line, with a space between mypolicy and the URL, and no spaces in the URL. Multiple lines are used in this example for legibility purposes.

• If this command line is longer than the maximum number of characters you are allowed to type on a single line, do the following. Create and save a text file containing the full command, and name the file with a .bat extension, for example, wf.bat. Then in your command window, type the name of the .bat file instead of the command.

---

If the applet still reports an error, you must troubleshoot the policy file. Use the Policy Tool to open the mypolicy file (using File > Open) and check the policy entries you just created in the previous step, Set Up a Policy File to Grant the Required Permissions.

To view or edit an existing policy entry, click on the line displaying that entry in the main Policy Tool window, then choose the Edit Policy Entry button. You can also double-click the line for that entry.

This launches the same type of Policy Entry dialog box that displays when you are adding a new policy entry after choosing the Add Policy Entry button, except in this case the dialog box is filled in with the existing policy entry information. To change the information, retype it (for the CodeBase and SignedBy values) or add, remove, or modify permissions.

Approach 2

You can specify a number of URLs (including ones of the form "http://") in policy.url.n properties in the security properties file, and all the designated policy files will get loaded.

So one way to have our mypolicy file's policy entry considered by the appletviewer is to add an entry specifying that policy file in the security properties file.

---

Important: If you are running your own copy of the JDK, you can easily edit your security properties file. If you are running a version shared with other users, you may only be able to modify the system-wide security properties file if you have write access to it or if you ask your system administrator to modify the file when appropriate. However, it's probably not appropriate for you to make modifications to a system-wide policy file for this tutorial test. We suggest that you just read the following to see how it is done or that you install your own private version of the JDK to use for the tutorial lessons.

---

To modify the security properties file, open it in an editor suitable for editing an ASCII text file. Then add the following line after the line starting with policy.url.2:

  Windows:
   policy.url.3=file:/C:/Test/mypolicy
 UNIX:
   policy.url.3=file:${user.home}/test/mypolicy

On a UNIX system you can also explicitly specify your home directory:

policy.url.3=file:/home/susanj/test/mypolicy

Now you can run the following:

appletviewer http://java.sun.com/docs/books/tutorial/
security1.2/tour1/examples/WriteFile.html

Type this command on one line, without spaces in the URL.

If you still get a security exception, you must troubleshoot your new policy file. Use the Policy Tool to check the policy entry you just created in the previous step, Set Up a Policy File to Grant the Required Permissions. Change any typos or other errors.

---

Important: The mypolicy policy file is also used in the Quick Tour of Controlling Applications lesson. You do not need to include the mypolicy file unless you are running this Tutorial lesson. To exclude this file, open the security properties file and delete the line you just added.

---