Signature Timestamp Support
for J2SE 5.0

IMPORTANT NOTE: The APIs and features described in this document are SUBJECT TO CHANGE.

Introduction

This document describes the enhancements that have been added in J2SE 5.0 to support signature timestamps. Please send feedback, especially those related to these new features, to java-security@sun.com.

Prior to J2SE 5.0, the signature generated by jarsigner contained no information about w hen the signature was generated. With no other information available, systems/deployers (including users of the Java Plug-in) often based their validity assessment of a signed JAR file on the validity of the signing certificate. When the signing certificate expires, systems/deployers conclude that the signature, and hence, the JAR file, has expired. Because signing certificates typically expire annually, this caused customers significant problems by forcing them to re-sign deployed JAR files annually.

Starting in J2SE 5.0, jarsigner can generate signatures that include a timestamp, thus enabling systems/deployer (including Java Plug-in) to check whether the JAR file was signed while the signing certificate was still valid. In addition, APIs were added in J2SE 5.0 to allow applications to obtain the timestamp information.

The following time-of-signing enhancements and additions are supported in version 5.0 of the Java 2 platform:

Jarsigner Enhancements

The jarsigner tool can now generate and store a signature timestamp when signing a JAR file. In addition, jarsigner supports alternative signing mechanisms. This behavior is optional and is controlled by the user at the time of signing through the options described below.

Jarsigner Timestamp Options

The following options were added to the jarsigner tool to support signature timestamps:

-tsa url

If "-tsa http://example.tsa.url" appears on the command line when signing a JAR file then a timestamp is generated for the signature. The URL, http://example.tsa.url, identifies the location of the Time Stamping Authority (TSA). It overrides any URL found via the -tsacert option. The -tsa option does not require the TSA's public key certificate to be present in the keystore.

To generate the timestamp, jarsigner communicates with the TSA using the Time-Stamp Protocol (TSP) defined in RFC 3161. If successful, the timestamp token returned by the TSA is stored along with the signature in the signature block file.

-tsacert alias

If "-tsacert alias" appears on the command line when signing a JAR file then a timestamp is generated for the signature. The alias identifies the TSA's public key certificate in the keystore that is currently in effect. The entry's certificate is examined for a Subject Information Access extension that contains a URL identifying the location of the TSA.

The TSA's public key certificate must be present in the keystore when using -tsacert.

Alternative Signing Options

Specifying an Alternative Signing Mechanism

-altsigner class
Specifies that an alternative signing mechanism be used. The fully-qualified class name identifies a class file that extends the com.sun.jarsigner.ContentSigner abstract class. The path to this class file is defined by the -altsignerpath option. If the -altsigner option is used, jarsigner uses the signing mechanism provided by the specified class. Otherwise, jarsigner uses its default signing mechanism.

For example, to use the signing mechanism provided by a class named com.sun.sun.jarsigner.AuthSigner, use the jarsigner option "-altsigner com.sun.jarsigner.AuthSigner"

Specifying Path to Alternative Signing Mechanism

-altsignerpath classpathlist
Specifies the path to the class file (the class file name is specified with the -altsigner option described above) and any JAR files it depends on. If the class file is in a JAR file, then this specifies the path to that JAR file, as shown in the example below.

An absolute path or a path relative to the current directory may be specified. If classpathlist contains multiple paths or JAR files, they should be separated with a colon (:) on Solaris and a semi-colon (;) on Windows. This option is not necessary if the class is already in the search path.

Example of specifying the path to a jar file that contains the class file:

-altsignerpath /home/user/lib/authsigner.jar

Note that the JAR file name is included.

Example of specifying the path to the jar file that contains the class file:

-altsignerpath /home/user/classes/com/sun/tools/jarsigner/

Note that the JAR file name is omitted.

Java Plug-in Enhancements

 In J2SE 5.0, the Java Plug-in was enhanced to check signature timestamps (if available) when validating JAR files. The Java Plug-in will no longer present a dialog when it encounters an expired or revoked certificate when validating a signed jar, provided that the signature timestamp confirms that the signature was generated prior to the expiration or revocation date.

The TSA's certificate must be available from the Plug-in's keystore or certificate stores when the Plug-in is validating a JAR file containing a signature timestamp.

The Plugin reverts to 1.4.x behavior if the signature does not contain a timestamp.

API Enhancements

The security and JAR APIs were enhanced to enable applications to access timestamp information.

Two new classes were added to the java.security package. These classes are CodeSigner, which maintains information associated with a signer, and Timestamp, which represents information associated with a signature timestamp.

New methods were added to the java.security.CodeSource class and java.util.jar.JarEntry class to allow access to this new, optional information.