View source for Add-ons/Extension Signing

Mozilla requires all extensions to be signed by Mozilla in order for them to be installable in Release and Beta versions of Firefox. Extensions submitted on [https://addons.mozilla.org/ addons.mozilla.org (AMO)] are signed as part of the review process, and a [http://addons-server.readthedocs.io/en/latest/topics/api/signing.html signing service] is also offered. Additional information on the extension submission and signing process is [https://developer.mozilla.org/en-US/Add-ons/Distribution available on MDN].

== Algorithm ==

Extension signing is controlled by Mozilla and requires access to a private signing infrastructure exposed by [https://addons.mozilla.org/ AMO], and internal services like [https://github.com/mozilla-services/autograph Autograph].

Add-ons and Extensions are XPI files (zip archives) where each file in the archives is hashed, and the manifest containing all the hashes is signed. When signing an extension, a manifest file containing the hash of each file in the XPI is first generated. The manifest file is stored in the signed XPI under '''META-INF/manifest.mf'''. The snippet below shows an example of manifest file.
<source>
Manifest-Version: 1.0

Name: install.rdf
Digest-Algorithms: MD5 SHA1
MD5-Digest: rzkfLZ5nC80leZsgMSGT3w==
SHA1-Digest: +43YVUxeOYeiJeOKeJaRdancg5I=

Name: bootstrap.js
Digest-Algorithms: MD5 SHA1
MD5-Digest: 2rUx2iRkGHx9yehpvoF2Wg==
SHA1-Digest: 7F7q7SUdOpxp7EYDFLENUqrNWMo=

Name: test.txt
Digest-Algorithms: MD5 SHA1
MD5-Digest: tT4aaxDCqRgFrpVHhe//Wg==
SHA1-Digest: 8mPWZnQPS9arW9Tu/vmC+JHgnYA=
</source>

A signature file is then created containing the hash of the manifest file (eg. `openssl dgst -binary -sha1 manifest.mf | base64`). The signature file is stored in the XPI under '''META-INF/mozilla.sf'''. An example is shown below:
<source>
Signature-Version: 1.0
MD5-Digest-Manifest: OlmmwIHcPmhoIt4uMxdh8A==
SHA1-Digest-Manifest: 82zZH0Aq6GaTNMq+PnBlzep6fEA=
</source>

A PKCS7 detached signature is computed on "mozilla.sf", using a signing certificate generated for each signature. The signing certificate, also called end-entity cert, is issued by an intermediate certificate of the Firefox private PKI. No special key usage or extended key usage is required in the end-entity cert, but its subject CN must match the add-on ID (for example, add-on ID test@tests.mozilla.org would have a cert CN set to that value).

Note: If the add-on ID is longer than 64 characters, we use the SHA256 hash of the add-on ID in the end-entity subject CN, to work around issues with long string in certificates (see [https://bugzilla.mozilla.org/show_bug.cgi?id=1203787 bug 1203787]).

The [https://tools.ietf.org/html/rfc2315 PKCS #7 (section 9.1 SignedData type)] signature is a binary file stored in the XPI under '''META-INF/mozilla.rsa'''. Because it is a standard PKCS7 signature, it can be verified using OpenSSL, as follows:
<source lang:bash>
$ openssl cms -verify -inform der -in META-INF/mozilla.rsa -content META-INF/mozilla.sf -CAfile test.addons.signing.root.ca.crt -purpose any
Signature-Version: 1.0
MD5-Digest-Manifest: OlmmwIHcPmhoIt4uMxdh8A==
SHA1-Digest-Manifest: 82zZH0Aq6GaTNMq+PnBlzep6fEA=

Verification successful
</source>

Both the end-entity and the intermediate certificates are also stored in the
SignedData.Certificates document. The root cert is not stored in the document
but shipped with Firefox directly.

When installing add-ons, Firefox does the following verifications:

* verify the signature of `mozilla.sf` using `mozilla.rsa`
* verify the signing cert chains back to the Firefox Root CA
* verify the hash of `manifest.mf` matches the hash stored in `mozilla.sf`
* verify the hashes of all files in the XPI match the hashes stored in `manifest.mf`
* verify all files in the XPI are listed in `manifest.mf`

=== Signing of special add-ons ===
There are three special cases of add-ons developed by Mozilla: System add-ons, Mozilla Extensions and Hotfixes.

* If the add-on is a system add-on, the Organizational Unit (OU) of the end-entity certificate must be set to "Mozilla Components".
* If the add-on is a Mozilla Extension, the OU of the EE cert must be set to "Mozilla Extensions".
* If the add-on is a hotfix, the add-on ID must match the pref `extensions.hotfix.id` (currently `firefox-hotfix@mozilla.org`) and the public key hash of the end-entity cert must match the fingerprints set in `extensions.hotfix.certs.1.sha1Fingerprint` or `extensions.hotfix.certs.2.sha1Fingerprint`.
* If the add-on is signed with the staging root, in Nightly you need to set the pref `xpinstall.signatures.dev-root = true` to tell Firefox to verify it

refs:
* https://searchfox.org/mozilla-central/source/toolkit/mozapps/extensions/internal/XPIProvider.jsm
* https://developer.mozilla.org/en-US/docs/Signing_a_XPI

== Documentation ==
* [https://blog.mozilla.org/addons/2015/02/10/extension-signing-safer-experience/ Introducing Extension Signing], Add-ons Blog.
* [https://blog.mozilla.org/addons/2015/04/15/the-case-for-extension-signing/ The Case for Extension Signing], Add-ons Blog.
* [https://bugzilla.mozilla.org/show_bug.cgi?id=signed-addons Main tracking bug].

== Timeline ==
Check the [[RapidRelease/Calendar|Firefox Release Calendar]] for specific dates. The following timelines are for Desktop:

* '''Firefox 40-42''': Firefox warns about signatures but doesn't enforce them.
* '''Firefox 43''': Firefox enforces the use of signatures by default, but has a preference that allows signature enforcement to be disabled (''xpinstall.signatures.required'' in about:config).
* '''Firefox 48''': (Pushed from Firefox 46). Release and Beta versions of Firefox for Desktop will not allow unsigned extensions to be installed, with no override. Firefox for Android will enforce add-on signing, and will retain a preference &mdash; which will be removed in a future release &mdash; to allow the user to disable signing enforcement.

The first ESR version to include signing support will be the Firefox ESR 52 release. 

All Firefox extensions - for Desktop and Android - on AMO that have passed review are now signed.

For unlisted (non-AMO) add-ons, submission and signing is active through [https://addons.mozilla.org AMO], and there is a [https://blog.mozilla.org/addons/2015/11/20/signing-api-now-available/ Signing API available] for automated submission and retrieval of unlisted add-ons.

== Unbranded Builds ==

Unbranded builds are available from the continuous integration builds on [https://treeherder.mozilla.org/#/jobs?repo=mozilla-beta treeherder.mozilla.org]. 
Make sure to download those builds from each OS which has the string addon next to it,  select '''B''', then the Artifacts tab on the bottom and then download the required format target.zip, target.tar.bz2 or target.dmg for the required OS.  Links to the latest beta and release builds are below. If they are outdated (they are not updated automatically), you can find builds yourself using the following links:

* [https://treeherder.mozilla.org/#/jobs?repo=mozilla-release&searchStr=addon release]
* [https://treeherder.mozilla.org/#/jobs?repo=mozilla-beta&searchStr=addon beta] (you may need to grow the list of changesets if there have been lots of locale updates, using the "10" or "20" buttons at the bottom of the page)

=== Latest Builds ===

'''Note:''' All Windows, Linux and Mac builds have a filename of target.zip, target.tar.bz2 and target.dmg, respectively. This is normal, and a result of the build process. 

'''Release builds''' 

Latest release (Firefox 93.0 - [https://hg.mozilla.org/releases/mozilla-release/rev/08b69dc588fb changeset 08b69dc588fb]) builds:

* [https://firefox-ci-tc.services.mozilla.com/api/queue/v1/task/cbKUieAqRYyoNbVrflZVRg/runs/0/artifacts/public/build/target.tar.bz2 Linux]
* [https://firefox-ci-tc.services.mozilla.com/api/queue/v1/task/Oi22_AXDQMeIkk_Ss2qjPw/runs/0/artifacts/public/build/target.dmg Mac OSX]
* [https://firefox-ci-tc.services.mozilla.com/api/queue/v1/task/BKmAuup_QLKKUs-ayAbTFQ/runs/0/artifacts/public/build/target.zip Windows 32-bit]
* [https://firefox-ci-tc.services.mozilla.com/api/queue/v1/task/FjFcSEFBQZS9SaEA_3g_3A/runs/0/artifacts/public/build/target.zip Windows 64-bit]

'''Beta builds'''

Latest beta (Firefox 94.0b1 - [https://hg.mozilla.org/releases/mozilla-beta/rev/8822ebbbec32 changeset 8822ebbbec32]) builds:

* [https://firefox-ci-tc.services.mozilla.com/api/queue/v1/task/Ieho7PywRouys_uMUMxeHw/runs/0/artifacts/public/build/target.tar.bz2 Linux]
* [https://firefox-ci-tc.services.mozilla.com/api/queue/v1/task/ccxfh1zfQrSbsOOxTtRRdg/runs/0/artifacts/public/build/target.dmg Mac OSX]
* [https://firefox-ci-tc.services.mozilla.com/api/queue/v1/task/Vlgxe43OTG-9rZNVqbqpcA/runs/0/artifacts/public/build/target.zip Windows 32-bit]
* [https://firefox-ci-tc.services.mozilla.com/api/queue/v1/task/bzIQ2oLSTwyWBXwDyHlqAw/runs/0/artifacts/public/build/target.zip Windows 64-bit]

== FAQ ==
* Which add-on types will need to be signed?
** Only extensions ([https://developer.mozilla.org/en-US/Add-ons/Install_Manifests#type type 2] in install.rdf)--this includes WebExtensions. Themes, dictionaries, language packs, and plugins don't need to be signed.

* Will other applications like Thunderbird, Seamonkey, Palemoon, etc. require extensions to be signed?
** The leaders of each of those projects will decide if they want to enforce signing, keep it as a setting, or deactivate it by default. We haven't heard about any other applications planning to support this.

* Will signed extensions work on other applications or older versions of Firefox?
** Yes, the signature system is built on top of the [https://developer.mozilla.org/en-US/docs/Signing_a_XPI existing add-on signing feature], which has been supported in Firefox and other applications.

* Will there be a setting or other overrides to disable signature checks?
** Firefox Release and Beta versions will not have any way to disable signature checks.  Signature checks can be disabled in other versions, as described in detail below.

* What are my options if I want to install unsigned extensions in Firefox?
** The [https://nightly.mozilla.org/ Nightly] and [https://www.mozilla.org/firefox/developer/ Developer Edition] versions of Firefox have a preference to disable signature enforcement. There are also be special [https://wiki.mozilla.org/Add-ons/Extension_Signing#Unbranded_Builds unbranded versions of Release and Beta] that have this preference, so that add-on developers can work on their add-ons without having to sign every build. To disable signature checks, you will need to set the <code>xpinstall.signatures.required</code> preference to "false".
*** type <code>about:config</code> into the URL bar in Firefox
*** in the Search box type <code>xpinstall.signatures.required</code>
*** double-click the preference, or right-click and selected "Toggle", to set it to <code>false</code>.

* How do the [[Add-ons/Extension_Signing#Unbranded_Builds|unbranded versions of Firefox]] work?
** They work just like Firefox, with two differences: they have a setting to disable mandatory signature checks, and they don't have the Firefox name and logo (instead using a generic name and logo). These builds are available in the en-US locale only.

* What about private add-ons used in enterprise environments?
** The ESR release supports signing starting with version 45-based releases. Signing enforcement is enabled by default in these releases, and enforcement can be disabled using the <code>xpinstall.signatures.required</code> preference.

* How do I get my add-ons signed if they are hosted on addons.mozilla.org (AMO)?
** No action is required.  We automatically signed reviewed versions of all add-ons currently hosted on AMO. All new versions will be signed automatically after they pass review. 

* How do I get my add-ons signed if they are not hosted on addons.mozilla.org (AMO)?
** You will need to create an AMO account and submit your add-on. There will be an option where you indicate the add-on won't be listed on AMO, and you'll be able to submit your add-on files without having them published on the site. Please read the [https://developer.mozilla.org/en-US/Add-ons/Distribution Distribution Policy] for more details.
** You can also use the [https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#web-ext-sign web-ext sign] command to generate a signed XPI that can be self-hosted.
** There is an [https://addons-server.readthedocs.io/en/latest/topics/api/signing.html API you can use] for signing.

* How does the signing process work for unlisted add-ons?
** For unlisted add-ons, files submitted for signing go through an automated review process. If they pass this review, they are automatically signed and a download link is sent back to the developer. This process should normally take seconds.
** There is an [https://addons-server.readthedocs.io/en/latest/topics/api/signing.html API you can use] for signing.

* Will I need to sign the custom version of an existing add-on I created with my own code changes, locale additions, etc.?
** If you use it on Release or Beta, yes. You will also need to change the add-on ID in order to submit it for signing.

* Is this a way for Mozilla to censor add-ons they don't like, enforce copyright, government demands, etc.?
** No, the purpose of this is to protect users from malicious add-ons. We have [https://developer.mozilla.org/en-US/Add-ons/AMO/Policy/Reviews a set of guidelines] for when it is appropriate to blocklist an add-on and have refused multiple times to block for other reasons.

* Will there be an upload and signing API so I don't have to manually upload each new version of the add-on?
** Yes. The [https://addons-server.readthedocs.io/en/latest/topics/api/signing.html signing API is documented here].

* Will this protect users against all forms of add-on malware?
** No, there is no perfect solution for this. Fighting malware requires defenses on many levels: operating system,, application, user, and even industry. Extension signing is a big step in protecting Firefox against malicious add-ons, but there is much more to do in other fronts to ensure the best experience for our users.

== Feedback and Questions ==
For questions about signing, you can use [https://developer.mozilla.org/en-US/Add-ons#Contact_us any of our communication channels].