• Summary of Process
• Collect Tools
• Set up a directory for signing
• Find Navigator's digital ID database directory
• Find name of your digital ID
• Find password for your digital ID
• Create a .jar signing batch file
• Do the actual signing
• Verify the signed archive
• Install the signed archive
• Possible problems
• Notes

Summary of Process

Make any necessary changes in the applet's code (see Writing code for Netscape Navigator).

Collect the tools you'll need: a digital ID, and signtool. Use signtool from an MS-DOS window in Win95 to create a digital signature for the applet's files and pack all the .class files into a .jar file, preserving directories (but stripping off the beginning of each path). Install the results. Enjoy.

Note: Navigator 3 isn't able to verify signed Java applets, and so can't take advantage of digitally signed applets. Navigator 4 and up can take advantage of digitally signed applets (I've verified this on the Macintosh and under Windows; I expect it is also true on other Navigator platforms).

Collect tools

You'll need two items to do digital signing: a Netscape Object Signing software publishing digital ID, and a DOS program called signtool.exe.

Note: VeriSign is the CA that I used for my certificates. Although it was one of the first, it now has competitors. You can check Netscape's list of CAs which support their products at <https://certs.netscape.com/client.html>, or you can check the Vendors section in the Links page.

To get a digital ID from VeriSign, use Navigator 4.0 or later under Win95 (make sure Java and JavaScript are enabled). Go to <http://www.verisign.com/>. Click "Developer Tools and Code Signing" and click "Buy Now" next to "Digital ID For Netscape Object Signing". Follow the directions for enrolling for a Class 3 software publishing ID.

Note: VeriSign used to have a Class 2 digital ID, for use by individual developers. It could be obtained in a manner of minutes, and cost $20/year. They're no longer offering this level of ID; my guess is too many people were buying Class 2 IDs rather than the (much more profitable) Class 3 IDs. Oh, well...

When you've received your ID, it will be automatically installed in a pair of files called "cert7.db" and "key3.db", both in (probably) "C:\Program Files\Netscape\users\<yourName>". This is the digital certificate database used directly by Navigator. You don't need to export anything, but when you use the code signing tools below you'll need to specify this directory, the name of the ID to use within the database, and the password for the database (if any). (Make a backup copy of the two .db files in case things get wiped out.)

Note: you can also create your own test certificates. For more information, see Creating and Installing Test Certificates.

Note: you can use signtool to create your own test certificate if you like. For instructions on how see Netscape's page Generating Test Object-Signing Certificates at <http://developer.netscape.com/docs/manuals/signedobj/signtool/signcert.htm>. Beware, though: this will only work if you have a Navigator password (unlike me): if you don't, you'll get the error message signtool: failure authenticating to key database: Security I/O error.

Netscape's signtool's downloading page is at <http://developer.netscape.com/software/tools/index.html?content=/software/signedobj/jarpack.html>. The version for Windows 95 (as of 9/3/99) is at <http://developer.netscape.com/software/signedobj/signtool11/signtool11WIN95.zip>. You can find documentation on signtool at the page Signing Software with Netscape Signing Tool 1.1, at <http://developer.netscape.com/docs/manuals/signedobj/signtool/index.htm>.

Make sure that signtool is placed in one of the directories in your PATH, so that MS-DOS will be able to find it.

Set up a directory for signing

Create a top-level directory for the signing. Within that directory, create a subdirectory containing all the .class files for your applet (I called mine "MyApplet"). Within the subdirectory, place copies of all .class files in their directories. Top level .class files should be right inside this directory, and all package .class files should be in subdirectories with the package names (e.g. all my "util" package .class files are inside the directory "MyApplet\util").

Find Navigator's digital ID database directory

For each browser user, Netscape maintains a directory holding various items, including that user's digital ID database. You'll need to specify this directory when using the code signing tool so that the tool will be able to find the public and private components of your key.

This directory is (usually) "c:\program files\netscape\users\<yourName>". To make sure, search for a directory containing the files "cert7.db" and "key3.db" (which contain your public certificate and private key, respectively). For safety, you might want to copy these files to a secure place.

Find name of your digital ID

Now that you've found the digital ID database, you need to know the exact name of your digital ID. To do this, use signtool to list the contents of the database:

signtool -d"<DATABASE directory>" -L

In my case, I typed this:

signtool -d"c:\program files\netscape\users\griscom" -L

signtool will print out a list of all certificates. Yours will have some long name based on your name, and MUST have a "*" to its left (indicating it is available for signing). I got the following results:

using certificate directory: c:\program files\netscape\users\griscom
S Certificates
- ------------
  AT&T Certificate Services
  Thawte Personal Premium CA
  GTE CyberTrust Secure Server CA
  Verisign/RSA Commercial CA
  AT&T Directory Services
  GTIS/PWGSC, Canada Gov. Web CA
  Thawte Personal Freemail CA
  Thawte Server CA
  GTIS/PWGSC, Canada Gov. Secure CA
  MCI Mall CA
  VeriSign Class 4 Primary CA
  United States Postal Service CA
  KEYWITNESS, Canada CA
  Netscape Export Control Policy CA
  BBN Certificate Services CA Root 1
  Thawte Personal Basic CA
  CertiSign BR
  VeriSign Class 3 Primary CA
  Canada Post Corporation CA
  Integrion CA
  IBM World Registry CA
  Uptime Group Plc. Class 1 CA
  VeriSign Class 1 Primary CA
  VeriSign Class 2 Primary CA
  VeriSign, Inc. - VeriSign, Inc.
  Uptime Group Plc. Class 2 CA
  Thawte Premium Server CA
  Uptime Group Plc. Class 3 CA
  Verisign/RSA Secure Server CA
  GTE CyberTrust Root CA
  Uptime Group Plc. Class 4 CA
* Daniel T Griscom's VeriSign Trust Network ID
------------ 

So: my ID name is "Daniel T Griscom's VeriSign Trust Network ID", and can be used for signing (phew). Note the list of the CAs who's CA certificates are installed in my browser, ready to validate digital IDs. If you only want to see the signing certificates, you can use signtool's -l option instead of the -L option.

Find password for your digital ID

If you have set a Navigator/Communicator password, you'll need this password for access to the database. Being a trusting soul I haven't set one, so the batch file below shows an empty password. If you have set one, you can include it in the batch file (which is insecure), or remove the password argument from the signtool line and type in your password each time you sign your applet (which is secure).

Note: I have had a report that signtool 1.1 on WinNT 4.0 with Service Patch 3 fails with a message "PROBLEM signing data (Out of memory)" when a password is included in the command line. When the developer removed the password from the command line, signtool put up a dialog prompting for the password and then properly signed the applet. I don't know how often this occurs, but if you see the above message then suspect this bug.

Create a .jar signing batch file

Life's a lot easier when you let the computer do the grunt work. So, here is a DOS batch file that creates a signed .jar archive for all files in a given subdirectory. Create the following DOS batch file called jarsign.bat:

@ECHO OFF
REM Script to make a directory into a signed .jar file. Takes the directory name as
REM its argument; creates a .jar file of the same name in the directory above the
REM specified one. Note: must be run in directory above directory to be signed.

REM I'll set up a couple of variables to make things more readable. You'll need to
REM edit these values to match your setup. If you get an error such as
REM "Out of environment space" then you'll have to increase your environment space.
REM (Boy, do I love DOS.)

REM This is the location of the digital signature database
SET ID_LOC="c:\program files\netscape\users\griscom"

REM This is the name of the digital ID to be used
SET ID_NAME="Daniel T Griscom's VeriSign Trust Network ID"

REM This is the password for the database. I haven't set one for mine,
REM so I don't need anything here (the single space is ignored).
SET ID_PASSWD=" "

REM This is the compression level for the final .jar file. 0 means no
REM compression, 9 means highest compression. Note! it used to be
REM that .jar files had to have no compression to work, but now it seems
REM that it's OK. I don't know when this changed, or with what version
REM of Navigator. signtool's default value is 6. Be warned, and try out
REM whatever you decide.
SET COMPRESSION=9

REM signtool signs the directory and creates the .jar archive.
REM Arguments:
REM    -d[text]    Directory holding digital signature database
REM    -k[text]    Name of ID in digital signature database
REM    -p[text]    Password for the database. NOTE! to be more secure, remove
REM                this argument and you'll be prompted for the password.
REM    -Z[text]    Name of .jar file to be created
REM    -c[digit]   Compression level ("0" - none, "9" - highest).
REM    [rest]      Name of directory to be signed
ECHO *********** About to sign directory using signtool ***********
signtool -d%ID_LOC% -k%ID_NAME% -p%ID_PASSWD% -Z %1.jar -c%COMPRESSION% .\%1

REM Punt the various environment variables
SET ID_LOC=
SET ID_NAME=
SET ID_PASSWD=
SET COMPRESSION=

ECHO *********** Done creating .jar archive ***********

Change the ID_LOC, ID_NAME and ID_PASSWD values to correspond to your digital ID directory, name and password, respectively. Make sure that jarsign.bat is where MS-DOS can find it (somewhere in your PATH). Also, when you execute the batch file you must be in the directory containing the directory to be signed.

Note: including your password in the text of jarsign.bat is a classic security no-no (although it isn't as bad as not having a password at all). If you want to be correct, remove the -p argument from the signtool line, and you'll be prompted for your database's password each time you run jarsign.bat.

Do the actual signing

Note! Before you run signcode, make sure Navigator is shut down!

Change to the directory that contains the directory containing your applet's .class files. Then, run jarsign with the name of the applet subdirectory as an argument:

jarsign MyApplet

You'll see lots of messages scroll up the screen. When done, a new archive with the applet directory's name and the suffix ".jar" will be created.

Verify the signed archive

The first time you create a signed archive you'll want to verify it. Do this by using the -w option for signtool:

signtool -d"c:\program files\netscape\users\griscom" -w  MyApplet.jar

Note: you'll have to change the -d argument to match your own digital ID database directory. You might want to make the following one-line batch file, named jarcheck.bat:

signtool -d"c:\program files\netscape\users\griscom" -w %1.jar

(again, change the directory name), and then use it thusly:

jarcheck MyApplet

If the archive is signed properly, you'll get a printout of the contents of the signing ID. If not, you won't.

Install the signed archive

Put the signed .jar archive into the web server directory containing the main class of your applet. Change the .html file that invokes the applet so that it mentions the archive:

<title>My Wonderful Signed Applet</title>
<hr>
<applet code="MyApplet.class" ARCHIVE="MyApplet.jar" width=600 height=350>
</applet>
<hr>

Possible Problems

If you sign your applet but you still get security exceptions when you run your applet then you code may not be properly using the Netscape Capabilities API to request privileges. Another clue is that you never see Navigator's security dialog, even when your code tries to do secure things. For information on the Capabilities API, see Netscape's document Java Capabilities API at <http://developer.netscape.com/library/documentation/signedobj/capsapi.html>, or Joe Bowbeer's article Signing Applets for Internet Explorer and Netscape Navigator at <http://ourworld.compuserve.com/homepages/jozart/article/index.html>.

If signtool complains "signtool: PROBLEM signing data (Certificate not approved for this operation)" then your certificate isn't approved for signing archives. You probably have an Email-signing certificate instead of a software publishing certificate.

A similar error message may indicate that your CA's certificate in your browser isn't marked for certifying software developers. Open the Security Info window, click on "Certificates/Signers" in the left column, select your CA in the list, and then click "Edit". Find the checkbox marked "Accept this Certificate Authority for Certifying software developers" and make sure it is checked.

If signtool can't find your private key, then perhaps you haven't been supplying a needed password.

If all else fails, then try this: at each step in the signing process, substitute information that you know is wrong. Examples: put in incorrect passwords, change file names, change paths, rename files, etc. If this changes the results (new error message, different error message, etc.) then your original information was probably correct. If not, then either the problem is occurring before that step, or your original information was itself wrong.

Notes

Although it should, Navigator 4.0 doesn't automatically load .gif (and probably .jpg) images from archives. You can, however, write code that will fetch .gif images from your applet's .jar archive. The process is explained in this JavaWorld article: <http://www.javaworld.com/javaworld/jw-07-1998/jw-07-jar.html>.

Files with the suffix .P12 can be used for moving certificates from machine to machine (in Navigator, choose the "Security Info" menu item, and then click "Certificates/Yours"; there are Import and Export buttons in this screen), but for signtool to use the certificates they must be installed into key3.db and cert7.db files.

If you don't have a digital ID, or you don't want to re-sign your applet again and again while developing, there is hope. Check out the Netscape tech note Activating Codebase Principals, at <http://developer.netscape.com/library/technote/security/sectn2.html>. By default, Navigator will let you trust applets with a given digital signature, or from your local hard disk (using file: URLs). If you activate codebase principals (meaning that principals, or trusted sources, can depend on where your code is based), Navigator will let you trust applets that come from specific http: URLs.

Sub-note: although the Activating Codebase Principals tech note tells you to edit the text file "prefs.js", this isn't always true. On the Macintosh, for instance, you must edit the file "Netscape Preferences", which isn't registered as a text file at all (you must force a text editor to open it, although once open it's fine). Good luck.

You can also use signtool to sign JavaScript scripts that are embedded in .html pages. For more information, see Netscape's documentation at <http://developer.netscape.com/docs/manuals/signedobj/signtool/signscpt.htm>, or Danny Goodman's article at <http://developer.netscape.com/viewsource/goodman_sscripts.html>.

Next section: Writing code for Microsoft Internet Explorer