# Signing Applets Using RSA Certificates

This chapter covers the following topics:

- Introduction
- Signing Tools
- Getting RSA Certificates
  - Getting Certificates With Jarsigner
  - Getting Certificates With Netscape Signing Tool
- Bundling Java Applets as JAR Files
- Signing Java Applets
  - Signing Applets Using `jarsigner`
  - Signing Applets Using Netscape Signing Tool
- Converting Old Netscape-Signed Applets
- Microsoft Authenticode
- Common Problems

## 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.

Signing applets requires the following :

1. Signing tools
2. An RSA keypair and a certificate chain for the public keys
3. The applet and all its class files, bundled as JAR files

## Signing Tools

Java Plug-in supports the format of the following tools for signing applets using RSA:

1. `jarsigner`—Signing tool shipped as part of the Java SDK
2. `signtool`—Signing tool provided by Netscape for signing applets in Navigator/Communicator. For more details on the sign tool and downloading it read the page at http://www.mozilla.org/projects/security/pki/nss/tools.

## 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:

1. 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:\Program Files\Java\jdk1.6.0\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): *********

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

       C:\Program Files\Java\jdk1.6.0\bin\keytool -certreq -alias MyCert

       Enter keystore password:  *********
       -----BEGIN NEW CERTIFICATE REQUEST-----
       MIIBtjCCAR8CAQAwdjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRIwE
       AYDVQQHEwlDdXBlcnRpbm8xGTAXBgNVBAoTEFN1biBNaWNyb3N5c3RlbX
       MxFjAUBgNVBAsTDUphdmEgU29mdHdhcmUxEzARBgNVBAMTClN0YW5sZXk
       gSG8wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALTgU8PovA4y59eb
       oPjY65BwCSc/zPqtOZKJlaW4WP+UhmebE+T2Mho7P5zXjGf7elo3tV5uI
       3vzgGfnhgpf73EoMow8EJhly4w/YsXKqeJEqqvNogzAD+qUv7Ld6dLOv0
       CO5qvpmBAO6mfaI1XAgx/4xU/6009jVQe0TgIoocB5AgMBAAGgADANBgk
       qhkiG9w0BAQQFAAOBgQAWmLrkifKiUYtd4ykhBtPWSwW/IKkgyfIuNMML
       dF1DH8neSnXf3ZLI32f2yXvs7u3/xn6chnTXh4HYCJoGYOAbB3WNbAoQR
       i6u6TLLOvgv9pMNUo6v1qB0xly1faizjimVYBwLhOenkA3Bw7S8UIVfdv
       84cO9dFUGcr/Pfrl3GtQ==
       -----END NEW CERTIFICATE REQUEST-----

3. The CA (e.g., VeriSign/Thawte) will send you a certificate reply (chain) by email. Copy the chain and store it in a file. Use "`keytool -import`" to import the chain into your keystore. E.g.,

       C:\Program Files\Java\jdk1.6.0\bin\keytool -import -alias MyCert -file VSSStanleyNew.cer

4. 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 SE SDK, can be used for that purpose. E.g.,

    C:\Program Files\Java\jdk1.6.0\bin\jar cvf C:\TestApplet.jar .
    added manifest
    adding: TestApplet.class (in = 94208) (out= 20103)(deflated 78%)
    adding: TestHelper.class (in = 16384) (out= 779)(deflated 95%)

This example creates a JAR file C:\TestApplet.jar, and it contains all the files under the current directory and its sub-directories.

After the JAR file is created, you should verify its content using the `jar` tool again, e.g.,

    C:\Program Files\Java\jdk1.6.0\bin\jar tvf TestApplet.jar
         0 Mon Mar 06 18:02:54 PST 2000 META-INF/
        68 Mon Mar 06 18:02:54 PST 2000 META-INF/MANIFEST.MF
     94208 Wed Mar 10 11:48:52 PST 2000 TestApplet.class
     16384 Wed Mar 10 11:48:52 PST 2000 TestHelper.class

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:

1. 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.,

       C:\Program Files\Java\jdk1.6.0\bin\jarsigner C:\TestApplet.jar MyCert
       Enter Passphrase for keystore: ********

2. Use "`jarsigner -verify -verbose -certs`" to verify the jar files

       C:\Program Files\Java\jdk1.6.0\bin\jarsigner -verify -verbose
                       -certs d:\TestApplet.jar

                245 Wed Mar 10 11:48:52 PST 2000 META-INF/manifest.mf
                187 Wed Mar 10 11:48:52 PST 2000 META-INF/MYCERT.SF
                968 Wed Mar 10 11:48:52 PST 2000 META-INF/MYCERT.RSA
       smk      943 Wed Mar 10 11:48:52 PST 2000 TestApplet.class
       smk      163 Wed Mar 10 11:48:52 PST 2000 TestHelper.class

             X.509, CN=XXXXXXX YYY, OU=Java Software,
                       O=Sun Microsystems, L=Cupertino,
                       ST=CA, C=US (mycert)
             X.509, CN=Sun Microsystems, OU=Java Plug-in QA,
                       O=Sun Microsystems, L=Cupertino, ST=CA, C=US
             X.509, EmailAddress=server-certs@thawte.com,
                       CN=Thawte Server CA, OU=Certification
                       Services Division, O=Thawte Consulting cc,
                       L=Cape Town, ST=Western Cape, C=ZA

         s = signature was verified
         m = entry is listed in manifest
         k = at least one certificate was found in keystore
         i = at least one certificate was found in identity scope

       jar verified.

3. Your applet has been signed properly. You are now ready to deploy your RSA signed applet.

### Signing Applets Using Netscape Signing Tool

To sign applets using signtool, follow these steps:

1. Use "`signtool -L`" to determine the certificate nickname that should be used in signing. E.g.,

       C:\signtool13WINNT40\signtool -L -d a:\cert
       using certificate directory: a:\cert

       S Certificates
       - ------------
         AT&T Certificate Services
         Thawte Personal Premium CA
         GTE CyberTrust Secure Server CA
         Verisign/RSA Commercial CA
         AT&T Directory Services
         BelSign Secure Server CA
         BelSign Class 1 CA
         GTIS/PWGSC, Canada Gov. Web CA
         Thawte Personal Freemail CA
         Thawte Server CA
         GTIS/PWGSC, Canada Gov. Secure CA
         MCI Mall CA
         VeriSign Class 3 Primary CA
         VeriSign Class 4 Primary CA
         KEYWITNESS, Canada CA
         BelSign Class 2 CA
         BelSign Object Publishing CA
       * Sun Microsystems, Inc.
         VeriSign Class 3 CA - Commercial Content/Software
                               Publisher - VeriSign, Inc.
         Verisign/RSA Secure Server CA
         VeriSign Class 1 Primary CA
         BBN Certificate Services CA Root 1
         Thawte Personal Basic CA
       * Sun Microsystems, Inc.'s VeriSign, Inc. ID
         CertiSign BR
         VeriSign Class 2 Primary CA
         Canada Post Corporation CA
         Integrion CA
         IBM World Registry CA
         BelSign Class 3 CA
         Uptime Group Plc. Class 1 CA
         Uptime Group Plc. Class 2 CA
         Thawte Premium Server CA
         Uptime Group Plc. Class 3 CA
         GTE CyberTrust Root CA
         Uptime Group Plc. Class 4 CA
       - ------------

       Certificates that can be used to sign objects
       have *'s to their left.

2. Create an empty directory. E.g.,

       mkdir signdir

3. Put all the applet class files into it.
4. Use "`signtool -Z`" to sign the applet. E.g.,

       C:\signtool13>signtool -k "Sun Microsystems, Inc.'s VeriSign, Inc. ID"
               -d a:\cert -Z c:\TestApplet.jar c:\signdir
       using certificate directory: a:\cert
       Generating c:\signdir/META-INF/manifest.mf file..
       --> TestApplet.class
       adding c:\signdir/TestApplet.class to c:\TestApplet.jar...
               (deflated 57%)
       --> TestHelper.class
       adding c:\signdir/TestHelper.class to c:\TestApplet.jar...
               (deflated 43%)
       Generating zigbert.sf file..
       adding c:\signdir/META-INF/manifest.mf to c:\TestApplet.jar...
               (deflated 44%)
       adding c:\signdir/META-INF/zigbert.sf to c:\TestApplet.jar...
               (deflated 46%)
       adding c:\signdir/META-INF/zigbert.rsa to c:\TestApplet.jar...
               (deflated 40%)
       tree "c:\signdir" signed successfully

5. Use "`signtool -w`" to verify the archive. E.g.,

       C:\signtool13>signtool -w c:\TestApplet.jar -d a:\cert
       using certificate directory: a:\cert

       Signer information:

       nickname: Sun Microsystems, Inc.'s VeriSign, Inc. ID
       subject name: C=US, ST=CA, L=Palo Alto, OU=Java Software,
               CN=Sun Microsystems, OU=Digital ID Class 3 - Netscape
       Object Signing, OU="www.verisign.com/repository/RPA Incorp.
               by Ref.,LIAB.LTD(c)99", OU=VeriSign Trust Network,
               O="VeriSign, Inc."
       issuer name: CN=VeriSign Class 3 CA - Commercial Content/Software
               Publisher, OU="www.verisign.com/repository/RPA Incorp.
               by Ref.,LIAB.LTD(c)98", OU=VeriSign Trust Network,
               O="VeriSign, Inc."

Your applet has been signed properly. You are now ready to deploy your RSA signed applet. See How to Deploy RSA Signed Applets for deployment information.

## 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:

1. Comment or remove all `netscape.security.*` related statements from the Java applet.
2. Compile and archive the applet as a JAR file.
3. 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.