summaryrefslogtreecommitdiffstats
path: root/docs/contributing
diff options
context:
space:
mode:
Diffstat (limited to 'docs/contributing')
-rw-r--r--docs/contributing/index.rst8
-rw-r--r--docs/contributing/reviews.rst6
-rw-r--r--docs/contributing/signing/signing_macos_build.rst155
3 files changed, 169 insertions, 0 deletions
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
index 545e161f8e..3321b7f5f4 100644
--- a/docs/contributing/index.rst
+++ b/docs/contributing/index.rst
@@ -42,6 +42,14 @@ development process and source code documentation.
.. toctree::
+ :caption: Signing
+ :maxdepth: 1
+ :glob:
+
+ signing/*
+
+
+.. toctree::
:caption: Additional Information
:maxdepth: 1
diff --git a/docs/contributing/reviews.rst b/docs/contributing/reviews.rst
index d2424724a2..8cd968ced3 100644
--- a/docs/contributing/reviews.rst
+++ b/docs/contributing/reviews.rst
@@ -68,6 +68,9 @@ Review groups
* - #firefox-svg-reviewers
- SVG-related changes
- `Member list <https://phabricator.services.mozilla.com/project/members/97/>`__
+ * - #android-reviewers
+ - Changes to Fenix, Focus and Android Components.
+ - `Member list <https://phabricator.services.mozilla.com/project/members/200/>`__
* - #geckoview-reviewers
- Changes to GeckoView
- `Member list <https://phabricator.services.mozilla.com/project/members/92/>`__
@@ -131,6 +134,9 @@ Review groups
* - #style or #firefox-style-system-reviewers
- Firefox style system (servo, layout/style).
- `Member list <https://phabricator.services.mozilla.com/project/members/90/>`__
+ * - #supply-chain-reviewers
+ - Changes to third-party audits and vendoring (cargo-vet, supply_chain).
+ - `Member list <https://phabricator.services.mozilla.com/project/members/164/>`__
* - #webcompat-reviewers
- System addons maintained by the Web Compatibility team
- `Member list <https://phabricator.services.mozilla.com/project/members/124/>`__
diff --git a/docs/contributing/signing/signing_macos_build.rst b/docs/contributing/signing/signing_macos_build.rst
new file mode 100644
index 0000000000..688a935bbe
--- /dev/null
+++ b/docs/contributing/signing/signing_macos_build.rst
@@ -0,0 +1,155 @@
+Signing Local macOS Builds
+==========================
+
+Background
+----------
+Firefox for macOS is mainly signed in one of two different ways: one for
+production releases, and one for builds that run on try. Typically, developers
+testing local builds don’t need to be concerned with signing unless they are
+working on an area specifically affected by macOS entitlements such as passkeys,
+loading third party libraries, or adding a new process type. However, it is
+good practice to test builds that are as close as possible to the production
+configuration or the try server configuration. Local builds are not signed
+automatically and mach doesn’t include support for running tests on signed
+builds. However, the mach command ``macos-sign`` can be used to sign local
+packaged builds for manual testing. ``macos-sign`` supports signing builds to
+match try or production builds.
+
+ Note: On Apple Silicon Macs, where all executables are required to be
+ signed, Firefox binaries will be “ad-hoc” self-signed automatically by the
+ linker during compilation, but this is a per-binary sign with no
+ Firefox-specific runtime settings or entitlements. This document ignores
+ automatic signing.
+
+To sign your own local build so that it has the same set of entitlements as a
+production release requires a signing certificate and provisioning profile
+issued from Mozilla’s Apple Developer account. Entitlements are used to grant
+Firefox certain permissions as well as impose security restrictions when it is
+run on macOS. Some entitlements are considered restricted and can only be
+enabled when signed by a certificate from an account that has been granted
+permission to use the entitlement, such as the passkey macOS entitlement. As an
+example of the production restrictions, production builds use an entitlement
+that disallows debugger attachment. Disallowing debuggers is required for
+distribution because it is required by the Notarization system. When signing
+locally, developers can modify entitlements as needed.
+
+Summary
+-------
+
+**Production build:** requires Mozilla's official Apple Developer ID
+certificate, private key, and provisioning profile. Only Mozilla Release
+Engineering has access to the official Developer ID certificate and private key.
+Mozilla developers can request a limited-use Apple *Developer* certificate which
+can be used to generated production-like builds for local testing. See
+:ref:`like-prod` below.
+
+**Developer build:** requires generating a self-signed certificate (to sign
+like a try push is signed) or using ad-hoc signing (no setup required and only
+usable locally), will have no passkey support (or any other restricted
+entitlement), has fewer restrictions with respect to module loading, is
+debuggable.
+
+Signing Your Build Like try
+---------------------------
+To sign your own local build with entitlements that match what is used for try
+push automated testing, generate a self-signed code signing certificate using
+the macOS Keychain Access application. During the process, supply a unique name
+not used by other Keychain entries making sure to not use any spaces. For
+example, ``my-firefox-selfsign-cert-2024``. This string will be used as
+the signing identity and passed to ``macos-sign`` with the ``-s`` option.
+``./mach`` passes this to the codesign command which looks up the entry in the
+keychain. When running the signing command, you'll be prompted to allow
+``codesign`` to access the keychain entry. Select ``Always Allow`` when
+prompted.
+
+.. code-block:: shell
+
+ $ ./mach build package
+ $ open <path-to-dmg>
+ <drag Browser to the Desktop>
+ $ ./mach macos-sign -s my-firefox-selfsign-cert-2024 -a ~/Desktop/Nightly.app
+
+The entitlements in the tree used for this configuration are labeled as
+developer and we call this the developer build. Developer signed builds differ
+from production signed in the following ways:
+
+* They allow debugger attachment
+* They allow loading of third party libraries in all processes
+* They respect dyld environment variables
+* They don’t include restricted entitlements such as the passkey entitlement
+ (and therefore passkeys can’t be used)
+
+Ad-hoc Signing Your Build - Like try Signing, but Requires no Configuration and is For Local Use Only
+-----------------------------------------------------------------------------------------------------
+Omitting the ``-s`` option will use ad-hoc signing which requires no setup. The
+build will be more limited than builds signed with a self-signed cert. Ad-hoc
+signed builds are not verifiable or runnable on any other system. There is
+little documentation available about the limitations.
+
+.. code-block:: shell
+
+ $ ./mach build package
+ $ open <path-to-dmg>
+ <drag Browser to the Desktop>
+ $ ./mach macos-sign -a ~/Desktop/Nightly.app
+
+.. _like-prod:
+
+Signing Your Build Like Production
+----------------------------------
+To sign your local build like a production Firefox build, you’ll need an Apple
+Developer signing certificate and provisioning profile issued from Mozilla's
+Apple Developer account. Developers will be given a development-role login
+allowing a signing certificate and provisioning profile to be generated. The
+provisioning profile used with Development certificates limits the signed
+application to Mozilla developer machines via a hardware ID. Employees can file
+a bug `here <https://bugzilla.mozilla.org/enter_bug.cgi?product=App%20Stores&component=App%20Store%20Access>`__
+to request an account. Once the developer's Apple account is setup as a member
+of Mozilla's Apple account, Xcode can be used to download a Developer signing
+certificate and provisioning profile for development use. Use Keychain Access to
+get the codesigning identifier for your development cert which should be passed
+as the ``-s`` codesigning identity to ``mach macos-sign``:
+
+.. code-block:: shell
+
+ $ ./mach build package
+ $ open <path-to-dmg>
+ <drag Browser to the Desktop>
+ $ ./mach macos-sign -a ~/Desktop/Nightly.app -s <MOZILLA_DEVELOPER_CERT_ID>
+
+Example: Re-Signing Official Nightly
+------------------------------------
+
+.. code-block:: shell
+
+ $ ditto /Applications/Firefox\ Nightly.app ~/Desktop/FirefoxNightly.app
+ $ ./mach macos-sign -a ~/Desktop/FirefoxNightly.app
+ 0:00.20 Using ad-hoc signing identity
+ 0:00.20 Using nightly channel signing configuration
+ 0:00.20 Using developer entitlements
+ 0:00.20 Reading build config file /Users/me/r/mc/taskcluster/ci/config.yml
+ 0:00.23 Stripping existing xattrs and signatures
+ 0:01.91 Signing with codesign
+ 0:02.72 Verification of signed app /Users/me/Desktop/FirefoxNightly.app OK
+
+Example: Re-Signing Official Developer Edition With `rcodesign <https://crates.io/crates/apple-codesign>`__ Using a pkcs12 Certificate Key Pair
+-----------------------------------------------------------------------------------------------------------------------------------------------
+
+More information about rcodesign can be found on the
+`rust crate page <https://crates.io/crates/apple-codesign>`__ or
+`github repo <https://github.com/indygreg/apple-platform-rs>`__. Certificates
+can be exported from Keychain Access in .p12 format.
+
+.. code-block:: shell
+
+ $ ditto /Applications/Firefox\ Developer\ Edition.app/ ~/Desktop/DevEdition.app
+ $ ./mach macos-sign -r -a ~/Desktop/DevEdition.app \
+ --rcodesign-p12-file ./myDevId.p12 \
+ --rcodesign-p12-password-file ./myDevId.p12.passwd
+ 0:00.26 Using pkcs12 signing identity
+ 0:00.26 Using devedition channel signing configuration
+ 0:00.26 Using developer entitlements
+ 0:00.26 Reading build config file /Users/me/r/mc/taskcluster/ci/config.yml
+ 0:00.29 Stripping existing xattrs and signatures
+ 0:02.09 Signing with rcodesign
+ 0:11.16 Verification of signed app /Users/me/Desktop/DevEdition.app OK