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