Labs/Sigma
Sigma is a platform to automatically install Labs approved add-ons and keep them up-to-date. The user-facing name of this add-on is Labs Pack.
A manifest is hosted on https://sigma.mozillalabs.com/ that controls the add-on behavior such as installing/uninstalling add-ons and showing informational pages. The manifest is only followed if a number of security checks pass such as a signature check. Some state is stored locally on each client that affects the add-on behavior.
Contents
Manifest Structure
The manifest is a JSON file with file extension .json where the top level JS object has the following properties:
| infoUrl | string | Information url to open in a tab if different from the previous infoUrl |
|---|---|---|
| install | [objects] | Array of add-on objects to install (see below) |
| timestamp | Date (string) | Time when the manifest was created |
| uninstall | [strings] | Array of add-on id strings to uninstall |
Install Add-on Object
The install array contains add-on objects with the following structure:
| hash | string | Expected hash of the downloaded xpi structured as "<hash algorithm>:<hex hash value>" e.g., "sha256:a1b2c3..." |
|---|---|---|
| id | string | Add-on id to check if it's already installed locally |
| url | string | URL to fetch the .xpi to install the add-on |
| version | string | Version of the add-on to check if the local version is already current |
Manifest Signature
At the same level as the .json file, there must be a .sig file that contains the expected signature of the plain-text JSON manifest that is verified by the public key, embedded in the add-on, corresponding to the private key used to sign the manifest.
Local State
In addition to the state of installed add-ons managed by Firefox, Sigma tracks the following values as preferences under the pref-branch extensions.sigma.:
| disabledIds | JSON [strings] | Add-on ids of add-ons that were disabled when Sigma was disabled |
|---|---|---|
| infoUrl | string | Information url from the last successful manifest (copied from the infoUrl property) |
| installIds | JSON [strings] | Add-on ids from the last successful manifest (copied from the id property of the objects in the install property) |
| signature | string | Signature from the last successful manifest (copied from the .sig file) |
| test | boolean | User set preference to turn on testing against a test manifest/signature |
| timestamp | JSON Date | Timestamp from the last successful manifest (copied from the timestamp property) |
Add-on Behavior
Sigma will automatically fetch and follow the manifest when triggered by a number of events.
Main Workflow
- Download the .sig signature file
- Check if the signature matches the local state signature
- If it matches, stop the update as the manifest and signature are unchanged
- Download the .json manifest file
- Check that the manifest and signature are correct with the embedded public key
- If the signature is not correct, abort
- Check that the timestamp is a valid date
- If not or missing, abort
- Check that the timestamp is at most 30 days old
- If it's too old, abort because we don't trust old manifests
- Check that the timestamp is newer than the local state timestamp
- If it's older or the same, abort because we only trust newer manifests
- Check if the infoUrl is different from the local state infoUrl
- If it is different, open a new tab with the new url and save infoUrl
- For each add-on object in install, try to install the add-on if necessary
- Check if a local add-on exists with the id
- If it exists, check if it's newer or the current version
- If it's newer or current, don't re-install this add-on
- If it exists, check if it's newer or the current version
- Check that the hash is a valid "algorithm:hex value" hash
- If it's not a valid hash, don't install this add-on
- Download the add-on .xpi at the url
- Check that the hash matches the computed hash for the .xpi
- If the hash does not match, don't install this add-on
- Install the add-on
- Check if a local add-on exists with the id
- For each add-on id in uninstall, uninstall if necessary
- Check if a local add-on exists with the add-on id
- If it exists, uninstall it
- Check if a local add-on exists with the add-on id
- Save state (installIds, signature, timestamp) from the manifest now that we've followed the instructions
Triggering Events
The following are various events that will trigger the main workflow:
- On install of the restartless Sigma add-on
- On re-enabling of the add-on
- Periodically every 24 hours after the add-on starts
- When Firefox starts up and the add-on is loaded
- When add-ons are being checked for updates
Even with these triggering events, if Firefox is offline or has already checked within the last hour since being activated, the update is skipped.
Other Event Behavior
When the add-on is being disabled, any active add-ons that are in the installIds list of add-ons that Sigma manages are disabled. These add-ons that were disabled are locally saved as disabledIds.
When the add-on is being enabled, any previously Sigma-disabled add-ons stored as disabledIds are re-enabled as well.
