• Summary of Process
• Collect tools
• Set up a directory for signing
• Create a .cab signing batch file
• Do the actual signing
• Verify the signed archive
• Install the signed archive
• Possible problems
• Note on Microsoft Security Levels

Summary of Process

Make any necessary changes in the applet's code (see Writing code for Microsoft Internet Explorer).

Collect the tools you'll need: Internet Explorer 4.0 (or later), a Microsoft Authenticode digital ID, cabarc, signcode, signer.dll, javasign.dll, and chktrust. Use cabarc to create a .cab file containing the applet .class and .gif files. Use signcode to sign the archive. Use chktrust to verify the signed archive. Install the results. Enjoy.

Note: this procedure has been extensively revamped due to changes in Microsoft's tools. It is now based on the code signing tools included with Microsoft's Java SDK 2.01.

Note: Internet Explorer version 4 was the earliest to recognize signed applets, and only under Windows. The Macintosh version of Explorer doesn't (and may never) recognize signed applets. Ahh, standards...

Collect tools

You'll need seven items to do Explorer digital signing: Microsoft Internet Explorer 4, a Microsoft Authenticode digital ID, a DOS program called cabarc.exe, a DOS program called signcode.exe, a DOS program called chktrust, and two application extensions called signer.dll and javasign.dll.

Download Internet Explorer 4.0 from the Microsoft web site at <http://www.microsoft.com/windows/ie/default.htm>.

To get a digital ID from VeriSign, use Internet Explorer 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 Microsoft Authenticode". 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 receive your ID from VeriSign, you will be prompted to store it in a pair of files: your certificate file (with suffix ".spc") and your private key file (with suffix ".pvk"). When you use the code signing tools below you'll need to specify the location of these two files. (Copy them onto a floppy disk for safekeeping.)

Note: if you get an Authenticode digital ID from Thawte, the ID will be installed directly into the Windows key registry, not into ".spc" and ".pvk" files. To use such an ID, you have to change the arguments to signcode in the cabsign.bat file below: instead of using the -spc and -v arguments, you need to use the -cn argument, specifying the certificate name. You can get your certificate name by going to the Content tab under Internet Explorer 4's "View / Internet Options" menu and clicking the "Personal" certificates button. [Thanks for the info, Chris Wooldridge!]

Alternatively, you can create your own test certificates using makecert and cert2spc. For more information, see Creating and Installing Test Certificates.

Now that you've got your certificate, you'll need to get the other tools. They are all part of Microsoft's Java SDK 2.02, which can be found (9/3/99) at <http://www.microsoft.com/java/download.htm>. (It's a 16MB download to get 300kB of files; sorry.)

The first tool is cabarc.exe, a very simple command-line oriented "cab" archiver. There's a much more powerful alternative called diamond: it provides WAY more power and complexity than you need for Java code archiving and signing, so I'd suggest you stick with cabarc.

If you're looking to permanently install your Java classes on the user's browser, check out dubuild.exe. dubuild builds cab files, but uses an OSD manifest rather than a .inf file. The advantage is that you can persistently install your java class files on a client machine. Dubuild is included in the Microsoft SDK; you can find out more about dubuild at <http://www.microsoft.com/Java/sdk/32/pg/pg_tools_swdist_dubuild.htm>

If you use dubuild, the only real difference is the step in the signing batch file that calls cabarc will be replaced by a call to dubuild (with a different set of parameters, of course).

Note: Dubuild generated cab files must be signed; otherwise the browser will ignore the file with no explanation as to what happened. To use the package manager, you also have to use a different set of applet tags, which are documented at <http://www.microsoft.com/Java/sdk/32/pg/pg_pkgdist_dubuild_3.htm>

signcode.exe is a very simple command-line oriented code signing tool. chktrust.exe is a very simple command-line oriented signature testing tool.

Note: these tools requires the "Microsoft CryptoAPI" to work. Although this isn't documented anywhere, this API is installed when you install Internet Explorer 4.0 or later.

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 a subdirectory called "util"). Include all images files as well (these are utilized by Explorer, although not Navigator).

Create a .cab signing batch file

Create the following DOS batch file called cabsign.bat:

@ECHO OFF
REM This batch file creates and signs a .cab file. The first argument should be the
REM name of the directory of files to be put into the cabinet (NO terminating "\",
REM please!) The second argument should be the formal name of the
REM applet. The third argument should be low, medium or high (generally low).
REM Note: you should be in the directory containing the directory of 
REM files to be CABbbed/signed when you run this.

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 ID certificate file (.spc). For convenience,
REM I put mine in the same directory as my Navigator ID database.
SET CERT_FILE="c:\program files\netscape\users\griscom\mycred.spc"

REM This is the location of the digital ID private key file (.pvk).
SET KEY_FILE="c:\program files\netscape\users\griscom\mycred.pvk"

REM First, create the CAB file. The arguments here are:
REM    -r        Recurse into subdirectories
REM    -p        Preserve path names
REM    -P [arg]  Strip the argument (here "%1\") from the beginning of each path
REM    N  [arg]  Create the given named .cab file
REM    [rest]    Put these files (here "%1\*.*") into the .cab file
REM Note! this does NOT use the -s option to reserve space for the signature;
REM the latest version of signcode (from the Java SDK 2.01) doesn't need this.
ECHO *********** About to create .cab archive using cabarc ***********
cabarc -r -p -P %1\ N %1.cab %1\*.*

REM Next, sign the code. Arguments are:
REM    -j javasign.dll    This provides the tools to do Java permission levels
REM    -jp  [arg]         The permission level to be used
REM    -spc [arg]         Software publishing certificate file
REM    -v   [arg]         Private key file
REM    -n   [arg]         Nice name of archive (shown in digital ID dialog)
REM    [arg]              Archive file to be signed (here "%1.cab")
ECHO *********** About to sign archive using signcode ***********
signcode -j javasign.dll -jp %3 -spc %CERT_FILE% -v %KEY_FILE% -n %2 %1.cab

REM Finally, timestamp the code. (I put this in a separate command to make each
REM command simpler.) NOTE! for this to work you must have an Internet
REM connection up and running. Arguments are:
REM    -x                 Timestamp the archive; do not sign it (it's already done)
REM    -t   [arg]         The timestamp server's HTTP address (here it's VeriSign)
REM    -tr  [arg]         The number of times to try timestamping before giving up
REM    [arg]              Archive file to be timestamped (here "%1.cab")
ECHO *********** About to timestamp .cab archive using signcode ***********
signcode -x -t http://timestamp.verisign.com/scripts/timstamp.dll -tr 5 %1.cab

REM Punt the various environment variables
SET CERT_FILE=
SET KEY_FILE=

ECHO *********** Done timestamping .cab archive ***********

Change the CERT_FILE and KEY_FILE values to correspond to the location of your public credential file and private key file, respectively. Make sure that cabsign.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: if you gave your ID a password when you got it from VeriSign, signcode will prompt you for the password. There's no way to include a password in signcode's arguments.

Remember: if you use Thawte as your CA you'll have to modify the signcode line to use a -cn argument instead of the -spc and -v arguments.

Do the actual signing

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

cabsign MyApplet "Super Duper Applet" "low"

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

Note: if you don't have an active connection to the Internet when you do this, the timestamping process will fail. The resulting archive will be valid and signed, just not timestamped.

Note: the timestamping URL I give in my batch file above is for VeriSign. If your certificate wasn't issued by VeriSign then you should probably use your CA's timestamping service (although I believe VeriSign's will work, it isn't very fair).

Verify the signed archive

The first time you create a signed archive you'll want to verify it. Do this using chktrust:

chktrust MyApplet.cab

If the archive is signed properly, you'll get a "Security Warning" dialog asking if you want to install and run "Super Duper Applet", which was signed by you (signature verified by your CA). If not, you won't.

Install the signed archive

Put the signed .cab 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" width=600 height=350>
<param name="CABBASE" value="MyApplet.cab">

</applet>
<hr>

Note: f you need to have an applet with multiple .cab archives, you can use the CABINETS applet parameter:

<param name="CABINETS" value="MyApplet.cab,MyApplet2.cab">

Possible Problems

Timestamping may fail for a number of reasons:

• signcode can't reach the timestamping server because you aren't connected to the Internet
• signcode can't reach the timestamping server because there's heavy traffic between you and it
• You may have an incorrect timestamping URL

If you don't see a security dialog when the applet is loaded into Explorer then the applet isn't properly signed and won't be allowed any privileges.

If your signed applet gets a SecurityExceptionEx[Host] exception when it tries to do a "dangerous" action, then you'll have to modify your code to assert permission. See Writing code for Microsoft Internet Explorer.

Once in a while I've seen a .spc that had two certificates instead of one. The first certificate was the CA certificate for the code signing certificate, and the second one was the actual code signing certificate. Problem: signcode only looks at the first certificate in a file, so the signing certificate was never seen. I used certmgr to see the problem (listing the certificates in the file); once I figured it out I used certmgr again to delete the first certificate in the file. (Nasty.)

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.

Note on Microsoft Security Levels

Internet Explorer actually supports three different security levels: "high", "medium" and "low." The batch file above assumes that you want the low security level, which grants all possible privileges to the applet. High level means that the applet is restricted to the sandbox, just like an unsigned applet. Medium level sounds more interesting: the applet has access to a certain amount of temporary hard disk space, and can do "user-directed" file I/O.

Problem: for your code to take advantage of the abilities granted at the Medium level you must use Microsoft-proprietary Java classes. This means that if you rely on these capabilities your code will be restricted to running on Microsoft platforms. Since I like conspiracy theories, I view this as one more attempt by Microsoft to lure programmers into writing Java code that only works on Microsoft platforms, thus subverting a major threat to their hegemony. Other, more charitable souls may see this as Microsoft's generous efforts to enhance Java. You'll have to decide for yourself. For more information, see Signing a Cabinet File with Java Permissions at <http://www.microsoft.com/Java/sdk/32/pg/pg_pkgdist_signcode_4.htm>.

Next section: Signing for both Navigator and Explorer