signing.rst (9234B)
1 Signing 2 ======= 3 4 Overview 5 -------- 6 7 Our `code signing`_ happens in discrete tasks, for both performance reasons 8 and to limit which machines have access to the signing servers and keys. 9 10 In general, the binary-to-be-signed is generated in one task, and the request 11 to sign it is in a second task. We verify the request via the `chain of trust`_, 12 sign the binary, then upload the signed binary or original binary + detached 13 signature as artifacts. 14 15 How the Task Works 16 ------------------ 17 18 Scriptworker_ verifies the task definition and the upstream tasks until it 19 determines the graph comes from a trusted tree; this is `chain of trust`_ 20 verification. Part of this verification is downloading and verifying the shas 21 of the ``upstreamArtifacts`` in the task payload. 22 23 An example signing task payload: 24 25 :: 26 27 { 28 "payload": { 29 "upstreamArtifacts": [{ 30 "paths": ["public/build/target.dmg"], 31 "formats": ["macapp"], 32 "taskId": "abcde", 33 "taskType": "build" 34 }, { 35 "paths": ["public/build/target.tar.gz"], 36 "formats": ["gcp_prod_autograph_gpg"], 37 "taskId": "12345", 38 "taskType": "build" 39 }] 40 } 41 } 42 43 In the above example, scriptworker would download the ``target.dmg`` from task 44 ``abcde`` and ``target.tar.gz`` from task ``12345`` and verify their shas and 45 task definitions via `chain of trust`_ verification. Then it will launch 46 `signingscript`_, which requests a signing token from the signing server pool. 47 48 Signingscript determines it wants to sign ``target.dmg`` with the ``macapp`` 49 format, and ``target.tar.gz`` with the ``gcp_prod_autograph_gpg`` format. Each 50 of the `signing formats`_ has their own behavior. After performing any 51 format-specific checks or optimizations, it calls `signtool`_ to submit the 52 file to the signing servers and poll them for signed output. Once it downloads 53 all of the signed output files, it exits and scriptworker uploads the signed 54 binaries. 55 56 We can specify multiple paths from a single task for a given set of formats, 57 and multiple formats for a given set of paths. 58 59 Signing kinds 60 ------------- 61 62 We currently have multiple signing kinds. These fall into several categories: 63 64 **Build internal signing**: Certain package types require the internals to be signed. 65 For certain package types, e.g. exe or dmg, we extract the internal binaries 66 (e.g. xul.dll) and sign them. This is true for certain zipfiles, exes, and dmgs; 67 we need to sign the internals before we [re]create the package. For linux 68 tarballs, we don't need special packaging, so we can sign everything in this 69 task. These kinds include ``build-signing``, ``shippable-l10n-signing``, 70 ``release-eme-free-repack-signing``, and ``release-partner-repack-signing``. 71 72 **Build repackage signing**: Once we take the signed internals and package them 73 (known as a ``repackage``), certain formats require a signed external package. 74 If we have created an update MAR file from the signed internals, the MAR 75 file will also need to be signed. These kinds include ``repackage-signing``, 76 ``release-eme-free-repack-repackage-signing``, and ``release-partner-repack-repackage-signing``. 77 78 ``release-source-signing`` and ``partials-signing`` sign the release source tarball 79 and partial update MARs. 80 81 **Mac signing and notarization**: For mac, we have ``*-mac-signing``, which signs the app and pkg, ``*-mac-notarization`` submits to Apple and staples the resulting ticket to the binaries. 82 83 We generate signed checksums at the top of the releases directories, like 84 in `60.0`_. To generate these, we have the checksums signing kinds, including 85 ``release-generate-checksums-signing``, ``checksums-signing``, and 86 ``release-source-checksums-signing`` 87 88 .. _signing formats: 89 90 Signing formats 91 --------------- 92 93 The known signingscript formats are listed in the fourth column of the 94 `signing password files`_. 95 96 The formats are specified in the ``upstreamArtifacts`` list-of-dicts. 97 ``gcp_prod_autograph_gpg`` signing results in a detached ``.asc`` signature 98 file. Because of its nature, we gpg-sign at the end if given multiple formats 99 for a given set of files. 100 101 ``jar`` signing is Android apk signing. After signing, we ``zipalign`` the apk. 102 This includes the ``focus-jar`` format, which is just a way to specify a different 103 set of keys for the Focus app. 104 105 ``macapp`` signing accepts either a ``dmg`` or ``tar.gz``; it converts ``dmg`` 106 files to ``tar.gz`` before submitting to the signing server. The signed binary 107 is a ``tar.gz``. 108 109 ``authenticode`` signing takes individual binaries or a zipfile. We sign the 110 individual file or internals of the zipfile, skipping any already-signed files 111 and a select few blocklisted files (using the `should_sign_windows`_ function). 112 It returns a signed individual binary or zipfile with signed internals, depending 113 on the input. This format includes ``gcp_prod_autograph_authenticode_202412``, 114 and ``gcp_prod_autograph_authenticode_202412_stub``. 115 116 ``mar`` signing signs our update files (Mozilla ARchive). ``mar_sha384`` is 117 the same, but with a different hashing algorithm. 118 119 ``gcp_prod_autograph_widevine`` is also video-related; see the 120 `widevine site`_. We sign specific files inside the package and rebuild the 121 ``precomplete`` file that we use for updates. 122 123 Cert levels 124 ----------- 125 126 Cert levels are how we separate signing privileges. We have the following levels: 127 128 ``dep`` is short for ``depend``, which is a term from the Netscape days. (This 129 refers to builds that don't clobber, so they keep their dependency object files 130 cached from the previous build.) These certs and keys are designed to be used 131 for Try or on-push builds that we don't intend to ship. Many of these are 132 self-signed and not of high security value; they're intended for testing 133 purposes. 134 135 ``nightly`` refers to the Nightly product and channel. We use these keys for 136 signing and shipping nightly builds, as well as Devedition on the beta channel. 137 Because these are shipping keys, they are restricted; only a subset of branches 138 can request the use of these keys. 139 140 ``release`` refers to our releases, off the beta, release, or esr channels. 141 These are the most restricted keys. 142 143 We request a certain cert level via scopes: 144 ``project:releng:signing:cert:dep-signing``, 145 ``project:releng:signing:cert:nightly-signing``, or 146 ``project:releng:signing:cert:release-signing``. Each signing task is required 147 to have exactly one of those scopes, and only nightly- and release-enabled 148 branches are able to use the latter two scopes. If a task is scheduled with one 149 of those restricted scopes on a non-allowlisted branch, Chain of Trust 150 verification will raise an exception. 151 152 Signing scriptworker workerTypes 153 -------------------------------- 154 155 The `linux-depsigning`_ pool handles all of the non-mac dep signing. These are 156 heavily in use on try and autoland, but also other branches. These verify 157 the `chain of trust`_ artifact but not its signature, and they don't have a 158 gpg key to sign their own chain of trust artifact. This is by design; the chain 159 of trust should and will break if a production scriptworker is downstream from 160 a depsigning worker. 161 162 The `linux-signing`_ pool is the production signing pool; it handles the 163 nightly- and release- signing requests. As such, it verifies the upstream 164 chain of trust and all signatures, and signs its chain of trust artifact. 165 166 The `linux-devsigning`_ pool is intended for signingscript and scriptworker 167 development use. Because it isn't used on any Firefox-developer-facing branch, 168 Mozilla Releng is able to make breaking changes on this pool without affecting 169 any other team. 170 171 Similarly, we have the `mac-depsigning`_ and `mac-signing`_ pools, which handle 172 CI and nightly/release signing, respectively. 173 174 .. _60.0: https://archive.mozilla.org/pub/firefox/releases/60.0/ 175 .. _addonscript: https://github.com/mozilla-releng/addonscript/ 176 .. _code signing: https://en.wikipedia.org/wiki/Code_signing 177 .. _chain of trust: https://scriptworker.readthedocs.io/en/latest/chain_of_trust.html 178 .. _linux-depsigning: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-k8s/worker-types/gecko-t-signing 179 .. _should_sign_windows: https://github.com/mozilla-releng/signingscript/blob/65cbb99ea53896fda9f4844e050a9695c762d24f/signingscript/sign.py#L369 180 .. _Encrypted Media Extensions: https://hacks.mozilla.org/2014/05/reconciling-mozillas-mission-and-w3c-eme/ 181 .. _signing password files: https://github.com/mozilla/build-puppet/tree/feff5e12ab70f2c060b29940464e77208c7f0ef2/modules/signing_scriptworker/templates 182 .. _signingscript: https://github.com/mozilla-releng/signingscript/ 183 .. _linux-devsigning: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-k8s/worker-types/gecko-t-signing-dev 184 .. _linux-signing: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-k8s/worker-types/gecko-3-signing 185 .. _mac-depsigning: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-prov-v1/worker-types/depsigning-mac-v1 186 .. _mac-signing: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-prov-v1/worker-types/signing-mac-v1 187 .. _signtool: https://github.com/mozilla-releng/signtool 188 .. _Scriptworker: https://github.com/mozilla-releng/scriptworker/ 189 .. _widevine site: https://www.widevine.com/wv_drm.html