An earlier chapter showed how to put Java applets into jars. The next step is to describe how jars can be used to convey the notion that the code is trusted. Since an applet can be downloaded from anywhere on the net just by browsing a URL, the default security model needs to be very strict. JDK 1.1 introduced support for signing an applet, which gives the browser the opportunity to identify who wrote the applet and then choose to let the applet access all system resources. JDK 1.2 lets you configure more precisely the resources that can be accessed by signed code.

Signing some code in a jar file is like signing a bank check. It means labeling it with a tamper-proof identifying mark saying where it came from. Don’t we already know this? Doesn’t it come from the URL we are browsing? The answer is that we are not sure enough to give our system away to the applet.

Applets start running by virtue of visiting a page; there need not be any visible indication that the page contains an applet. Secondly, although an applet is hosted on a page, it is not necessarily located on that page. The CODEBASE applet tag can point to a URL anywhere else on the net. Finally, with enough effort, it is possible to spoof (masquerade as) web servers. If the stakes are high enough people could do this to make a malicious or fraudulent applet appear to come from mother.teresa.org.

Figure 25-1. Signed applets have more privileges.

A sandbox is like a room built out of firewalls (see Figure 25-2). Applets are executed inside a sandbox by default, so they cannot access the private or vulnerable resources of your system. This is a representative but not exhaustive list of the restrictions on remotely accessed applets.

Figure 25-2. The secure sandbox.

By default, an applet accessed over the net:

• cannot read or write files;

• cannot open a socket connection, except to the server that it came from;

• cannot start up a program on your system;

• cannot call native (non-Java) code.

Applets accessed from a local file system (rather than over the net) are allowed more privileges. They can only be on your local file system with your permission, so it is presumed that you trust them (see Figure 25-3).

Figure 25-3. A local applet can access more resources.

We can write our signature on a check because it is a physical piece of paper. For an applet in a jar file, we add an extra file saying what the origin is. Obviously, it wouldn’t be good enough just to put an ASCII text file in there saying, “Software from Honest Software Corporation,” since the drug-peddling, code-encrypting, porno-terrorists that the FBI says are all over the Internet could easily forge that file on their own applets.

Instead, we use computer encryption to sign a file. Here is a summary of the basic steps:

This process makes the applet trusted. The longest part of the process is the one-time setup.

All browsers install a security manager, and you can install one on your applications too. It’s called by the runtime. Look at this code in the runtime library to create a FileInputStream:

public FileInputStream(String name) throws FileNotFoundException {
    SecurityManager security = System.getSecurityManager();
    if (security != null) {
       security.checkRead(name);
   }
   fd = new FileDescriptor();
   open(name);
} 

Before it does anything else, the code gets the SecurityManager object for the system. If there isn’t one (the reference is null), it goes ahead. However, if someone has created a SecurityManager, then its checkRead() method is called.

The checkRead() method will judge whether this operation is permitted or not. Perhaps it looks to see if the program is trying to read from one of several directories that it is allowed to access. Perhaps the program is only allowed to read files with a certain name, or that are newer than some date. There will be some application-specific protocol for judging whether access is permitted or not.

If it is permitted, the method does its work and returns without a problem. If the file access is not permitted (you’re an ordinary applet that was just downloaded, for example), a SecurityException is thrown, tossing you out of the FileInputStream constructor before the object creation completes.

The SecurityManager is a built-in class in package java.lang with about a dozen methods, each of which checks access to a particular resource: threads, properties, socket connections, reading a file, and so on.

The java.lang.SecurityManager class contains the following public methods:

public class java.lang.SecurityManager extends java.lang.Object {
     public java.lang.SecurityManager();
     public void checkAccept(java.lang.String, int);
     public void checkAccess(java.lang.Thread);
     public void checkAccess(java.lang.ThreadGroup);
     public void checkAwtEventQueueAccess();
     public void checkConnect(java.lang.String, int);
     public void checkConnect(java.lang.String, int, Object);
     public void checkCreateClassLoader();
     public void checkDelete(java.lang.String);
     public void checkExec(java.lang.String);
     public void checkExit(int);
     public void checkLink(java.lang.String);
     public void checkListen(int);
     public void checkMemberAccess(java.lang.Class, int);
     public void checkMulticast(java.net.InetAddress);
     public void checkMulticast(java.net.InetAddress, byte);
     public void checkPackageAccess(java.lang.String);
     public void checkPackageDefinition(java.lang.String);
     public void checkPermission(java.security.Permission);
     public void checkPermission(java.security.Permission, Object);
     public void checkPrintJobAccess();
     public void checkPropertiesAccess();
     public void checkPropertyAccess(java.lang.String);
     public void checkRead(java.io.FileDescriptor);
     public void checkRead(java.lang.String);
     public void checkRead(java.lang.String, java.lang.Object);
     public void checkSecurityAccess(java.lang.String);
     public void checkSetFactory();
     public void checkSystemClipboardAccess();
     public boolean checkTopLevelWindow(java.lang.Object);
     public void checkWrite(java.io.FileDescriptor);
     public void checkWrite(java.lang.String);
     public boolean getInCheck();
     public java.lang.Object getSecurityContext();
     public java.lang.ThreadGroup getThreadGroup();
} 

The methods scrutinize some specific form of resource access. So checkRead(java.io.FileDescriptor) will return normally if a read may be done using this file descriptor, and throw an exception if it should not. The three methods, whose names are not self-descriptive, carry out this processing:

You never call these checking methods; they are called at appropriate times by the Java runtime. The calls are already in place throughout the runtime library. When a Java system first starts executing, the security manager is set to null and the only access restrictions are those imposed by the underlying operating system. In other words, anything goes.

To change the default, you can write your own class that extends SecurityManager and provide new methods to override the parent checking method for the resources you are interested in. The body of each new method contains your algorithm for deciding whether to grant access or not. It will either return or throw a security exception. Returning without throwing an exception means the access is allowed. If you install a new security manager of your own, then every resource not controlled in your new manager is disallowed. Following is an example that allows access to all system properties and nothing else:

class MySecurityManager extends SecurityManager {
     public void checkPropertyAccess(String key) {
          return;
     }
}


public class foo {
     public static void main(String s[]) {
          SecurityManager msm = new MySecurityManager();
          try {
               System.setSecurityManager(msm);
          } catch(Exception e){}
     }
} 

A SecurityManager can be set, at most, once during the lifetime of a Java runtime. There is no way to install a new SecurityManager that includes permission to keep installing new SecurityManagers—it’s a one-shot deal and cannot be replaced, changed, or overridden later on. In an application, you, the programmer, can define the level of security for your program. In an applet, the browser sets the SecurityManager and decides what processes to follow to grant or deny access. Applets must be unable to impose a new security manager.

Different browsers have imposed slightly different SecurityManager policies, and they can take into account whether an applet was loaded from a local file or from browsing over the Internet. Local files only exist on your system because you put them there, so they are presumed to have more privileges. Table 25-1 is a matrix of browser characteristics extracted from the JavaSoft site www.javasoft.com/sfaq.

The restrictions mean that an applet loaded from over the Internet:

The SecurityManager class provides a way to recognize trusted code so we can grant it more capabilities without jeopardizing system security.

You can configure the Sun appletviewer to read and write files on your local disk by editing the file .hotjava/properties. This file is in your home directory on Unix (note its name starts with a dot, so it is not usually visible when you list the directory). Under Windows, the files is in the root directory of the drive on which you installed Java (the file might be C:.hotjavaproperties). Note that this works for the appletviewer only, not other browsers like Netscape.

Then you can set the acl.read and acl.write properties to point to the files or directories that you will allow applets to read or write. For example, if I add these two lines to my ∼/.hotjava/properties file (or my C:.hotjavaproperties file on Windows), then applets are allowed to read any files in /home/linden or to write to any files in the /tmp directory.

acl.read=/home/linden
acl.write=/tmp 

ACL stands for Access Control List—a mainframe feature for providing fine-grained control of resources like files.

Here’s an applet that you can run under Sun’s appletviewer to confirm this:

// <applet code=show.class  height=100 width=200> </applet>
import java.io.*;
import java.awt.*;
import java.applet.Applet;
public class show extends Applet {

     public void Read() throws IOException {

          DataInputStream dis;
          String s, myFile = "show.java";

          dis = new DataInputStream(new FileInputStream(myFile));
          s = dis.readLine();
          System.out.println("line> "+s);
     }

     public void paint(Graphics g) {
          try {
               Read();
               g.drawString("Success in read", 10, 10);
     }
          catch (SecurityException e) {
               g.drawString("Caught security exception in read", 10, 10);
     }
          catch (IOException ioe) {
               g.drawString("Caught i/o exception in read", 10, 10);
          }
     }
} 

If you need a refresher on the I/O details take a look at Chapter 13. For now, the purpose is to demonstrate that the security manager controls the resources accessed by applets and that file I/O is possible from an applet using the applet-viewer.

java -Xrunhprof:cpu=times myprogram 

rank   self  accum   count trace method
   1 24.73% 24.73%       3  1260 java.lang.Object.wait
   2 24.65% 49.38%       2  1275 java.lang.Object.wait
   3  7.52% 56.89%  786432   756 DataBufferInt.getElem
   4  7.26% 64.15%     768   718 SampleModel.getPixels
   5  7.11% 71.26%  786432   259 BufferInt.getElem
   6  6.95% 78.22%     768   535 Model.getPixels
   7  2.45% 80.66%    1605   349 Deflater.deflateBytes
   8  1.28% 81.95%       1   363 LinearRGB16TosRGB8LUT
   9  1.21% 83.15%   65536   638 java.lang.Math.round
  10  1.16% 84.32%   65330   405 java.lang.Math.pow 

The previous three sections explained how security restrictions are enforced. This section describes how a fine-grained security policy can be set up to specify exactly what the restrictions are and to which code and code signers they apply. The notion of security policies, and the tools to adjust them, has been in Java since JDK 1.2.

The one-sentence summary of Java Security Policy is, “There are a bunch of files outside the Java system that keep a record of the way application and applet classes are grouped together into domains, and the permissions associated with those domains.” The security is carefully tracked by the runtime, so a less-privileged class cannot grab more permissions because it called or was called by a more powerful domain.

The way that permission is granted is by adding an entry to a policy file. Policy files exist in a couple of standard places, and users can create additional ones and specify them as a command-line argument when they start a program. The format of an entry in a policy file is a little tricky; it resembles statements in a programming language. At least the entries are in ASCII, not binary, so you don’t have to use the policytool provided, and can just edit the file if you prefer. If this was designed today, the configuration would be specified in XML. Instead. it uses a pseudo-Java syntax.

Each grant entry in the policy file is of the following format, where the leading grant is a reserved word that signifies the beginning of a new entry. Optional items appear in brackets. The keyword permission is another reserved word that marks the beginning of a new permission in the entry. Each entry grants a set of permissions to the specified code source.

grant [SignedBy "signer_names"] [, CodeBase "URL"] {

permission permission_class_name
  ["target_name"]   [,"action"]   [,SignedBy "signer_names"];

    // there may be a series of permission statements
}; 

Here is an example of a pretty minimal policy file. We will use this in a later chapter to grant a program the ability to connect and accept connections on sockets:

grant  {
      permission java.net.SocketPermission "*", "connect";
      permission java.net.SocketPermission "*", "accept";
}; 

We put that text into a file called “permit,” and then start the program mentioning the permission filename like this:

java -Djava.security.policy=permit  MySocketProgram 

Here is another example policy file, where I say that I will grant file read and write permission in the /tmp directory or any subdirectory of it to all applets that originate from the Sun Java site.

grant CodeBase  "http://java.sun.com/" {
     permission java.io.FilePermission "/tmp/*", "read,write";
} 

So where are the standard places that a policy file can exist, and what is the list of permissions?

There is by default a single system-wide policy file, and a single-user policy file. The system policy file is by default located here:

$JAVAHOMElibsecurityjava.policy  (Windows)
$JAVAHOME/lib/security/java.policy  (Solaris) 

The user policy file is by default located in the user’s home directory in a file called this:

.java.policy  (note the leading “.” in the name)) 

The system makes provision for specifying a number of additional policy files, including defining the name of one as a property when you invoke the program, as shown above. This can be done for the appletviewer, too, like so:

appletviewer -J-Djava.security.policy=file:/foo/permit applet.html 

The full list of permissions and subpermissions is shown in Table 25-2. The policytool software will help you navigate these, and you can see why it’s useful.

The next section is a step-by-step example of signing a piece of code so that it can write to the local filesystem.

Applets are not allowed to write to the local file system by default. We will walk through the example of how we can sign an applet so that it does have that ability. It’s a lengthy process the first time because you also need to create and register your cryptographic keys.

There are steps that the code signer has to do (here, linden), and steps that the code receiver has to do to run the code (here, sauceboy). You can sign any kind of Java code: applets or applications. Applets always run under the control of a security manager, but you have to provide one if you want an application to have the same level of assurance.

% keytool
keytool usage:

-certreq     [-v] [-alias <alias>] [-sigalg <sigalg>]
             [-file <csr_file>] [-keypass <keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <storetype>]

-delete      [-v] -alias <alias>
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <storetype>]

-export      [-v] [-rfc] [-alias <alias>] [-file <cert_file>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <storetype>]

-genkey      [-v] [-alias <alias>] [-keyalg <keyalg>]
             [-keysize <keysize>] [-sigalg <sigalg>]
             [-dname <dname>] [-validity <valDays>]
             [-keypass <keypass>] [-keystore <keystore>]
             [-storepass <storepass>] [-storetype <storetype>] 

keytool -genkey -storepass password1 -keystore name1
     -alias name2 -keypass password2 

keytool -genkey -storepass soupy99  -keystore lindenstore
          -alias linden  -keypass lime43 

What is your first and last name?
  [Unknown]:  Peter van der Linden
What is the name of your organizational unit?
  [Unknown]:  code grinding shop
What is the name of your organization?
  [Unknown]:  AFU (Cayman Islands) Inc.
What is the name of your City or Locality?
  [Unknown]:  Silicon Valley
What is the name of your State or Province?
  [Unknown]:  California
What is the two-letter country code for this unit?
  [Unknown]:  US
Is <CN=Peter van der Linden, OU=code grinding shop, O=AFU (Cayman Islands)
Inc., L=Silicon Valley, ST=California, C=US> correct?
  [no]:  y 

% ls -l
-rw-r--r--   1 linden   staff       1351 Nov 15 14:21 lindenstore 

/* <applet
       archive=write.jar    code=write.class
       width=120           height=75>
   </applet>
*/
import java.io.*;
import java.awt.*;
import javax.swing.*;

public class write extends JApplet {

    public void init() {
       try {
           FileWriter fw = new FileWriter("score.txt");
           fw.write("new high score: 14 
");
           fw.close();
       } catch (Exception e) {System.out.println(e);}
  }

    public void paint(Graphics g){
        g.drawString("Try to write a file", 15, 15);
    }
} 

% javac write.java

% jar -cvf write.jar  write.class 

% appletviewer write.java
java.security.AccessControlException: access denied
(java.io.FilePermission score.txt write) 

jarsigner -keystore lindenstore -signedjar swrite.jar write.jar linden 

Enter Passphrase for keystore: soupy99
Enter key password for linden: lime43 

-rw-r--r--   1 linden   staff       2249 Nov 15 14:24 swrite.jar
-rw-r--r--   1 linden   staff        977 Nov 15 14:18 write.jar 

<applet

       archive=swrite.jar
       code=write.class
       width=120
       height=75>
   </applet> 

keytool -export -keystore lindenstore  -alias linden  -file linden.cert 

Enter keystore password:  soupy99
Certificate stored in file <linden.cert> 

keytool -import -alias linden -file linden.cert -keystore sauceboystore

Enter keystore password:  sauce99
Owner: CN=Peter van der Linden, OU=code grinding shop, O=AFU (Cayman
Islands) Inc., L
=Silicon Valley, ST=California, C=US
Issuer: CN=Peter van der Linden, OU=code grinding shop, O=AFU (Cayman
Islands) Inc.,
L=Silicon Valley, ST=California, C=US
Serial number: 364f53f0
Valid from: Sun Nov 15 14:21:36 PST 1998 until: Sat Feb 13 14:21:36 PST
1999
Certificate fingerprints:
         MD5:  E8:83:20:2C:99:5E:AD:25:82:F7:28:B4:96:05:F5:8E
         SHA1: CA:EE:D3:1D:D3:A2:00:0E:E7:C8:0E:CC:8D:06:FC:76:E7:2E:6A:3D
Trust this certificate? [no]:  y 

Step 6: Set up a Security Policy for the User, Allowing Signed Code

The person who wishes to run the signed code (sauceboy, in this example) must now set up a policy file allowing this runtime permission. The policy file is an ASCII file that associates URLs with code signers, with code, and with permis-sions. You can edit the file manually, but there is a GUI utility in JDK 1.2 to help you. The utility is called policytool, so start it up by typing that name. It has the same kind of elementary look and feel as early versions of Netscape. You can’t type directly into text fields; you have to select them from the menu first.

Start policytool and a main window will come up. Using the “Edit” -> “Change KeyStore” menu, type in the new keystore URL for the sauceboy keystore that we created in step 5. Note that the keystore is accessed by an URL, so it can be located anywhere on the Internet (or more likely, your private intranet). Also enter “File” -> “Save as” and enter the pathname for where you want the policy file to go. The screen will look like Figure 25-4.

Figure 25-4. The Policy Tool utility.

That takes care of reading the contents of sauceboy’s keystore. Now we need to add a policy entry for the precise permission we want to grant. Press the button marked “Add Policy Entry” to bring up the policy entry screen.

The policy entry screen has two text fields at the top, “CodeBase” and “SignedBy.” If we enter a URL in the codebase field, we are saying that the permission applies to code that arrives from that codebase. Thus, you might enter “ http://java.sun.com ” to apply a permission to all applets that you browse on the Sun Java web site. If you leave the field blank, it means the permission you are about to specify applies to all code, regardless of where it comes from.

The second text field “SignedBy” identifies who signed the code. We need to enter the alias that we used to identify the linden certificate when we entered it into the sauceboy keystore. If you look back a couple of pages, you’ll see we just used the string “linden.”

“Code signed by linden” is shorthand for saying,” Code in a class file contained in a JAR file, where the JAR file was signed using the private key corresponding to the public key that appears in a keystore certificate in an entry aliased by linden.” Phew!

You then click the “add permission” button and select the appropriate permission, what it applies to, and the level of access. The permissions are listed back in Table 25-2. The screen resembles Figure 25-5.

Figure 25-5. Setting up security.

The “Target” is the file or directory to which you want to apply the permission. The “Action” is the kind of access: read, write, execute, delete. Finish up by clicking “Done” and saving the file.

Take a look at the policy file, and you will see something like this:

/* AUTOMATICALLY GENERATED ON Sun Nov 15 16:31:02 PST 1998*/
/* DO NOT EDIT */

keystore "file:/home/sauceboy/sauceboystore";

grant signedBy "linden" {
  permission java.io.FilePermission "<<ALL FILES>>", "write";
}; 

By the time this book gets into the hands of readers, more browsers are expected to support configurable applet security. One need is to be able to configure browsers to accept or refuse certain X.509 certificates. You’ll want to be able to tell your browser, “Accept applets that are accompanied by certificates from these five companies, and ask me explicitly about any others.”

appletviewer -J-Djava.security.policy=file:/etc/sauceboy/permit write.html 

Anyone who has had to do “booth duty” at a computer exhibition knows the problem: Software is nebulous stuff, and very hard to demonstrate. Take a compiler for example. You don’t really have anything to show that is going to make people gasp in astonishment. You type a command-line, the compiler runs and creates an object file, and that’s it. The problem is even worse for utility and system administration software. There’s just plain nothing to see.

A software company based in southern California, Syncronys Softcorp, took this concept to the limit (and then took one step further) with SoftRAM95, a bestselling Windows product. An advertisement on page 81 of the December 1995 issue of Wired read:

The trade press named SoftRAM95 as the hottest-selling utility for Windows 95. More than 600,000 people bought SoftRAM95 and Syncronys’s stock price shot up from $.03 a share in March 1995 to $32 a share just five months later. SoftRAM95 works like this in action (see Figure 25-6).

Figure 25-6. SoftRAM95: Just a pretty face.

I don’t mean “SoftRAM95 looks like this picture in a book”— I mean “SoftRAM95 works like this picture in a book. It looks pretty but it does nothing.” The program was on the market for several months and sold hundreds of thousands of copies before word started to get out that the emperor had no clothes.

SoftRAM95 was based on an earlier Syncronys Windows 3.1 program that also did nothing. However, it featured a really slick control panel that reported on the amount of memory present and the extra resources that the software said it was providing. The trade press was initially full of favorable reports, but careful consumers noticed that the dials read the same whether or not the Syncronys libraries were on the system, which tended to cast doubt on whether the control panel was reporting what the system was doing, or what it wanted users to think the system was doing.

The jig only started to unravel well after SoftRAM was a big hit in the market. Three independent tests reported that SoftRAM did not work as advertised, and in fact did not work at all. It did not speed up Windows. It did not double memory. The software did not do anything at all. PC Magazine’s technical editor Larry Seltzer reported, “I’ve never seen a product that was so devoid of value as SoftRAM. After careful testing, we found no evidence that SoftRAM95 performs any of the main functions it claims to perform.”

Amazingly, the product continued to sell in boatloads, and with a list price of $79.95, Syncronys was reluctant to admit that the only effect of the software was a placebo effect. Syncronys’s reseller in Germany actually sued German computer magazine, c’t, which was the first to report that SoftRAM didn’t work as advertised. At first, Syncronys circulated a favorable report done by XXCAL labs, claiming that the report “confirmed that SoftRAM95 effectively doubles Random Access Memory (RAM).” After criticism continued to mount, Syncronys issued a press release in October 1995 that admitted, “RAM compression is not being delivered to the operating system.” Syncronys glossed over the critical fact that the software didn’t even attempt any compression of memory, so of course it couldn’t deliver anything at all to the operating system.

At last the Federal Trade Commission began to ask a few half-hearted questions of Syncronys, which announced in December 1995 that it was recalling SoftRAM and would credit or refund purchasers. Even then Syncronys didn’t give up, and wrote to its distributors saying that it would soon be relaunching SoftRAM and creating a version for the Macintosh. And in June 1996 Syncronys had its lawyers warn Dr. Dobbs Journal over an upcoming review of SoftRAM 95. Dr. Dobbs Journal wasn’t intimidated and went ahead and printed the truth in its August 1996 issue without further ado.

Finally, the FTC brought a complaint against Syncronys. It was settled by Syncronys agreeing “not to make representations about the performance, attributes, benefits, or effectiveness of SoftRAM, SoftRAM95, or any substantially similar product unless the representations were true and substantiated.” In other words, Syncronys siphoned millions from unwary customers, and got away clean with a slap on the wrist. In a news story reporting the consent decree, Syncronys CEO Rainer Poertner was quoted as saying that SoftRAM for Windows 3.x “always worked perfectly.” I suppose it depends on your definition of “perfectly.” While the program perfectly delivered a lot of cash into Syncronys’s bank account, it certainly didn’t deliver the memory benefits claimed for it.

Syncronys had perhaps the biggest of the best-selling programs that do nothing, but they are by no means alone in the field. Right now there is a vendor hawking “security” software that supposedly safeguards your system against hostile Java applets. They’re using all the same tools to keep the software on the market: lawyers letters, favorable test reports from “independent” labs, press releases, and so on. And the software has just as much use. Hostile Java applets don’t exist; because of the security measures in place from the first Java release, about the worst that a cracker can do in a Java applet is a “denial of service” attack—chew up CPU cycles that don’t belong to him.

Jerry Seinfeld used to take great pride in his comedy show, saying it was “a show about nothing.” Sometimes life does imitate art. Syncronys had a best-selling Windows product that bore the “Designed for Windows 95” logo that did absolutely nothing.

Addendum: In the summer of 2000, Syncronys’s stock nose-dived to less than one-tenth of a cent. When I last checked their website, it had been taken over by an adult content operator. I was curious to find out who. A reverse DNS look-up showed it was being operated from an address in Yerevan, Armenia. Why am I not surprised?

Applied Cryptography, 2nd edition by Bruce Schneier. (John Wiley and Sons, New York, NY, 1996), ISBN 0-471-11709-9 (paperback).

A wonderful book. The author has gone to considerable trouble to explain a complicated mathematical topic so that any programmer can follow it. More technical books should be written like it.

There is more information on Java Security at java.sun.com/security, which is Sun’s Java security home page.

The Java documentation has some information which, if you installed the documentation, will be at file:/c:/jdk1.4/docs/guide/security/index.html.