From ba8456e877b296e0f9df2b0170b0e767634c1fcd Mon Sep 17 00:00:00 2001 From: Leona Date: Thu, 7 Jul 2016 15:15:42 -0700 Subject: [PATCH] adding info about signing and verifying build artifacts to advanced_config Signed-off-by: Leona --- source/validate_sigs.rst | 91 ++++++++++++++++++++++++++++++++++------ 1 file changed, 78 insertions(+), 13 deletions(-) diff --git a/source/validate_sigs.rst b/source/validate_sigs.rst index b9ef4153..a927d214 100644 --- a/source/validate_sigs.rst +++ b/source/validate_sigs.rst @@ -3,19 +3,19 @@ Validating Signatures ##################### -Clear Linux offers a way to validate signatures to create verifiable build -artifacts. Validations can be obtained by users and by code to confirm -that we are indeed dealing with official ClearLinux outputs. +Clear Linux* OS for Intel® Architecture offers a way to validate signatures +to create verified build artifacts. Validations can be obtained by users and +by code to confirm that we are indeed dealing with official outputs. Multiple types of artifacts have signing/verifying: * Image checksums files; for example, the release ``https://download.clearlinux.org/releases/8890/clear/`` has ``clear-*.img.xz`` - image files, ``clear-*.img.xz-SHA512SUMS`` checksum files, and + image files, ``clear-*.img.xz-SHA512SUMS`` checksum files, and ``clear-*.img.xz-SHA512SUMS.sig`` signature files. -.. * Software Update :command:`swupd`; :abbr:`Manifest of Manifests (MoM)`: +* Software Update :command:`swupd`; :abbr:`Manifest of Manifests (MoM)`: ``https://download.clearlinux.org/update/8890/`` has ``Manifest.MoM`` and - ``Manifest.MoM.sig`` validations. .. + ``Manifest.MoM.sig`` signature file. Verifying a Clear OS Image ========================== @@ -26,7 +26,7 @@ Verification of images is done by humans when they download an image via the fol with the release being downloaded. For example, if you're interested in verifying the ``8970`` release, obtain the certificate from `https://download.clearlinux.org/releases/8970/clear/ClearLinuxRoot.pem`_. #. Download the desired OS image, as well as the ``[image]-SHA512SUMS.sig`` file - to a directory. For simplification purposes here, we'll call it ``~/download`` + to a directory. #. Download and validate the release's OS ``ClearLinuxRoot.pem`` certificate: * Validate the certificate by comparing the downloaded certificate's @@ -40,20 +40,21 @@ Verification of images is done by humans when they download an image via the fol .. code-block:: console_output + .. You should see this (accurate as of 2016-06-14 00:00 UTC): + 4b0ca67300727477913c331ff124928a98bcf2fb12c011a855f17cd73137a890 ClearLinuxRoot.pem * Now we verify that the signature file is valid, which also proves - the OS image tarball is as trusted as the ClearLinuxRoot certificate - that we have in ``~/download``. To do this, create the **SHA512SUMS** - file of the tarball. This is the content which is actually signed by - the Clear Linux release team. + the OS image tarball is as trusted as the ``ClearLinuxRoot`` certificate. + To do this, create the **SHA512SUMS** file of the tarball. This is the + content which is actually signed by the Clear Linux* OS for Intel® Architecture's release team. .. code-block:: console $ sha512sum [image].tar.xz > sha512sum.out - * Finally, we can use openssl to validate the signed :file:`SHA512SUMS.sig` - was signed by the Clear Linux Root certificate: + * Finally, we can use :command:`openssl` to validate the signed + :file:`SHA512SUMS.sig` was signed by the ``ClearLinuxRoot`` certificate: .. code-block:: console @@ -62,3 +63,67 @@ Verification of images is done by humans when they download an image via the fol After running this, you should see: :code:`Verification successful`. If you do not see this, you cannot be certain the OS you downloaded can be trusted. + + +Verification of the signed MoM +============================== + +An overview of the mechanism used internal to :command:`swupd` +(implemented in C calls to the openssl library API) is as follows: + +#. A trusted certificate is distributed with all Clear Linux + releases in :file:`/usr/share/clear/update-ca/ClearLinuxRoot.pem`. + +#. The :command:`swupd` downloads the top-level manifest (MoM), as + well as the signed :file:`MoM.sig` for either the currently-installed + image, and for the release being updated to in the case of an update. + +#. The :command:`swupd` generates a ``sha256sum`` of the MoM. + +#. The :command:`swupd` uses the :file:`MoM.sig` downloaded in step 1, + as well as the ``sha256sum``; and, using the openssl API, it makes + an equivalent call to the verification command: + + .. code-block:: c + + openssl smime -verify -in sha256sums.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem + + .. note:: + The actual API call is to ``PKCS7_verify())`` + +#. With a successful verification, we can proceed to trust this + MoM and its contents, which consist of hashes of the contents + of all the Clear Linux bundle manifests. + + * **Success** When a successful signature verification occurs, you + should see the message ``Signature check succeeded`` as part of the\ + :command:`swupd` output. + + * **Fail** Should verification fail, you will see ``WARNING!!! FAILED TO VERIFY SIGNATURE OF Manifest.MoM``. + +#. As :command:`swupd` then uses or installs bundle manifests, that + bundle manifest hash is matched to the trusted MoM, extending the + chain of trust from the MoM, to the bundle manifests, and out to + every file installed. + +Clear Linux* OS for Intel® Architecture Public Key as of 06/16/2016 00:00 UTC +----------------------------------------------------------------------------- + +You can re-create this when given a cert with the command: + +.. code-block:: console + + $ openssl x509 -pubkey -noout -in ClearLinuxRoot.pem + + -----BEGIN PUBLIC KEY----- + + MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwfnY2m665SwYxr4/R+8L + X1IMAkVYmvNiI5KmV815WvVQwUQDDCY1HUag+wb2BhTxkotKUdm6LGY1ck+Eb742 + rdICMToX+32vFM3XvIK16TKM6ficPsGA4xmbE/9qp01bn0O4MCwKjPAmxJkW+UOO + L5u8p9VBZ1MYMnsRkECPZif/fULqIU73aYD3HYtcYEk1+N8n1AcNkpRY9p3Qd92M + 9aRlCNl1sb2g5DwSx9G0dWTS+YPchpclV7fBGQUiTuxb72hpVRE66CfR8tTd14np + IbsKGq0S5PzkR9ubilDywFQ/6XPc1Rur/4g0rm6pPPx7DLQK3EqC8d4Z/C2nywje + PwIDAQAB + + -----END PUBLIC KEY----- +