McCoy

McCoy is an application that allows add-on authors to provide secure updates to their users. Applications periodically look for and install updates to their add-ons. It's important that the update information retrieved has not been tampered with since being written by the add-on author. Specifically, it focuses on the process of digitally signing update manifests so the applications can verify the integrity of a manifest retrieved over normally insecure channels.

If you want to learn about the technical details of McCoy then visit the project wiki.

Installing McCoy

To use McCoy you need to download and install it. McCoy is provided in the standard package for your operating system, just extract it where you like and run it.

There are some known issues with running McCoy on Linux. It will not run on older versions of Linux and there are known problems even on up to date systems. We hope to resolve this for the next release.

Uninstalling McCoy

To uninstall McCoy simply delete the applications files. The cryptographic keys and other McCoy data are kept in a profile folder separate from the application so you can uninstall and reinstall without losing your precious keys.

Backing up data

If you need to backup your data or move it from one machine to another you need to take a copy of the profile folder. This is located in:

  •  %APPDATA%\Mozilla\McCoy (Windows)
  • ~/.mozilla/mccoy (Linux)
  • ~/Library/Application Support/McCoy (Mac OS X)
It is highly recommended that you back up your profile folder and store it in a safe location whenever you create a new key; without a backup, there is no way to recover your private keys if they are lost!

Running McCoy

To run McCoy simply run the mccoy executable (or the McCoy application on OS X). The first time it runs it will ask you to create a master password. It is strongly recommended that you use a password to protect your McCoy data. Once you have a password set you can change it from the Keys menu and you will have to enter it each time you run McCoy.

Signing from command line

Currently there is no support to run McCoy from command line under Windows, but it is planned to add this support in the future. However, there are several external and unofficial tools which enable signing from command line:

  1. Uhura - part of the MXTools package from SoftLights http://www.softlights.net/projects/mxtools/uhura.html
  2. signOnTheLine - an extension to McCoy - Important: You have to checkout rev 222, later revisions are not working in McCoy!
    https://fireclipse.svn.sourceforge.net/svnroot/fireclipse/trunk/FireclipseExtensions/chromebug/mccoy/signOnTheLine/
  3. Bug 396525 - patch to McCoy
    https://bugzilla.mozilla.org/show_bug.cgi?id=396525

Signing update manifests

Before you release your add-on

In order to verify the update manifests applications need to already have information from you for how to verify it. This is in the form of the public part of a cryptographic key included in the original add-on you release.

The first step is to create a cryptographic key. Simply click the "Create" toolbar button or select "Create Key" from the "Keys" menu. You should give the key a name that will remind you what you are using it for. It is up to you how you use your keys, either using one key for all add-ons or one key per add-on would seem sensible choices.

Once you have a key you need to add its public part to your add-on's install.rdf file. The simplest way to do this is to select the key then click the Install toolbar button. You must then locate your install.rdf for McCoy and the public part of the key will be added directly to the file. The file will be overwritten so take a backup if you need to.

You can then include this install.rdf in your add-on's xpi and release it.

Note: If you wish to manually add the public key to the <tt>install.rdf</tt> you can right click the key, select "Copy Public Key" and then add it to the file as an updateKey entry.

Releasing an update

Once you are ready to release an updated version of your add-on you must create yourself an update.rdf file. You need to use McCoy to sign this file so that the application can verify that it really came from you. Simply select the key you originally added to the add-on's install.rdf, then click the "Sign" toolbar button, select your update.rdf file and the data in it will be signed. It's important to note that if you change any information in the update file then it must be signed again.

Note: The signing is RDF aware, which means that if you reorganized the XML in the file into a more human readable form but the RDF data remained the same then the signature would still be valid.

Document Tags and Contributors

 Last updated by: kmaglione,