taskcluster/docs/signing.rst

   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": ["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 ``autograph_gpg`` format. Each of the
  50 `signing formats`_ has their own behavior. After performing any format-specific
  51 checks or optimizations, it calls `signtool`_ to submit the file to the signing
  52 servers and poll them for signed output. Once it downloads all of the signed
  53 output files, it exits and scriptworker uploads the signed binaries.
  54
  55 We can specify multiple paths from a single task for a given set of formats,
  56 and multiple formats for a given set of paths.
  57
  58 Signing kinds
  59 -------------
  60
  61 We currently have multiple signing kinds. These fall into several categories:
  62
  63 **Build internal signing**: Certain package types require the internals to be signed.
  64 For 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;
  66 we need to sign the internals before we [re]create the package. For linux
  67 tarballs, we don't need special packaging, so we can sign everything in this
  68 task. 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.
  73 If we have created an update MAR file from the signed internals, the MAR
  74 file 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
  78 and partial update MARs.
  79
  80 **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.
  81
  82 We generate signed checksums at the top of the releases directories, like
  83 in `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
  89 Signing formats
  90 ---------------
  91
  92 The known signingscript formats are listed in the fourth column of the
  93 `signing password files`_.
  94
  95 The formats are specified in the ``upstreamArtifacts`` list-of-dicts.
  96 ``autograph_gpg`` signing results in a detached ``.asc`` signature file. Because of its
  97 nature, we gpg-sign at the end if given multiple formats for a given set of
  98 files.
  99
 100 ``jar`` signing is Android apk signing. After signing, we ``zipalign`` the apk.
 101 This includes the ``focus-jar`` format, which is just a way to specify a different
 102 set of keys for the Focus app.
 103
 104 ``macapp`` signing accepts either a ``dmg`` or ``tar.gz``; it converts ``dmg``
 105 files to ``tar.gz`` before submitting to the signing server. The signed binary
 106 is a ``tar.gz``.
 107
 108 ``authenticode`` signing takes individual binaries or a zipfile. We sign the
 109 individual file or internals of the zipfile, skipping any already-signed files
 110 and a select few blocklisted files (using the `should_sign_windows`_ function).
 111 It returns a signed individual binary or zipfile with signed internals, depending
 112 on 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
 116 the 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
 122 Cert levels
 123 -----------
 124
 125 Cert 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
 128 refers to builds that don't clobber, so they keep their dependency object files
 129 cached from the previous build.) These certs and keys are designed to be used
 130 for Try or on-push builds that we don't intend to ship. Many of these are
 131 self-signed and not of high security value; they're intended for testing
 132 purposes.
 133
 134 ``nightly`` refers to the Nightly product and channel. We use these keys for
 135 signing and shipping nightly builds, as well as Devedition on the beta channel.
 136 Because these are shipping keys, they are restricted; only a subset of branches
 137 can request the use of these keys.
 138
 139 ``release`` refers to our releases, off the beta, release, or esr channels.
 140 These are the most restricted keys.
 141
 142 We 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
 146 to have exactly one of those scopes, and only nightly- and release-enabled
 147 branches are able to use the latter two scopes. If a task is scheduled with one
 148 of those restricted scopes on a non-allowlisted branch, Chain of Trust
 149 verification will raise an exception.
 150
 151 Signing scriptworker workerTypes
 152 --------------------------------
 153
 154 The `linux-depsigning`_ pool handles all of the non-mac dep signing. These are
 155 heavily in use on try and autoland, but also other branches. These verify
 156 the `chain of trust`_ artifact but not its signature, and they don't have a
 157 gpg key to sign their own chain of trust artifact. This is by design; the chain
 158 of trust should and will break if a production scriptworker is downstream from
 159 a depsigning worker.
 160
 161 The `linux-signing`_ pool is the production signing pool; it handles the
 162 nightly- and release- signing requests. As such, it verifies the upstream
 163 chain of trust and all signatures, and signs its chain of trust artifact.
 164
 165 The `linux-devsigning`_ pool is intended for signingscript and scriptworker
 166 development use. Because it isn't used on any Firefox-developer-facing branch,
 167 Mozilla Releng is able to make breaking changes on this pool without affecting
 168 any other team.
 169
 170 Similarly, we have the `mac-depsigning`_ and `mac-signing`_ pools, which handle
 171 CI and nightly/release signing, respectively.
 172
 173 .. _60.0: https://archive.mozilla.org/pub/firefox/releases/60.0/
 174 .. _addonscript: https://github.com/mozilla-releng/addonscript/
 175 .. _code signing: https://en.wikipedia.org/wiki/Code_signing
 176 .. _chain of trust: https://scriptworker.readthedocs.io/en/latest/chain_of_trust.html
 177 .. _linux-depsigning: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-k8s/worker-types/gecko-t-signing
 178 .. _should_sign_windows: https://github.com/mozilla-releng/signingscript/blob/65cbb99ea53896fda9f4844e050a9695c762d24f/signingscript/sign.py#L369
 179 .. _Encrypted Media Extensions: https://hacks.mozilla.org/2014/05/reconciling-mozillas-mission-and-w3c-eme/
 180 .. _signing password files: https://github.com/mozilla/build-puppet/tree/feff5e12ab70f2c060b29940464e77208c7f0ef2/modules/signing_scriptworker/templates
 181 .. _signingscript: https://github.com/mozilla-releng/signingscript/
 182 .. _linux-devsigning: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-k8s/worker-types/gecko-t-signing-dev
 183 .. _linux-signing: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-k8s/worker-types/gecko-3-signing
 184 .. _mac-depsigning: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-prov-v1/worker-types/depsigning-mac-v1
 185 .. _mac-signing: https://firefox-ci-tc.services.mozilla.com/provisioners/scriptworker-prov-v1/worker-types/signing-mac-v1
 186 .. _signtool: https://github.com/mozilla-releng/signtool
 187 .. _Scriptworker: https://github.com/mozilla-releng/scriptworker/
 188 .. _widevine site: https://www.widevine.com/wv_drm.html