|
|
|
|
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:
- Signing tools.
- An RSA keypair and a certificate chain for its public keys.
- 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:
- Jarsigner -- a tool that is shipped as part of the Java 2
Software Development Kit.
- 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:
-
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,
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-----
- 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
- 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:
-
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: ********
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.
- 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:
-
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.
- Create an empty directory. e.g.
mkdir signdir
- Put all the applet class files into it.
- 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
-
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, and you are now ready to
deploy your RSA signd applet.
Deploying RSA signed applets
To deploy RSA signed applets:
- Reference the JAR from the HTML page using ARCHIVE=xyz.jar in the
EMBED/OBJECT tag.
- 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:
- 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.
- 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.
- 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.
- 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.
|