Java Technology Home Page
Downloads, APIs, Documentation
Java Developer Connection
Docs, Tutorials, Tech Articles, Training
Online Support
Community Discussion
News & Events from Everywhere
Products from Everywhere
How Java Technology is Used Worldwide

A-Z Index

The Source for Java Technology

Step-by-step guide of signing applets using RSA certificate

Since Java Plugin 1.2.2, RSA signed applets has been supported to make deploying signed applets much easier. However, signing applets through RSA is still remained a mystery to most novice applet developers, and it prevents them to fully take advantages of this features of Java Plug-in. This document outlines the step-by-step guide of signing applets using RSA certificate, so novice applet developers will be able to sign their applets in Java Plug-in without fully understand all the complex security related terminalogy.

To sign an applet, several things are needed:

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

Signing tools

Two types of signing tools are currently supported in Java Plug-in to sign RSA applets in:

  1. Jarsigner -- a tool that is shipped as part of the Java 2 Software Development Kit.
  2. Netscape Signing Tool -- a tool that is provided by Netscape for signing applets in Navigator/Communicator. The latest version of the signing tool is 1.3, and it may be download from http://developer.netscape.com/software/signedobj/jarpack.html. Please notice that Netscape no longer make older version of the signing tool available for download.

RSA certificates

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

Jarsigner

As of the time this document was written, we have demonstrated interoperability of Jarsigner with VeriSign and Thawte. To use jarsigner to sign applets using RSA certificate, you should obtain the Sun Java Signing certificate from VeriSign, or Java Code Signing certificate from Thawte, or similar certificate from other CAs. During the process of certificate enrollment, you will be asked to provide the certificate signing request (CSR). To generate the CSR, these are the steps you should follow:

  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:\>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): *********
    
  2. Use "keytool -certreq" to generate a certification signing request. Copy the result and paste it into the VeriSign/Thawte webform. For example, 
    C:\>C:\jdk1.3\bin\keytool -certreq -alias MyCert
    Enter keystore password:  *********
    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIIBtjCCAR8CAQAwdjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRIwEAYDVQQHEwlDdXBlcnRp
    bm8xGTAXBgNVBAoTEFN1biBNaWNyb3N5c3RlbXMxFjAUBgNVBAsTDUphdmEgU29mdHdhcmUxEzAR
    BgNVBAMTClN0YW5sZXkgSG8wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALTgU8PovA4y59eb
    oPjY65BwCSc/zPqtOZKJlaW4WP+UhmebE+T2Mho7P5zXjGf7elo3tV5uI3vzgGfnhgpf73EoMow8
    EJhly4w/YsXKqeJEqqvNogzAD+qUv7Ld6dLOv0CO5qvpmBAO6mfaI1XAgx/4xU/6009jVQe0TgIo
    ocB5AgMBAAGgADANBgkqhkiG9w0BAQQFAAOBgQAWmLrkifKiUYtd4ykhBtPWSwW/IKkgyfIuNMML
    dF1DH8neSnXf3ZLI32f2yXvs7u3/xn6chnTXh4HYCJoGYOAbB3WNbAoQRi6u6TLLOvgv9pMNUo6v
    1qB0xly1faizjimVYBwLhOenkA3Bw7S8UIVfdv84cO9dFUGcr/Pfrl3GtQ==
    -----END NEW CERTIFICATE REQUEST-----
    
  3. CAs (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:\>C:\jdk1.3\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 the jarsigner to sign your JAR file.

Note that you must the *same* alias name for all the above steps (or no alias name, in which case the alias name defaults to "mykey").

Netscape Signing Tool

As of the time this document was written, most CAs (e.g. VeriSign/Thawte) are known to support Netscape Signing Tool. To use Netscape Signing Tool to sign applets using RSA certificate, you should obtain the Netscape Object Signing certificate from Verisign, or Netscape Object Signing certificate from Thawte, or similar certificate from other CAs. During the process of enrollment, you will be asked about your personal/company information because the CA will need to verify your information before the certificate is issued. 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

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


Java Applets

To sign applets with RSA certificates with Jarsigner, the applets must be bundled as JAR files. Jar tool is provided as part of the Java 2 Software Development Kit. For example,

C:>C:\jdk1.3\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 create 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 Jar tool again. e.g.

C:>C:\jdk1.3\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 ensure the class files are stored with the proper path within the JAR file.

To sign applets with RSA certificates with Netscape Signing Tool, the applets must be placed in a directory, and Netscape Signing Tool will bundle it as JAR file after the process of signing.


Signing applets

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

Signing applets using jarsigner

To sign applets using jarsigner, these are the steps you should follow:

  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:\>C:\jdk1.3\bin\jarsigner C:\TestApplet.jar MyCert
    Enter Passphrase for keystore: ********
    
  2. Use "jarsigner -verify -verbose -certs" to verify the jar files
    C:>C:\jdk1.3\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 Co
    sulting 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, and you are now ready to deploy your RSA signd applet.

 

Signing applets using Netscape Signing Tool

To sign applets using signtool, these are the steps you should follow:

  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."
    
  6. Your applet has been signed properly, and you are now ready to deploy your RSA signd applet.

 

Deploying RSA signed applets

To deploy RSA signed applets:

  1. Reference the JAR from the HTML page using ARCHIVE=xyz.jar in the EMBED/OBJECT tag.
  2. Put the JAR file and the HTML page on the web server.

When users of Java Plug-in encounter an RSA signed applet, the Plug-in will verify that the applet is correctly signed, and that the RSA certificate chain and the root CA are valid. If these are all valid, the Plug-in will pop-up a security dialog that tells the user who signed the applet and provides four options:

  1. Grant always: If selected, the applet will be granted "AllPermission". Any signed applet signed using the same certificate will be trusted automatically in the future, and no security dialog will pop up again when this certificate is encountered again. This decision can be changed from the Java Plug-in Control Panel.
  2. Grant this session: If selected, the applet will be granted "AllPermission". Any signed applet signed using the same certificate will be trusted automatically within the same browser session.
  3. Deny: If selected, the applet will be granted the applicable permissions from the security policy of the Java runtime. By default, the permissions granted would be those for untrusted applets.
  4. More Info: If selected, users can examine the attributes of each certificate in the certificate chain in the JAR file.

Once the user selects the options from the security dialog, the applet will be run in the corresponding security context. Please notice that all these decisions are determined on the fly, and no preconfiguration is required.


Common Problems

  • If the JAR file is not signed properly, or 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 will not pop up the security dialog. The applet will be treated as unsigned.
  • The Netscape Signing Tool very picky 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 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 JAR files regardless of whether their MANIFEST is at the beginning or at the end. To workaround this problem when using Netscape Signing Tool, you should generate the JAR file and sign it through the tool itself.
  • Java Plug-in 1.2.2 supports signed applets signed using Netscape Signing Tool 1.2. However, Java Plug-in 1.2.2 fails to authenticate any signed JAR files generated by Netscape Signing Tool 1.3, due to changes in the signature block file of those JAR files. Note that interoperability with Netscape Signing Tool 1.3 has been restored in Java Plug-in 1.3, which also interoperates with Netscape Signing Tool 1.2.


[ This page was updated: 02-Dec-99 ]

Products & APIs | Developer Connection | Docs & Training | Support
Community Discussion | Industry News | Solutions Marketplace | Case Studies
Glossary - Applets - Tutorial - Employment - Business & Licensing - Java Store - Java in the Real World
Feedback | Map | A-Z Index

For more information on Java technology
and other software from Sun Microsystems, call:
(800) 786-7638
Outside the U.S. and Canada, dial your country's AT&T Direct Access Number first.
Sun Microsystems, Inc.
Copyright ?995-2000 Sun Microsystems, Inc.
All Rights Reserved. Terms of Use. Privacy Policy.