• Firefox extensions
• Projects
• Snippets
• Links
• Contact me
• GPG public key

Code snippets

XPI signing tutorial

Some years ago, I had to apply a digital signature to a (proprietary) Firefox XPI extension at work. At the time (Firefox was pre-1.0 at the time), I had to dig and search to find half complete documentation. With some extrapolation and by joining the info I gathered here and there, I managed to get a signed XPI file. Obviously, my boss asked that I document the process for him so we could sign new versions with less hassle, and that I did.

I figured that with time (about three years have passed), the Mozilla folks would have better documented the process, and I sort of forgot about the sparse documentation. A couple of days ago, a discussion on Slashdot mentionned the still pitiful state of the Mozilla documentation regarding XPI signing. So I went and re-dug up the documentation I could find, and made this tutorial.

I have executed all the following steps on a Fedora Core 6 installation, all with software and libraries that come with the distro. Therefore, this tutorial currently assumes you are running Linux. Instructions for Windows users will be provided in a future version of this tutorial.

What you need to have before beginning :

• A PKCS#12 key/certificate (file with extension .pfx). That file should be provided to you by a certificate authority, like Verisign or Thawte. If you don't want a commercial certificate or can't afford one, Ascertia can provide you with a free certificate, but turning it into a code signing certificate requires some extra work, which I have detailed on another page.
• A Firefox installation (d'uh!). I have used Firefox 2.0.0.1 for this tutorial. However, I have signed XPI extensions since Firefox 0.9, so pretty much all versions have the required tools. Some options might have changed name, but they're all in there somewhere.
• A compiler. Like many free software, Mozilla's NSS tools are distributed as source. That means you'll have to compile the code signer yourself.
• GNU make. For some reason, Mozilla advises to not use another make program than GNU's one. Probably has to do with some compatibility stuff.
• The Firefox XPI extension you want to sign.

If you are running Linux, you can download this file which automates the first few steps, greatly simplifying the process. If you use the above file, unpack it where you want to work from and it will create a directory named XPI_signing. cd into that directory in a console, execute the build.sh script and skip to step 5.

Step 1: In a console, create a directory named XPI_signing, and cd into it. Then create a sub-directory named certs. This is where we'll put our certificates. Create another subdirectory, which we'll call XPI. As you might have guessed, this is where we'll unzip the extension to be signed.

Step 2: Get the Mozilla NSS tools' source code. The easiest way to do that is through CVS, with the following commands:

Step 3: Build NSS. cd into the mozilla/security/nss subdirectory and build the thing with gmake nss_build_all

Step 4: Copy the newly built signtool executable in the XPI_signing directory.

Step 5: Unzip your XPI extension in the XPI sub-directory created on step 1. Make sure to put in that directory only the content of the XPI extension, and not the extension itself.

Step 6: Import your code signing certificate into Firefox. To do so, launch Firefox, and open the Preferences dialog from the Edit menu. In the dialog, go to the Advanced tab, and click on the View Certificates button to open the Certificate Manager dialog.

Step 7: We're done with Firefox for now, so head back to your console. You'll want to copy two files from your Firefox profile directory into your certs directory. Those files are cert8.db and key3.db. Those two files contain the certificate information you need to sign a directory with the signtool we built and copied on step 4.

Step 8: Now that we have confirmed we have a valid signing certificate, we can use signtool to sign the content of the XPI directory. In the command below, replace «certificate_id» with the name of the certificate as we have discovered it in the previous step (10223188607… in my case).

Step 9: The content of the XPI directory is signed. All we need to do now is to package it into a usable Firefox extension. While packaging an unsigned extension simply means zipping the whole XPI directory's content into a file, that is not how it is done when dealing with signed extensions. This last part is very simple but very badly documented, and this is why most people fail to sign extensions. Here's the trick though. The order in which the files are included in the zipped file matters, and the very first file that needs to be included is META-INF/zigbert.rsa. Once this file is added to the zipped file, you can add (not replace) all the other files.

Step 10: There ya go! You should now have a signed extension on your hands. Install your newly created extension in Firefox and gaze at the beauty of a signature.

Step 10 (b): If you have been using a free certificate authority to get your signing certificate, make sure you are aware of the possible consequences for your users. See the caveat section of the Free Certificate Authority tutorial.