signing_macos_build.rst (8041B)
1 Signing Local macOS Builds 2 ========================== 3 4 Background 5 ---------- 6 Firefox for macOS is mainly signed in one of two different ways: one for 7 production releases, and one for builds that run on try. Typically, developers 8 testing local builds don’t need to be concerned with signing unless they are 9 working on an area specifically affected by macOS entitlements such as passkeys, 10 loading third party libraries, or adding a new process type. However, it is 11 good practice to test builds that are as close as possible to the production 12 configuration or the try server configuration. Local builds are not signed 13 automatically and mach doesn’t include support for running tests on signed 14 builds. However, the mach command ``macos-sign`` can be used to sign local 15 packaged builds for manual testing. ``macos-sign`` supports signing builds to 16 match try or production builds. 17 18 Note: On Apple Silicon Macs, where all executables are required to be 19 signed, Firefox binaries will be “ad-hoc” self-signed automatically by the 20 linker during compilation, but this is a per-binary sign with no 21 Firefox-specific runtime settings or entitlements. This document ignores 22 automatic signing. 23 24 To sign your own local build so that it has the same set of entitlements as a 25 production release requires a signing certificate and provisioning profile 26 issued from Mozilla’s Apple Developer account. Entitlements are used to grant 27 Firefox certain permissions as well as impose security restrictions when it is 28 run on macOS. Some entitlements are considered restricted and can only be 29 enabled when signed by a certificate from an account that has been granted 30 permission to use the entitlement, such as the passkey macOS entitlement. As an 31 example of the production restrictions, production builds use an entitlement 32 that disallows debugger attachment. Disallowing debuggers is required for 33 distribution because it is required by the Notarization system. When signing 34 locally, developers can modify entitlements as needed. 35 36 Summary 37 ------- 38 39 **Production build:** requires Mozilla's official Apple Developer ID 40 certificate, private key, and provisioning profile. Only Mozilla Release 41 Engineering has access to the official Developer ID certificate and private key. 42 Mozilla developers can request a limited-use Apple *Developer* certificate which 43 can be used to generated production-like builds for local testing. See 44 :ref:`like-prod` below. 45 46 **Developer build:** requires generating a self-signed certificate (to sign 47 like a try push is signed) or using ad-hoc signing (no setup required and only 48 usable locally), will have no passkey support (or any other restricted 49 entitlement), has fewer restrictions with respect to module loading, is 50 debuggable. 51 52 Signing Your Build Like try 53 --------------------------- 54 To sign your own local build with entitlements that match what is used for try 55 push automated testing, generate a self-signed code signing certificate using 56 the macOS Keychain Access application. During the process, supply a unique name 57 not used by other Keychain entries making sure to not use any spaces. For 58 example, ``my-firefox-selfsign-cert-2024``. This string will be used as 59 the signing identity and passed to ``macos-sign`` with the ``-s`` option. 60 ``./mach`` passes this to the codesign command which looks up the entry in the 61 keychain. When running the signing command, you'll be prompted to allow 62 ``codesign`` to access the keychain entry. Select ``Always Allow`` when 63 prompted. 64 65 .. code-block:: shell 66 67 $ ./mach build package 68 $ open <path-to-dmg> 69 <drag Browser to the Desktop> 70 $ ./mach macos-sign -s my-firefox-selfsign-cert-2024 -a ~/Desktop/Nightly.app 71 72 The entitlements in the tree used for this configuration are labeled as 73 developer and we call this the developer build. Developer signed builds differ 74 from production signed in the following ways: 75 76 * They allow debugger attachment 77 * They allow loading of third party libraries in all processes 78 * They respect dyld environment variables 79 * They don’t include restricted entitlements such as the passkey entitlement 80 (and therefore passkeys can’t be used) 81 82 Ad-hoc Signing Your Build - Like try Signing, but Requires no Configuration and is For Local Use Only 83 ----------------------------------------------------------------------------------------------------- 84 Omitting the ``-s`` option will use ad-hoc signing which requires no setup. The 85 build will be more limited than builds signed with a self-signed cert. Ad-hoc 86 signed builds are not verifiable or runnable on any other system. There is 87 little documentation available about the limitations. 88 89 .. code-block:: shell 90 91 $ ./mach build package 92 $ open <path-to-dmg> 93 <drag Browser to the Desktop> 94 $ ./mach macos-sign -a ~/Desktop/Nightly.app 95 96 .. _like-prod: 97 98 Signing Your Build Like Production 99 ---------------------------------- 100 To sign your local build like a production Firefox build, you’ll need an Apple 101 Developer signing certificate and provisioning profile issued from Mozilla's 102 Apple Developer account. Developers will be given a development-role login 103 allowing a signing certificate and provisioning profile to be generated. The 104 provisioning profile used with Development certificates limits the signed 105 application to Mozilla developer machines via a hardware ID. Employees can file 106 a bug `here <https://bugzilla.mozilla.org/enter_bug.cgi?product=App%20Stores&component=App%20Store%20Access>`__ 107 to request an account. 108 109 Once the developer's Apple account is setup as a member 110 of Mozilla's Apple account, Xcode can be used to download a Developer signing 111 certificate and provisioning profile for development use. See 112 :doc:`Configure Development Certificate <../signing/configure_development_certificate>` 113 for instructions on how to set up a development certificate and provisioning 114 profile using Xcode. Use Keychain Access to get the codesigning identifier for 115 your development cert which should be passed as the ``-s`` codesigning identity 116 to ``mach macos-sign``: 117 118 .. code-block:: shell 119 120 $ ./mach build package 121 $ open <path-to-dmg> 122 <drag Browser to the Desktop> 123 $ ./mach macos-sign -a ~/Desktop/Nightly.app -s <MOZILLA_DEVELOPER_CERT_ID> -e production 124 125 Example: Re-Signing Official Nightly 126 ------------------------------------ 127 128 .. code-block:: shell 129 130 $ ditto /Applications/Firefox\ Nightly.app ~/Desktop/FirefoxNightly.app 131 $ ./mach macos-sign -a ~/Desktop/FirefoxNightly.app 132 0:00.20 Using ad-hoc signing identity 133 0:00.20 Using nightly channel signing configuration 134 0:00.20 Using developer entitlements 135 0:00.20 Reading build config file /Users/me/r/mc/taskcluster/config.yml 136 0:00.23 Stripping existing xattrs and signatures 137 0:01.91 Signing with codesign 138 0:02.72 Verification of signed app /Users/me/Desktop/FirefoxNightly.app OK 139 140 Example: Re-Signing Official Developer Edition With `rcodesign <https://crates.io/crates/apple-codesign>`__ Using a pkcs12 Certificate Key Pair 141 ----------------------------------------------------------------------------------------------------------------------------------------------- 142 143 More information about rcodesign can be found on the 144 `rust crate page <https://crates.io/crates/apple-codesign>`__ or 145 `github repo <https://github.com/indygreg/apple-platform-rs>`__. Certificates 146 can be exported from Keychain Access in .p12 format. 147 148 .. code-block:: shell 149 150 $ ditto /Applications/Firefox\ Developer\ Edition.app/ ~/Desktop/DevEdition.app 151 $ ./mach macos-sign -r -a ~/Desktop/DevEdition.app \ 152 --rcodesign-p12-file ./myDevId.p12 \ 153 --rcodesign-p12-password-file ./myDevId.p12.passwd 154 0:00.26 Using pkcs12 signing identity 155 0:00.26 Using devedition channel signing configuration 156 0:00.26 Using developer entitlements 157 0:00.26 Reading build config file /Users/me/r/mc/taskcluster/config.yml 158 0:00.29 Stripping existing xattrs and signatures 159 0:02.09 Signing with rcodesign 160 0:11.16 Verification of signed app /Users/me/Desktop/DevEdition.app OK