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.
- Make sure you have built PersonalJava with INCLUDECODESIGNING=true.
- Move to the bin directory.
- 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.
- 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
- Import Duke's certificate into your Identity Database. This step associates
the identity "Duke" with the certificate Duke.x509.
% pjavakey -ic Duke Duke.x509
- 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.
- Create an identity:
% javakey -cs "duke" true
- Generate DSA key pair for the identity.
% javakey -gk "duke" DSA 512 duke_pub duke_priv
- 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
- 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
- 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
- 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.