Introduction

RSA-signed applets are supported to make deployment of signed applets easier.
However, signing applets through RSA is still difficult for most novice applet
developers and prevents them from taking full advantage of this Java Plug-in
feature. This document provides step-by-step instructions for signing applets
using RSA certificates, allowing novice applet developers to sign their applets
without having to wade through the many complex security issues involved.

To sign an applet, several things are required:

Signing tools.

An RSA keypair and a certificate chain for the public keys.

The applet and all its class files, bundled as JAR files.

Signing Tools

For RSA signing of applets, two types of signing tools are currently supported
in Java Plug-in:

Jarsignera tool that is shipped as part of the Java 2 SDK.
Command is jarsigner ...

Netscape Signing Toola tool that is provided by Netscape for
signing applets in Navigator/Communicator. The latest version of the signing
tool may be download from http://developer.netscape.com/software/signedobj/jarpack.html.
(Note that Netscape no longer makes older versions of the signing tool available
for download.) Command is signtool ...

Getting RSA Certificates

RSA certificates may be purchased from a Certificate Authority (CA) that supports
RSA, such as VeriSign and Thawte.
Some CAs, such as VeriSign, implement different protocols for issuing certificates,
depending on the particular signing tool you are using.

Getting Certificates With Jarsigner

Jarsigner is known to work with VeriSign and Thawte certificates and may work
with Certificate Authorties. To use Jarsigner to sign applets using RSA certificates,
obtain the Sun
Java Signing certificate from VeriSign or the Java
Code Signing certificate from Thawteor similar certificates from other
CAs. During the process of certificate enrollment, you will be asked to provide
the certificate signing request (CSR). To generate the CSR, follow these steps:

Use keytool to generate an RSA keypair (using the "-genkey
-keyalg rsa" options). Make sure your distinguished name contains all
the components mandated by VeriSign/Thawte. E.g.,

C:\>C:\jdk1.3\bin\keytool -genkey -keyalg rsa -alias MyCert
Enter keystore password: *********
What is your first and last name?
[Unknown]: XXXXXXX YYY
What is the name of your organizational unit?
[Unknown]: Java Software
What is the name of your organization?
[Unknown]: Sun Microsystems
What is the name of your City or Locality?
[Unknown]: Cupertino
What is the name of your State or Province?
[Unknown]: CA
What is the two-letter country code for this unit?
[Unknown]: US
Is <CN=XXXXXXX YYY, OU=Java Software, O=Sun Microsystems,
L=Cupertino, ST=CA, C=US> correct?
[no]: yes
Enter key password for <MyCert>
(RETURN if same as keystore password): *********

Use "keytool -certreq" to generate a certification signing
request. Copy the result and paste it into the VeriSign/Thawte webform. For
example,

Your RSA certificate and its supporting chain have been validated and imported
into your keystore. You are now ready to use jarsigner to sign
your JAR file.

Note

You must use the same alias name for all the above stepsor no
alias name, in which case the alias name defaults to "mykey".

Getting Certificates With Netscape Signing
Tool

Most CAs (e.g., VeriSign/Thawte) support Netscape Signing Tool. To use the
Netscape Signing Tool to sign applets using RSA certificates, obtain the Netscape
Object Signing certificate from Verisign or the Netscape
Object Signing certificate from Thawteor similar certificates from
other CAs. During the process of enrollment, you will be asked for personal/company
information, since the CA will need to verify your identity before issuing a
certificate. This process may take from several hours to several days.

Once the RSA certificate is issued, it usually consists of three files:

cert7.db

key3.db

secmod.db

Depending on the CA, the certificate may be issued and stored on a floppy
diskette, or it may be stored directly in the security modules of Netscape Navigator/Communicator.
Once you have the certificate, you are ready to use the Netscape Signing Tool
to sign your JAR file.

Bundling Java Applets as JAR Files

To use Jarsigner to sign applets with RSA certificates, the applets must be
bundled as JAR files. The Jar tool (command jar ...), which comes
wiht the Java 2 SDK, can be used for that purpose. E.g.,

This ensures that the class files are stored with the proper path within the JAR
file.

To sign an applet with an RSA certificate using the Netscape Signing Tool,
the applet must be placed in a directory, e.g., C:\signdir. The
Netscape Signing Tool will bundle it as JAR file after the signing process.

Signing Java Applets

Once you have the RSA certificates, the signing tool and the applet's JAR
files, you are ready to sign the applets.

Signing applets using jarsigner

To sign applets using jarsigner, follow these steps:

Use jarsigner to sign the JAR file, using the RSA credentials
in your keystore that were generated in the previous steps. Make sure the
same alias name is specified. E.g.,

Converting Old Netscape-Signed Applets

Existing RSA signed applets designed for Netscape may use Netscape-specific
security APIs. These Netscape-specific APIs are not supported in Java Plug-in.
Instead, the Plug-in supports the standard Java security APIs in both Netscape
Navigator and Internet Explorer.

To migrate Netscape-signed applets using the Netscape security APIs to run
in Java Plug-in:

Comment or remove all netscape.security.* related
statements from the Java applet.

Compile and archive the applet as a JAR file.

Re-sign the JAR file using Object Signing.

This ensures that an RSA signed applet will run in both Netscape Navigator
and Internet Explorer with Java Plug-in.

Microsoft Authenticode

Authenticode is a proprietary signing technology used in Microsoft Internet Explorer
on Win32 for supporting signed applets in IE's JVM. Authenticode is not supported
in Java Plug-in. Instead, the Java Plug-in supports use of RSA signed applets
in both IE and Netscape.

Common Problems

If the JAR file is not signed properly, if the RSA certificate has expired,
or if the RSA certificate is a self-generated, self-signed certificate, Java
Plug-in may fail silently and not pop up the security dialog. The applet will
be treated as unsigned.

The Netscape Signing Tool is very particular about JAR file format. In Netscape
Signing Tool, it expects the MANIFEST file to be at the end of the JAR file,
whereas Jarsigner puts it at the beginning. The standard does not mandate
where the MANIFEST file should be in the JAR file. Therefore, if you create
a JAR file using Jar tool, the Netscape Signing Tool may complain about "Invalid
Jar File Format". On the other hand, Jarsigner is not picky; it can verify
a JAR file regardless of whether its MANIFEST file is located at the beginning
or the end. To avoid this problem when using Netscape Signing Tool, you should
both generate and sign the JAR file through the Netscape Signing Tool.