How-to provide secure add-on updates (for Firefox 3)
Introduction
First of all making Firefox add-ons update is quite a pain in the ass. For me, at least. Since Firefox 3 it's even twice as crazy, so I will show you in this tutorial how-to make a correct install.rdf file and update.rdf. Let's say you already have your awesome add-on done. Everything works fine, but now you want to provide automatic updates, because no one would install them manually.
Note: This is for developers who are already familiar with the FF add-on structure and it's fundamentals.
Getting started
The two files of importance are install.rdf (based directly in your add-ons main folder) and update.rdf (this file will be on your server). You can download my example files right here:
Now please have a look at the files with your text editor (I prefer Notepad++ ) If the source code doesn't show up in beautiful colors choose the language "XML" in your editor.
Unique ID and updateURL
Every add-on needs a unique id. Instead of generating some crazy number, you can also use your email address, f.e. name@mydomain.com. Once chosen, please never rename it, otherwise you will end up having your add-on installed 10 times, and you'll throw your laptop against the wall.
Please modify this in the example install.rdf:
em:id="name@mydomain.com" (your unique add-on identifier) em:name="The best add-on in the world" (add-on's name)
em:version="0.1" (your add-on's current version)
em:creator="myname"
em:description="This add-on can wash dishes"
em:updateURL="http://www.mydomain.com/myaddon/update.rdf" (updateURL is the path, where FF will look for update information)
Now open the update.rdf file and modify:
RDF:about="urn:mozilla:extension:name@mydomain.com" (put your unique identifier in here) em:minVersion="1.5" (Firefox version 1.5, whatever you think, but this is a good default)
em:maxVersion="5.0.0.*" (haha my add-ons will work till Firefox 5!!!)
em:updateLink="http://www.mydomain.com/myaddon/myaddon.xpi" (Path to your actual myaddon.xpi file) em:version="2.2" (this is your new version, FF will update if it's higher than the add-on's)
Signature and UpdateKey with McCoy (pain in the ass)
So, usually we would package up our add-on now with the new install.rdf and upload update.rdf to our server (if update available, or for testing purpose). But no - since Firefox 3 there are some special security regulations.
You might have seen the weird numbers in the RDF files, those are the Signature (update.rdf) and the UpdateKey (install.rdf). You will need to generate your own ones with a tool called McCoy. Every time you change something in the update.rdf, you will need to generate a new signature. The UpdateKey will always stay the same.
Complete documentation here: http://developer.mozilla.org/en/docs/McCoy
So after installing McCoy, open it, choose a master password, set a new key and name it f.e. "myaddon". All of this is not hard, but you'll need to concentrate or you'll end up puking on your table (seriously!). Now: Click on the button "Install", and select your install.rdf file, McCoy will update your UpdateKey automatically now. Pretty cool, i know. Same with the signature in the update.rdf file: Click on the button "Sign", select your update.rdf file and go for it. Now, you can also use the "Verify" button to check if everything went well (Doesn't always work actually).
Every time you edit the update.rdf file, you'll have to go through this procedure again, or your updates just won't work.
Get UpdateHash with HashTab Tool
We're not quite done, there's one more security obstacle. We need to get a hash number of your finished add-on. A hash is a unique identifier for a file, to make sure that no super-evil hacker manipulates it during the transfer. There are different hash standards, but we will use "sha1". To get this number, you should install:
- HashTab for Windows or
- MD5deep Compiled for Mac os or
- MD5deep for every other operating system
If you use HashTab, after installing it nothing happens. HashTab only adds some features to your context menues.
Excuse the German screenshot, but you get the idea. Windows users do a right-click on the finished add-on, select "properties" and in the second register you'll find the SHA-1 Hash, copy it and paste it into your update.rdf file with the definition "sha1:" in front. It should look like this:
em:updateHash="sha1:DB8C3912AD7D2E1FD175F5D2AF2EB934C69BA95A"
If you are interested, you can find more details here:Mozilla Developer's Wiki
Testing and Updating
Now you can upload your *.xpi and update.rdf to your server (think carefully about the URLs you've defined earlier). Let's say you already have your add-on installed and now there's a new version and a new update.rdf file on your server. Go to your add-on window and select update for your add-on. What does it say? "No updates available"? Well there should be one, if you moved to a higher version number. It's time for debugging!
- Enter "about:config" in you URL bar
- Find the preference extensions.logging.enabled and switch it to "true"
- close Firefox
- Open the windows command line ("Start", "Run...")
- Type firefox -console
- Now you can see why your add-on is not updating
Good luck with the debugging, and if you see a window like this - maximum respect!