Signed Applets, Browsers, and File Access

Feather pen Have you ever asked yourself "How do I sign an applet so it can access local system resources?", or "Why does an applet work in Applet Viewer, but not in my browser?" This article answers these questions, and shows you how to sign an applet, give it access to a local file, and successfully run it.

By default, applets have no access to system resources outside the directory from which they were launched, but a signed applet can access local system resources as allowed by the local system's security policy. The Java Development Kit provides security tools so end users and system administrators can sign applets and applications, and define their local security policy by specifying in a policy file how much access to local system resources a signed applet or application can have.

Web Browsers

If an applet attempts to access local system resources, the applet must be signed and the local system must have a policy file configured to allow the access.

Local File Access

For an applet to access local system resources outside the directory from which the applet is launched, the applet must be granted explicit access to those resources. An applet is granted access to specific resources by setting up a policy file that contains the URLs to one or more resources that specifies the required permissions. When the applet is launched, it must be launched with the policy file to gain the access. Sometimes the permissions in the policy file require an applet be signed to gain access to some URLs and not signed for access to others.

Example

If the policy file requires the applet to be signed, anApplet can get access to the file only if it has the correct signature. If it has the wrong signature or no signature, it will not get access to the file. The policy file might require a signature for writing, but no signature for reading. If anApplet has the correct signature, it will be able to write, but if it does not, anApplet will only be allowed to read.

Example

If a signature is needed for the access, the applet has to be bundled into a Java ARchive (JAR) file before it can be signed. This example shows you how to sign and grant permission to an applet so it can create newfile in the user's home directory when it executes in Applet Viewer.

Signed applet demo

These files are used for the example. You can copy them to or create them in your working directory.

SignedAppletDemo.java file containing the applet code
Write.jp policy file granting access to the user's home directory
Applet tag embedded in the SignedApplet.html file:

<applet code="SignedAppletDemo.class"
   archive="SSignedApplet.jar"
   width=400 height=400>
   <param name=file value="/etc/inet/hosts">
</applet>

Usually an applet is bundled and signed by one person and handed off to another who verifies the signature and runs the applet. In this example, Susan performs Steps 1 through 5 and Ray performs Steps 6 through 8. But, to keep things simple, all steps occur in the same working directory.

Compile the applet
Create a JAR file
Generate Keys
Sign the JAR file
Export the Public Key Certificate
Import the Certificate as a Trusted Certificate
Create the policy file
Run the applet

Susan

Susan bundles the applet executable in a JAR file, signs the JAR file, and exports the public key certificate.

Compile the Applet

In her working directory, Susan uses the javac command to compile the SignedAppletDemo.java class. The output from the javac command is the SignedAppletDemo.class.

javac SignedAppletDemo.java

Make a JAR File

Susan then makes the compiled SignedAppletDemo.class file into a JAR file. The -cvf option to the jar command creates a new archive (c), using verbose mode (v), and specifies the archive file name (f). The archive file name is SignedApplet.jar.

jar cvf SignedApplet.jar SignedAppletDemo.class

Generate Keys

Susan creates a keystore database named susanstore that has an entry for a newly generated public and private key pair with the public key in a certificate.

A JAR file is signed with the private key of the creator of the JAR file and the signature is verified by the recipient of the JAR file with the public key in the pair. The certificate is a statement from the owner of the private key that the public key in the pair has a particular value so the person using the public key can be assured the public key is authentic. Public and private keys must already exist in the keystore database before jarsigner can be used to sign or verify the signature on a JAR file.

In her working directory, Susan creates a keystore database and generates the keys:

keytool -genkey -alias signFiles -keystore susanstore -keypass kpi135 -dname "cn=jones" -storepass ab987c

This keytool -genkey command invocation generates a key pair that is identified by the alias signFiles. Subsequent keytool command invocations use this alias and the key password (-keypass kpi135) to access the private key in the generated pair.

The generated key pair is stored in a keystore database called susanstore (-keystore susanstore) in the current directory, and accessed with the susanstore password (-storepass ab987c).

The -dname "cn=jones" option specifies an X.500 Distinguished Name with a commonName (cn) value. X.500 Distinguished Names identify entities for X.509 certificates.

You can view all keytool options and parameters by typing:

keytool -help

Sign the JAR File

JAR Signer is a command line tool for signing and verifying the signature on JAR files. In her working directory, Susan uses jarsigner to make a signed copy of the SignedApplet.jar file.

jarsigner -keystore susanstore -storepass ab987c -keypass kpi135 -signedjar SSignedApplet.jar SignedApplet.jar signFiles

The -storepass ab987c and -keystore susanstore options specify the keystore database and password where the private key for signing the JAR file is stored. The -keypass kpi135 option is the password to the private key, SSignedApplet.jar is the name of the signed JAR file, and signFiles is the alias to the private key. jarsigner extracts the certificate from the keystore whose entry is signFiles and attaches it to the generated signature of the signed JAR file.

Export the Public Key Certificate

The public key certificate is sent with the JAR file to the whoever is going to use the applet. That person uses the certificate to authenticate the signature on the JAR file. To send a certificate, you have to first export it.

5: Export the Public Key Certificate

In her working directory, Susan uses keytool to copy the certificate from susanstore to a file named SusanJones.cer as follows:

keytool -export -keystore susanstore -storepass ab987c -alias signFiles -file SusanJones.cer

Ray

Ray receives the JAR file from Susan, imports the certificate, creates a policy file granting the applet access, and runs the applet.

Import Certificate as a Trusted Certificate

Ray has received SSignedApplet.jar and SusanJones.cer from Susan. He puts them in his home directory. Ray must now create a keystore database (raystore) and import the certificate into it. Ray uses keytool in his home directory /home/ray to import the certificate:

keytool -import -alias susan -file SusanJones.cer -keystore raystore -storepass abcdefgh

Create the Policy File

The policy file grants the SSignedApplet.jar file signed by the alias susan permission to create newfile (and no other file) in the user's home directory.

Ray creates the policy file in his home directory using either policytool or an ASCII editor.

keystore "/home/ray/raystore";
// A sample policy file that lets a Java program 
// create newfile in user's home directory
// Satya N Dodda

grant SignedBy "susan" {
        permission java.util.PropertyPermission 
               "user.home", "read"
        permission java.io.FilePermission 
                 "${user.home}/newfile", "write"
};

Run the Applet in Applet Viewer

Applet Viewer connects to the HTML documents and resources specified in the call to appletviewer, and displays the applet in its own window. To run the example, Ray copies the signed JAR file and HTML file to /home/aURL/public_html and invokes Applet viewer from his home directory as follows:

appletviewer -J-Djava.security.policy=Write.jp 
  http://aURL.com/SignedApplet.html

Note: Type everything on one line and put a space after Write.jp

The -J-Djava.security.policy=Write.jp option tells Applet Viewer to run the applet referenced in the SignedApplet.html file with the Write.jp policy file.

Note: The Policy file can be stored on a server and specified in the appletviewer invocation as a URL.