Using the Netscape Object Signing Tool

Netscape Object Signing Tool 1.1

<APPLET CODE=”somefile.class”

ARCHIVE=”jarfile.jar”>

Where somefile.class is the class in the JAR file where execution should begin, and jarfile.jar is the URL of the JAR file. The tool is available for most operating systems. While, as of this writing, version 1.0 is still available for download, we recommend that you use version 1.1.

After the download is complete, unpack the archive file in a directory. Included are three files: readme.txt, license.txt, and signtool. To make signing objects easier, put the directory that contains signtool in your PATH environment variable, as per your operating system. For example, a Windows 95 user who unpacked the tool to C:nos would run the following line (and then add it to the autoexec.bat file):

PATH=%PATH%;C:nos

Before attempting to sign anything, check to see if signtool is able to locate the Certificate that will be used to sign objects. UNIX flavors of signtool look for Certificates in the $HOME/.netscape. If your local Netscape files are kept somewhere different, or you are using the Win32 version, signtool must be explicitly told the path to the Certificates. This is done with the -d flag. On Win32, this path is commonly c:Program FilesNetscapeUsersname where name is the name of your Netscape Profile. To verify that your signing Certificate was installed properly run:

signtool -l

or, if your certificate cannot be found,

signtool -d”<path to certificates>” -l

For example, if your certificates were stored in C:certs, you would type:

signtool

-d”C:certs” -l

If your Certificate still does not appear in the listing, verify that the Certificate is installed in Netscape properly. (See the instructions above). If all else fails, check with Netscape and the issuing Certificate Authority. Make note of the full name of your Certificate, as it appears in the listing. This will be needed when it comes time to sign.

Create a directory in which to put all the class files for the Applet you wish to sign. Once all the class files that make up the Applet are in the right place, the signtool program can create a signed JAR file in one step. Navigate into the directory containing the soon-to-be signed classes. To sign the classes and create a JAR file in one step, issue the command:

signtool -d”” -k”“
 -e “.class” -Z myjar.jar

If your Communicator Certificate Database is password protected, signtool will prompt for the password before signing the classes. The “.” at the end of the command should be the last thing to appear. It specifies that the signing should begin in the current working directory. The signtool command recursively signs files by default. To keep the tool from recursing through directories, add –norecurse to the command line.

Here’s a brief explanation of the flags used in the previous example, as well as some of the other more useful flags for signing applets:

• -k “certificate name”: Specifies the certificate with which you would like to sign. This flag is necessary when signing an applet. The certificate name should be the entire name of the certificate as it appeared as the output of signtool -l. Since the certificate name is likely to have spaces in it, make sure you place it in quotes, otherwise the signing will fail.
• -e”.extension”: specifies the file extensions to sign. If you don’t include this flag, the tool will sign all files, as opposed to the example above, which uses this flag to sign .class files only.
• -x”name”: Allows you to sign all files except a particular file or directory. An example where this might be useful is when you are using an untrusted library in your applet. You probably will not want to vouch for code you did not write with your signature!
• -Z”jarfile”: specifies the name of the JAR file to create. If you omit this option, you will have to JAR everything up yourself.

When the JAR file is created, signtool can be used to test the validity of the signatures. This is done by issuing the command:

signtool

-d”<path to certificate>” -v myjar.jar

Signtool will list the contents of the JAR and verify that they have been signed, and that they have not been tampered with since the signature was created. You may also check to see who signed the JAR file:

signtool -d”<path to certificate>” -w myjar.jar

Signtool can be used to sign anything, not just Java files. In fact, it can extract JavaScript from HTML files, and sign just the JavaScript. However, that functionality is outside the scope of this article.

Adding capabilities to your classes

The special privileges an applet can request are called capabilities by Netscape. (Note: Though Netscape and some other vendors use the term “capabilities” to refer to this system, this usage clashes with the use of “capability” as a technical term in the security literature.) Predictably, no two browsers support flexible privileges in quite the same way, so privilege-management code will only work with one browser. (So much for “write once, run anywhere!”) As a result, while Netscape keeps its own internal version of these classes, in order to actually compile and test an applet that can request them, you must download them.

Put the zip file in your CLASSPATH. Now you will be able to develop code that requests extra privileges in Netscape. Note that you should not include these classes with your applet; the Netscape browser running on the remote machine will use its internal version of the classes.

The capabilities library provides a class called PrivilegeManager that handles requests from the program to turn on and off privileges. When the first request to enable a certain privilege is made, PrivilegeManager prompts the browser’s user, showing the certificate used to sign the code requesting the privilege and asking whether the privilege should be granted. If the user agrees to grant the privilege, the privilege is granted for the lifetime of the applet. However, once the applet has obtained a privilege, it can turn the privilege off and on at its discretion.

To request that a particular privilege be enabled, you use the static method enablePrivilege() of class netscape.security.PrivilegeManager. The method takes a single String argument, which is the name of the privilege to enable. Some useful privileges include:

• UniversalFileAccess: This privilege gives the applet the ability to access any file available to the user. It will enable the applet to call most things in the java.io package related to file manipulation. This privilege is a superset of other file manipulation privileges that may be requested individually, such as UniversalFileRead, UniversalFileWrite and UniversalFileDelete.
• UniversalSendMail: This privilege allows the applet to send e-mail on behalf of the user.
• UniversalExitAccess: Allows the Java applet to shut down the Netscape browser.
• UniversalExecAccess: Enables the applet to run programs already stored on the user’s local computer.
• PrivateRegistryAccess: Grants access to application-specific portions of the computer’s registry (Win32 only).

The simplest privilege an applet can request is permission to read System Properties, which include the user’s login name. Here is an example applet which requests privilege to read the user’s name:

import netscape.security.PrivilegeManager;

import netscape.security.ForbiddenTargetException;

import java.applet.Applet;

public class CapabilitiesExample extends Applet {

  public void init() {

    String username = “user: “;

    try {

      PrivilegeManager.enablePrivilege(“UniversalPropertyRead”);

      username += System.getProperty(“user.name”);

    } catch (ForbiddenTargetException fte) {

      username += “access denied”;

    }

    showStatus(username);

  }

}

A call to enablePrivilege will throw an exception that the applet must catch if the user decides not to grant the privilege specified in the call. Thus, the applet must be prepared to catch instances of netscape.security.ForbiddenTargetException. When a privilege is enabled, it does not have to stay enabled for the entire execution of the applet. There are a couple of ways to turn privileges off (which is always a good idea). First, when the method that calls enablePrivilege returns, the privilege will automatically be disabled. As a result, you should not use a helper method to enable a privilege, because once execution returns from that method, the privilege will no longer be enabled. Second, you can call revertPrivilege, which also takes the name of a privilege as an argument. Finally, you can call disablePrivilege, which turns off a particular privilege. In no case will the granting of the privilege be revoked; the applet can turn the privilege back on by simply calling enablePrivilege again.

Next week, we’ll examine the code signing tools Sun ships in the JDK 1.2.

Resources

• The Java Security Hotlist
• Securing Java: Getting Down to Business with Mobile Code by Gary McGraw and Ed Felten
• Reliable Software Technologies

John Viega is a research associate at Reliable Software Technologies, in Sterling, Va. He holds an M.S. in Computer Science from the University of Virginia. He developed and maintains Mailman, the Gnu mailing list manager. His research interests include software assurance, programming languages, and object-oriented systems.

Tom O’Connor is a software engineer in the research division at Reliable Software Technologies. His interests are computer security and object-oriented software development.

Portions of this article will appear as an appendix in the forthcoming book Securing Java: Getting Down to Business with Mobile Code (John Wiley & Sons, 1998), the second edition of McGraw and Felten’s book, Java Security: Hostile Applets, Holes, & Antidotes.