PersonalJava(TM) Code Signing


Java(tm) Platform Security

PersonalJava(tm) 1.0 and 1.1 follow the JDK 1.0 security model. PersonalJava 1.1 also supports optional support for code signing introduced in JDK 1.1. This document covers the optional support for code signing.

In the JDK 1.0 security model Applications can access all available system resources such as the file system, and unlimited network access. Applets have very restricted access to system resources. They can not access the file system and are limited to only being able to open network connections to the host of the .html page they are embedded in.

Trusted Code and Signed Jar Files

PersonalJava 1.1 incorporates optional support for reading signed JAR files. Signing JAR files is a method for providing information to the runtime environment that allows the JAR file's contents to be declared as trusted. The JAR file may contain any type of file needed for the running of an Applet. Examples of files types include class, graphics, audio, and text. Applets that reside in signed JAR files are considered trusted Applets.

A trusted Applet has the same access to system resources that an Application does. To determine if an Applet is trusted the Java platform examines the signature file of the JAR file when the JAR file is downloaded. It compares the signatures to a list contained in the systems Identity Database. If the signatures are verified as trusted then the JAR file's contents are trusted and the Applet can run with access to full system resources.

Building PersonalJava to Support Code Signing

Code signing is a compile time option for PersonalJava. To build a version of PersonalJava that supports code signing compile with the following option:

INCLUDECODESIGNING=true

If you are running on a win32 platform you must start with a clean build before building for codesigning (nmake clobberall, nmake INCLUDECODESIGNING=true). The Solaris makefiles allow for switching between codesigning and non-codesigning builds incrementally.

Compiling with this option will create the additional classes necessary for code signing to work. This option does not create any additional classes in the java.* packages and thus does not create any public APIs.

pjavakey

pjavakey is a tool to be used by system developers while constructing a PersonalJava based system. pjavakey is based on javakey from the JDK, but has been modified to work with the package structure in PersonalJava. pjavakey supports the full range of features in JDK's javakey, including creating identity databases and signing JAR files.

After a code signing build is completed, pjavakey in located in your tools directory. In the tools directory you will find pjavakey and pjavakey.jar . Both of these files must be present in the same directory to run pjavakey. pjavakey is run against a late version of JDK 1.1 (such as JDK 1.1.5). To run pjavakey set the environment variable JAVA_HOME to point to your installation of JDK, such as in this example from UNIX:

setenv JAVA_HOME /usr/local/jdk1.1.5

Once the JAVA_HOME environment variable has been set, pjavakey can be invoked by typing pjavakey from the command line. Use the -h option to get a list of available actions:

javakey -h

Running Signed Code

Since running signed code does not involve the use of new APIs all that is necessary to run a signed JAR file is to setup the environment correctly. To setup your environment you need to create an Identity Database. Creating and modifying the Identity Database is done with the pjavakey tool. You can not create an Identity Database for PersonalJava using the javakey tool from JDK.

The Identity Database is stored in a file called identitydb.obj. This file resides in your home directory for Solaris systems and in C:\ for Windows systems.

The steps for creating an Identity Database are explained in detail in the document Signed Applet Example on Sun's Java web site. Substitute pjavakey for where this document specifies javakey. What follows is a quick summary of the steps from that document. An example certificate for "Duke" is used.
  1. Make sure you have built PersonalJava with INCLUDECODESIGNING=true.


  2. Move to the bin directory.


  3. Obtain the certificate for the signer of the code you will be trusting. In our example the signer is "Duke" and the certificate is Duke.x509 from Sun's Java web site. Save the certificate in the bin directory as Duke.x509.


  4. Create the identity "Duke" in your Identity Database. This step will also create an Identity Database if one does not already exist. Note: if you have created an Identity Database previously using JDK you must remove it before this step.

    % pjavakey -c Duke true


  5. Import Duke's certificate into your Identity Database. This step associates the identity "Duke" with the certificate Duke.x509.

    % pjavakey -ic Duke Duke.x509


  6. You are now ready to run a signed Applet. There is a test Applet available on Sun's Java web site at: http://java.sun.com/security/signExample/signedWriteFile.html. Run this Applet using the pappletviewer.

    % pappletviewer http://java.sun.com/security/signExample/signedWriteFile.html

    This Applet will open a window, write a file to your tmp directory called "foo" and query the system for the user name. It then announces when it has succeeded. If it the Applet fails it outputs a message saying "caught security exception".

Signing JAR Files

In addition to creating an identity database that allows signed JAR files to be run, pjavakey also can sign JAR files. The functionality of pjavakey and javakey are identical in regards to signing JAR files. JAR files signed with pjavakey can be run by JDK and JAR files signed by javakey can be run by PersonalJava. The ability to sign JAR files was retained in pjavakey for the convenience of the system developer.

A complete explanation of signing JAR files can be found in the document Using Javakey at Sun's Java web site. What follows is a quick run through of the steps needed to sign a JAR file. Once again we will be using the identity "Duke" and the certificate Duke.x509 for this example.

  1. Create an identity:

    % javakey -cs "duke" true


  2. Generate DSA key pair for the identity.

    % javakey -gk "duke" DSA 512 duke_pub duke_priv


  3. Generate a certificate. To do this step you need a certificate directive. A sample certificate directive, cert_directive, is available on Sun's Java web site. Obtain this certificate directive and save it in the bin directory as cert_directive. Serveral modifications need to made to the certificate directive. The fields issuer.name and subject.name have to be set to "Duke" instead of "mrm". The value for the field end.date on the certificate directive has passed, so that field has to be modified to use a date later than the present date.

    % javakey -gc cert_directive


  4. Create a JAR file. A complete description of the jar tool is in JAR Guide on Sun's Java web site. This example creates the JAR file with PhoneServlet.class, but any class file will do.

    % jar cf demo.jar PhoneServlet.class


  5. Sign the JAR file. To sign the file you need a sign directive. A sample sign directive sign_directive is available on Sun's Java web site. Obtain this sign directive and save it in the bin directory as sign_directive.

    % javakey -gs sign_directive demo.jar


  6. The output from the last command will be a file called demo.jar.sig. Rename this file demo.jar.

This JAR file is now ready to be run as trusted code on a system set up to trust "Duke" and Duke's Duke.x509 certificate.

More Resources

There is a good collection of documents on Sun's Java web site that relate to the issues surrounding code signing. Many of the following documents have been referenced above but are repeated here.

http://java.sun.com/security
http://java.sun.com/security/signExample
http://java.sun.com/security/usingJavakey.html
http://java.sun.com/security/policy.html
http://java.sun.com/products/jdk/1.1/docs/tooldocs/solaris/javakey.html
http://java.sun.com/products/jdk/1.1/docs/tooldocs/win32/javakey.html
http://java.sun.com/products/jdk/1.1/docs/guide/jar/jarGuide.html
http://java.sun.com/products/jdk/1.1/docs/tooldocs/solaris/jar.html
http://java.sun.com/products/jdk/1.1/docs/tooldocs/win32/jar.html
http://java.sun.com/products/jdk/1.1/docs/guide/jar/manifest.html

Copyright © 1998 Sun Microsystems, Inc. All Rights Reserved.