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 addons.mozilla.org (AMO) are signed as part of the review process, and a signing service is also offered. Additional information on the extension submission and signing process is available on MDN.

Algorithm

Extension signing is controlled by Mozilla and requires access to a private signing infrastructure exposed by AMO, and internal services like 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.

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=

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:

Signature-Version: 1.0
MD5-Digest-Manifest: OlmmwIHcPmhoIt4uMxdh8A==
SHA1-Digest-Manifest: 82zZH0Aq6GaTNMq+PnBlzep6fEA=

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 bug 1203787).

The 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:

$ 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

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 and Mozilla Extensions.

• 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 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
• Out-dated information about how XPIs were signed in the past: https://web.archive.org/web/20200105223104/https://developer.mozilla.org/en-US/docs/Archive/Add-ons/Signing_an_XPI

Documentation

• Introducing Extension Signing, Add-ons Blog.
• The Case for Extension Signing, Add-ons Blog.
• Main tracking bug.
• Signing and distributing your add-on, Extension Workshop.

Timeline

Check the 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 — which will be removed in a future release — 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 AMO, and there is a Signing API available for automated submission and retrieval of unlisted add-ons.

Unbranded Builds

Unbranded builds are available from the continuous integration builds on 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:

• release
• 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 98.0.1 - changeset 35fe60c82cf0) builds:

• Linux
• Mac OSX
• Windows 32-bit
• Windows 64-bit

Beta builds

Latest beta (Firefox 99.0b4 - changeset a466f13e839e) builds:

• Linux
• Mac OSX
• Windows 32-bit
• Windows 64-bit

FAQ

• Which add-on types will need to be signed?
  • Only extensions (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 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 Nightly and Developer Edition versions of Firefox have a preference to disable signature enforcement. There are also be special 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 xpinstall.signatures.required preference to "false".
    • type about:config into the URL bar in Firefox
    • in the Search box type xpinstall.signatures.required
    • double-click the preference, or right-click and selected "Toggle", to set it to false.

• How do the 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 xpinstall.signatures.required 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 Distribution Policy for more details.
  • You can also use the web-ext sign command to generate a signed XPI that can be self-hosted.
  • There is an 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 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 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 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 any of our communication channels.