Labs/Sigma - Revision history

Mardak: /* Triggering Events */ and other event behavior

2010-10-12T21:50:15Z

Triggering Events: and other event behavior

← Older revision		Revision as of 21:50, 12 October 2010
Line 117:		Line 117:

	== Triggering Events ==		== 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 <tt>installIds</tt> list of add-ons that Sigma manages are disabled. These add-ons that were disabled are locally saved as <tt>disabledIds</tt>.

			When the add-on is being enabled, any previously Sigma-disabled add-ons stored as <tt>disabledIds</tt> are re-enabled as well.

Mardak: /* Add-on Behavior */ add list of actions

2010-10-12T21:43:14Z

Add-on Behavior: add list of actions

← Older revision		Revision as of 21:43, 12 October 2010
Line 82:		Line 82:

	= Add-on Behavior =		= Add-on Behavior =

			Sigma will automatically fetch and follow the manifest when triggered by a number of events.

			== Main Workflow ==

			# Download the <tt>.sig</tt> signature file
			# Check if the signature matches the local state <tt>signature</tt>
			## If it matches, stop the update as the manifest and signature are unchanged
			# Download the <tt>.json</tt> 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 <tt>timestamp</tt> is a valid date
			## If not or missing, abort
			# Check that the <tt>timestamp</tt> is at most 30 days old
			## If it's too old, abort because we don't trust old manifests
			# Check that the <tt>timestamp</tt> is newer than the local state <tt>timestamp</tt>
			## If it's older or the same, abort because we only trust newer manifests
			# Check if the <tt>infoUrl</tt> is different from the local state <tt>infoUrl</tt>
			## If it is different, open a new tab with the new url and save <tt>infoUrl</tt>
			# For each add-on object in <tt>install</tt>, try to install the add-on if necessary
			## Check if a local add-on exists with the <tt>id</tt>
			### If it exists, check if it's newer or the current <tt>version</tt>
			#### If it's newer or current, don't re-install this add-on
			## Check that the <tt>hash</tt> 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 <tt>url</tt>
			## Check that the <tt>hash</tt> matches the computed hash for the .xpi
			### If the hash does not match, don't install this add-on
			## Install the add-on
			# For each add-on id in <tt>uninstall</tt>, uninstall if necessary
			## Check if a local add-on exists with the add-on id
			### If it exists, uninstall it
			# Save state (<tt>installIds</tt>, <tt>signature</tt>, <tt>timestamp</tt>) from the manifest now that we've followed the instructions

			== Triggering Events ==

Mardak: /* Manifest Signature */

2010-10-12T21:18:29Z

Manifest Signature

← Older revision		Revision as of 21:18, 12 October 2010
Line 49:		Line 49:
	== Manifest Signature ==		== Manifest Signature ==

	At the same level as the <tt>.json</tt> file, there must be a <tt>.sig</tt> file that contains the expected signature of the plain-text JSON manifest that is verified by the public key corresponding to the private key used to sign the manifest.		At the same level as the <tt>.json</tt> file, there must be a <tt>.sig</tt> 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 =		= Local State =

Mardak: /* Local State */ indicate which prefs are JSON

2010-10-12T21:10:58Z

Local State: indicate which prefs are JSON

← Older revision		Revision as of 21:10, 12 October 2010
Line 57:		Line 57:
	{\| cellpadding=5		{\| cellpadding=5
	! <tt>disabledIds</tt>		! <tt>disabledIds</tt>
	\| align=center \| <tt>[strings]</tt>		\| align=center \| <tt>JSON [strings]</tt>
	\| Add-on ids of add-ons that were disabled when Sigma was disabled		\| Add-on ids of add-ons that were disabled when Sigma was disabled
	\|-		\|-
Line 65:		Line 65:
	\|-		\|-
	! <tt>installIds</tt>		! <tt>installIds</tt>
	\| align=center \| <tt>[strings]</tt>		\| align=center \| <tt>JSON [strings]</tt>
	\| Add-on ids from the last successful manifest (copied from the <tt>id</tt> property of the objects in the <tt>install</tt> property)		\| Add-on ids from the last successful manifest (copied from the <tt>id</tt> property of the objects in the <tt>install</tt> property)
	\|-		\|-
Line 77:		Line 77:
	\|-		\|-
	! <tt>timestamp</tt>		! <tt>timestamp</tt>
	\| align=center \| <tt>Date ~~(string)~~</tt>		\| align=center \| <tt>JSON Date</tt>
	\| Timestamp from the last successful manifest (copied from the <tt>timestamp</tt> property)		\| Timestamp from the last successful manifest (copied from the <tt>timestamp</tt> property)
	\|}		\|}

	= Add-on Behavior =		= Add-on Behavior =

Mardak: /* Local State */ fix type of infoUrl

2010-10-12T21:07:07Z

Local State: fix type of infoUrl

← Older revision		Revision as of 21:07, 12 October 2010
Line 61:		Line 61:
	\|-		\|-
	! <tt>infoUrl</tt>		! <tt>infoUrl</tt>
	\| align=center \| <tt>~~[strings]~~</tt>		\| align=center \| <tt>string</tt>
	\| Information url from the last successful manifest (copied from the <tt>infoUrl</tt> property)		\| Information url from the last successful manifest (copied from the <tt>infoUrl</tt> property)
	\|-		\|-

Mardak: unify type align center styling

2010-10-12T21:06:06Z

unify type align center styling

← Older revision		Revision as of 21:06, 12 October 2010
Line 17:		Line 17:
	\|-		\|-
	! <tt>timestamp</tt>		! <tt>timestamp</tt>
	\| align="center" \| <tt>Date (string)</tt>		\| align=center \| <tt>Date (string)</tt>
	\| Time when the manifest was created		\| Time when the manifest was created
	\|-		\|-
	! <tt>uninstall</tt>		! <tt>uninstall</tt>
	\| align="center" \| <tt>[strings]</tt>		\| align=center \| <tt>[strings]</tt>
	\| Array of add-on id strings to uninstall		\| Array of add-on id strings to uninstall
	\|}		\|}
Line 31:		Line 31:
	{\| cellpadding=5		{\| cellpadding=5
	! <tt>hash</tt>		! <tt>hash</tt>
	\| <tt>string</tt>		\| align=center \| <tt>string</tt>
	\| Expected hash of the downloaded xpi structured as "<hash algorithm>:<hex hash value>" e.g., "sha256:a1b2c3..."		\| Expected hash of the downloaded xpi structured as "<hash algorithm>:<hex hash value>" e.g., "sha256:a1b2c3..."
	\|-		\|-
	! <tt>id</tt>		! <tt>id</tt>
	\| <tt>string</tt>		\| align=center \| <tt>string</tt>
	\| Add-on id to check if it's already installed locally		\| Add-on id to check if it's already installed locally
	\|-		\|-
	! <tt>url</tt>		! <tt>url</tt>
	\| <tt>string</tt>		\| align=center \| <tt>string</tt>
	\| URL to fetch the .xpi to install the add-on		\| URL to fetch the .xpi to install the add-on
	\|-		\|-
	! <tt>version</tt>		! <tt>version</tt>
	\| <tt>string</tt>		\| align=center \| <tt>string</tt>
	\| Version of the add-on to check if the local version is already current		\| Version of the add-on to check if the local version is already current
	\|}		\|}

Mardak: /* Local State */ preferences

2010-10-12T21:05:19Z

Local State: preferences

← Older revision		Revision as of 21:05, 12 October 2010
Line 52:		Line 52:

	= Local State =		= 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 <tt>extensions.sigma.</tt>:

			{\| cellpadding=5
			! <tt>disabledIds</tt>
			\| align=center \| <tt>[strings]</tt>
			\| Add-on ids of add-ons that were disabled when Sigma was disabled
			\|-
			! <tt>infoUrl</tt>
			\| align=center \| <tt>[strings]</tt>
			\| Information url from the last successful manifest (copied from the <tt>infoUrl</tt> property)
			\|-
			! <tt>installIds</tt>
			\| align=center \| <tt>[strings]</tt>
			\| Add-on ids from the last successful manifest (copied from the <tt>id</tt> property of the objects in the <tt>install</tt> property)
			\|-
			! <tt>signature</tt>
			\| align=center \| <tt>string</tt>
			\| Signature from the last successful manifest (copied from the <tt>.sig</tt> file)
			\|-
			! <tt>test</tt>
			\| align=center \| <tt>boolean</tt>
			\| User set preference to turn on testing against a test manifest/signature
			\|-
			! <tt>timestamp</tt>
			\| align=center \| <tt>Date (string)</tt>
			\| Timestamp from the last successful manifest (copied from the <tt>timestamp</tt> property)
			\|}

	= Add-on Behavior =		= Add-on Behavior =

Mardak: some wording in the intro and section headers

2010-10-12T20:54:20Z

some wording in the intro and section headers

← Older revision		Revision as of 20:54, 12 October 2010
Line 1:		Line 1:
	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.		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 ~~hosted~~ is hosted on https://sigma.mozillalabs.com/ that ~~control~~ 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.		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.

	= Manifest Structure =		= Manifest Structure =
Line 50:		Line 50:

	At the same level as the <tt>.json</tt> file, there must be a <tt>.sig</tt> file that contains the expected signature of the plain-text JSON manifest that is verified by the public key corresponding to the private key used to sign the manifest.		At the same level as the <tt>.json</tt> file, there must be a <tt>.sig</tt> file that contains the expected signature of the plain-text JSON manifest that is verified by the public key corresponding to the private key used to sign the manifest.

			= Local State =

			= Add-on Behavior =

Mardak: Initial sigma manifest description

2010-10-12T20:39:33Z

Initial sigma manifest description

New page

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 hosted is hosted on https://sigma.mozillalabs.com/ that control 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.

= Manifest Structure =

The manifest is a JSON file with file extension <tt>.json</tt> where the top level JS object has the following properties:

{| cellpadding=5
! <tt>infoUrl</tt>
| align=center | <tt>string</tt>
| Information url to open in a tab if different from the previous <tt>infoUrl</tt>
|-
! <tt>install</tt>
| align=center | <tt>[objects]</tt>
| Array of add-on objects to install (see below)
|-
! <tt>timestamp</tt>
| align="center" | <tt>Date (string)</tt>
| Time when the manifest was created
|-
! <tt>uninstall</tt>
| align="center" | <tt>[strings]</tt>
| Array of add-on id strings to uninstall
|}

== Install Add-on Object ==

The <tt>install</tt> array contains add-on objects with the following structure:

{| cellpadding=5
! <tt>hash</tt>
| <tt>string</tt>
| Expected hash of the downloaded xpi structured as "<hash algorithm>:<hex hash value>" e.g., "sha256:a1b2c3..."
|-
! <tt>id</tt>
| <tt>string</tt>
| Add-on id to check if it's already installed locally
|-
! <tt>url</tt>
| <tt>string</tt>
| URL to fetch the .xpi to install the add-on
|-
! <tt>version</tt>
| <tt>string</tt>
| Version of the add-on to check if the local version is already current
|}

== Manifest Signature ==

At the same level as the <tt>.json</tt> file, there must be a <tt>.sig</tt> file that contains the expected signature of the plain-text JSON manifest that is verified by the public key corresponding to the private key used to sign the manifest.