From 3e0dc35cac6434677634d1898fa2cc1fecac68bb Mon Sep 17 00:00:00 2001 From: George T Kramer Date: Wed, 22 Mar 2017 17:03:19 -0700 Subject: [PATCH 1/5] Revising to be more clear --- source/validate_sigs.rst | 104 +++++++++++++++++++++------------------ 1 file changed, 55 insertions(+), 49 deletions(-) diff --git a/source/validate_sigs.rst b/source/validate_sigs.rst index cd593ee6..065be55e 100644 --- a/source/validate_sigs.rst +++ b/source/validate_sigs.rst @@ -3,81 +3,87 @@ Validating Signatures ##################### -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. +|CLOSIA| offers a way to validate the content of an image or an update. +Validation of content works by creating a hash and then signing the hash. If +the signature of the hash is valid, then that implies the content is valid. -Multiple types of artifacts have signing/verifying: +This guide covers how to validate the content of an image, which is a manual +process, and the automatic process which occurs to validate an update that +``swupd`` performs in the background. -* Image checksums files; for example, `release 8890`_ has - * ``clear-*.img.xz`` image files, - * ``clear-*.img.xz-SHA512SUMS`` checksum files, and - * ``clear-*.img.xz-SHA512SUMS.sig`` signature files. -* The :command:`swupd` Manifest of Manifests (aka :abbr:`MoM (Manifest of Manifests)`) - ``https://download.clearlinux.org/update/8890/`` has ``Manifest.MoM`` - and ``Manifest.MoM.sig`` signature file. +Image Content Validation +======================== -Verifying a Clear Linux OS for Intel Architecture image -======================================================= +For the outlined steps, the installer image of the latest release of |CL| is +used for illustrative purposes. You may use any image of |CL| you choose. -Verification of images is done by humans when they download an image via the following steps: +#. Download the image, the signature of the SHA512 sum of the image, and the certificate used + to create signatures. -#. Download the current ``ClearLinuxRoot.pem`` certificate; this is provided - 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. -#. Download and validate the release's OS ``ClearLinuxRoot.pem`` certificate: + .. code-block:: console - * Validate the certificate by comparing the downloaded certificate's - ``sha256sum`` hash with what is published here: + # Image + curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz + # Signature of SHA512 sum of image + curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig + # Certificate + curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem - .. code-block:: console +#. Generate the ``sha256sum`` of the certificate. + + .. code-block:: console - $ sha256sum ClearLinuxRoot.pem + sha256sum ClearLinuxRoot.pem - You should see this (accurate as of 2016-06-16 00:00 UTC): +#. Ensure the generated SHA256 sum of the certificate matches following SHA256 + sum to verify the integrity of the certificate. - .. code-block:: console + .. code-block:: console - 4b0ca67300727477913c331ff124928a98bcf2fb12c011a855f17cd73137a890 ClearLinuxRoot.pem + 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. - To do this, create the **SHA512SUMS** file of the tarball. This is the - content which is actually signed by the release team. +#. Generate the ``sha512sum`` of the image and save it to a file. + + .. code-block:: console - .. code-block:: console + sha512sum ./clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz > sha512sum.out - $ sha512sum ./[image-####].img.xz > sha512sum.out + .. important:: - * Finally, we can use :command:`openssl` to validate the signed - :file:`SHA512SUMS.sig` was signed by the ``ClearLinuxRoot`` certificate: + The ``./`` in the file name must be included. This is part of the + signature of the SHA512 sum of the image. Without it, the validation will + fail. - .. code-block:: console +#. Ensure the signature of the SHA512 sum of the image sum was signed using the + certificate. This validates that the image is trusted and that it has not been + modified. - $ openssl smime -verify -in [image]-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem -out /dev/null + .. code-block:: console - 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. + openssl smime -verify -in clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem + +#. The output should be ``Verification successful``. If the output contains + ``bad_signature`` at all, then the image cannot be trusted. + +Update Content Validation +========================= + +All update content processed by ``swupd`` is validated automatically before +being applied. What follows is the process ``swupd`` follows internally, +illustrated with manual steps: -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 OS for Intel Architecture releases in :file:`/usr/share/clear/update-ca/ClearLinuxRoot.pem`. -#. :command:`swupd` downloads the top-level manifest (MoM), as +#. ``swupd`` downloads the top-level manifest (MoM), as well as the signed :file:`MoM.sig` for the currently-installed image, and for the release being updated to in the case of an update. -#. :command:`swupd` generates a ``sha256sum`` of the MoM. +#. ``swupd`` generates a ``sha256sum`` of the MoM. -#. :command:`swupd` uses the :file:`MoM.sig` downloaded in step 1, +#. ``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: @@ -92,7 +98,7 @@ An overview of the mechanism used internal to :command:`swupd` of all bundle manifests. * **Success** When a successful signature verification occurs, you - should see the following message as part of the :command:`swupd` + should see the following message as part of the ``swupd`` output: .. code-block:: console @@ -105,7 +111,7 @@ An overview of the mechanism used internal to :command:`swupd` WARNING!!! FAILED TO VERIFY SIGNATURE OF Manifest.MoM -#. As :command:`swupd` then uses or installs bundle manifests, that +#. As ``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. From a86fc32f22501a2880370db4faf2ab37d205d9f7 Mon Sep 17 00:00:00 2001 From: George T Kramer Date: Wed, 22 Mar 2017 17:49:43 -0700 Subject: [PATCH 2/5] Showing users precicely how swupd validates signatures --- source/validate_sigs.rst | 121 +++++++++++++++------------------------ 1 file changed, 47 insertions(+), 74 deletions(-) diff --git a/source/validate_sigs.rst b/source/validate_sigs.rst index 065be55e..c275bfbd 100644 --- a/source/validate_sigs.rst +++ b/source/validate_sigs.rst @@ -4,12 +4,13 @@ Validating Signatures ##################### |CLOSIA| offers a way to validate the content of an image or an update. -Validation of content works by creating a hash and then signing the hash. If -the signature of the hash is valid, then that implies the content is valid. +Validation of all content works by creating a hash and then signing the hash. If +the signature of the hash is valid, then that implies the content is valid by +creating a chain of trust. This guide covers how to validate the content of an image, which is a manual process, and the automatic process which occurs to validate an update that -``swupd`` performs in the background. +``swupd`` performs internally. Image Content Validation ======================== @@ -17,8 +18,8 @@ Image Content Validation For the outlined steps, the installer image of the latest release of |CL| is used for illustrative purposes. You may use any image of |CL| you choose. -#. Download the image, the signature of the SHA512 sum of the image, and the certificate used - to create signatures. +#. Download the image, the signature of the SHA512 sum of the image, and the + certificate used for signing the SHA512 sum. .. code-block:: console @@ -29,8 +30,8 @@ used for illustrative purposes. You may use any image of |CL| you choose. # Certificate curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem -#. Generate the ``sha256sum`` of the certificate. - +#. Generate the SHA256 sum of the certificate. + .. code-block:: console sha256sum ClearLinuxRoot.pem @@ -42,102 +43,74 @@ used for illustrative purposes. You may use any image of |CL| you choose. 4b0ca67300727477913c331ff124928a98bcf2fb12c011a855f17cd73137a890 ClearLinuxRoot.pem -#. Generate the ``sha512sum`` of the image and save it to a file. - +#. Generate the SHA512 sum of the image and save it to a file. + .. code-block:: console sha512sum ./clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz > sha512sum.out .. important:: - The ``./`` in the file name must be included. This is part of the - signature of the SHA512 sum of the image. Without it, the validation will - fail. + The ``./`` in the file name must be included because it is part of the + SHA512 sum of the image. Without it, the validation of the signature of + the image will fail. -#. Ensure the signature of the SHA512 sum of the image sum was signed using the - certificate. This validates that the image is trusted and that it has not been - modified. +#. Ensure the signature of the SHA512 sum of the image was signed using the + certificate. This validates that the image is trusted and that it has not + been modified. .. code-block:: console openssl smime -verify -in clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem -#. The output should be ``Verification successful``. If the output contains - ``bad_signature`` at all, then the image cannot be trusted. +#. The output should contain ``Verification successful``. If the output + contains ``bad_signature`` at all, then the image cannot be trusted. Update Content Validation ========================= All update content processed by ``swupd`` is validated automatically before being applied. What follows is the process ``swupd`` follows internally, -illustrated with manual steps: +illustrated with manual steps for the latest release. There is no need to +perform this manually as a part of performing a ``swupd update``. +#. Download the :abbr:`MoM (top-level manifest)` and the signature of the MoM. -#. A trusted certificate is distributed with all Clear Linux - OS for Intel Architecture releases in :file:`/usr/share/clear/update-ca/ClearLinuxRoot.pem`. + .. code-block:: console -#. ``swupd`` downloads the top-level manifest (MoM), as - well as the signed :file:`MoM.sig` for the currently-installed - image, and for the release being updated to in the case of an update. + # MoM + curl -O https://download.clearlinux.org/update/$(curl https://download.clearlinux.org/latest)/Manifest.MoM + # Signature of MoM + curl -O https://download.clearlinux.org/update/$(curl https://download.clearlinux.org/latest)/Manifest.sig -#. ``swupd`` generates a ``sha256sum`` of the MoM. + .. note:: -#. ``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: + The certificate used for signing the MoM is distributed with |CL| and can + be found at ``/usr/share/clear/update-ca/Swupd_Root.pem``. As a result, + the integrity of the certificate does not need validated. It is already + trusted. - .. code-block:: c + .. note:: - openssl smime -verify -in sha256sums.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem + The certificate used by ``swupd`` and the certificate used for the + distribution are different because these are different entities that + require separate identities. - Note that the actual API call is to ``PKCS7_verify())``. +#. Ensure the signature of the MoM was signed using the certificate. This + validates that the update content is trusted and that it has not been + modified. -#. With a successful verification, we can proceed to trust this - MoM and its contents, which consist of hashes of the contents - of all bundle manifests. + .. code-block:: console - * **Success** When a successful signature verification occurs, you - should see the following message as part of the ``swupd`` - output: + openssl smime -verify -in sha256sums.sig -inform der -content Manifest.MoM -CAfile ClearLinuxRoot.pem - .. code-block:: console + .. note:: - Signature check succeeded + The SHA512 sum of the MoM is not signed. Instead, the MoM is signed + directly because it is small in size compared to an image of |CL|. - * **Fail** Should verification fail, you will see: - - .. code-block:: console - - WARNING!!! FAILED TO VERIFY SIGNATURE OF Manifest.MoM - -#. As ``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 ------------------------------------------------------------------------------ - -.. code-block:: raw - - -----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----- - - -You can re-create this when given a cert with the command: - -.. code-block:: console - - $ openssl x509 -pubkey -noout -in ClearLinuxRoot.pem - - - -.. _release 8890: https://download.clearlinux.org/releases/8890/clear/ \ No newline at end of file +#. The output should contain ``Verification successful``. If the output + contains ``bad_signature`` at all, then the MoM cannot be trusted. Because + the MoM contains a list of hashes for bundle manifests, if the MoM cannot be + trustes, then bundle content cannot be trusted. \ No newline at end of file From 52c84f7a224fe0a67af6b3ca6a214c6da87fd4c1 Mon Sep 17 00:00:00 2001 From: Rodrigo Caballero Date: Fri, 31 Mar 2017 14:04:11 -0600 Subject: [PATCH 3/5] Edit the grammar, spelling, and markup of validation signatures. Signed-off-by: Rodrigo Caballero --- source/validate_sigs.rst | 144 ++++++++++++++++++++------------------- 1 file changed, 75 insertions(+), 69 deletions(-) diff --git a/source/validate_sigs.rst b/source/validate_sigs.rst index c275bfbd..78ea7428 100644 --- a/source/validate_sigs.rst +++ b/source/validate_sigs.rst @@ -1,18 +1,17 @@ .. _validate_sigs: -Validating Signatures +Validating signatures ##################### |CLOSIA| offers a way to validate the content of an image or an update. -Validation of all content works by creating a hash and then signing the hash. If -the signature of the hash is valid, then that implies the content is valid by -creating a chain of trust. +All validation of content works by creating and signing a hash. If +the signature is valid, then the chain of trust implies the content is valid. -This guide covers how to validate the content of an image, which is a manual -process, and the automatic process which occurs to validate an update that -``swupd`` performs internally. +This guide covers how to validate the contents of an image, which is a manual +process, and describes the automatic process ``swupd`` performs internally to +validate an update. -Image Content Validation +Image content validation ======================== For the outlined steps, the installer image of the latest release of |CL| is @@ -23,94 +22,101 @@ used for illustrative purposes. You may use any image of |CL| you choose. .. code-block:: console - # Image - curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz - # Signature of SHA512 sum of image - curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig - # Certificate - curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem + # Image curl -O https://download.clearlinux.org/current/clear-$(curl + https://download.clearlinux.org/latest)-installer.img.xz + # Signature of SHA512 sum of image curl -O + https://download.clearlinux.org/current/clear-$(curl + https://download.clearlinux.org/latest)-installer.img.xz- + SHA512SUMS.sig + # Certificate curl -O https://download.clearlinux.org/releases/$(curl + https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem -#. Generate the SHA256 sum of the certificate. +#. Generate the SHA256 sum for the certificate. .. code-block:: console sha256sum ClearLinuxRoot.pem -#. Ensure the generated SHA256 sum of the certificate matches following SHA256 - sum to verify the integrity of the certificate. +#. Ensure the generated SHA256 sum of the certificate matches following + SHA256 sum to verify the integrity of the certificate. .. code-block:: console - 4b0ca67300727477913c331ff124928a98bcf2fb12c011a855f17cd73137a890 ClearLinuxRoot.pem + 4b0ca67300727477913c331ff124928a98bcf2fb12c011a855f17cd73137a890 + ClearLinuxRoot.pem #. Generate the SHA512 sum of the image and save it to a file. .. code-block:: console - sha512sum ./clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz > sha512sum.out + sha512sum ./clear-$(curl + https://download.clearlinux.org/latest)-installer.img.xz > + sha512sum.out .. important:: The ``./`` in the file name must be included because it is part of the - SHA512 sum of the image. Without it, the validation of the signature of - the image will fail. + SHA512 sum of the image. Without it, the validation of the signature + of the image will fail. #. Ensure the signature of the SHA512 sum of the image was signed using the - certificate. This validates that the image is trusted and that it has not - been modified. - - .. code-block:: console - - openssl smime -verify -in clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem - -#. The output should contain ``Verification successful``. If the output - contains ``bad_signature`` at all, then the image cannot be trusted. - -Update Content Validation -========================= - -All update content processed by ``swupd`` is validated automatically before -being applied. What follows is the process ``swupd`` follows internally, -illustrated with manual steps for the latest release. There is no need to -perform this manually as a part of performing a ``swupd update``. - - -#. Download the :abbr:`MoM (top-level manifest)` and the signature of the MoM. - - .. code-block:: console - - # MoM - curl -O https://download.clearlinux.org/update/$(curl https://download.clearlinux.org/latest)/Manifest.MoM - # Signature of MoM - curl -O https://download.clearlinux.org/update/$(curl https://download.clearlinux.org/latest)/Manifest.sig - - .. note:: - - The certificate used for signing the MoM is distributed with |CL| and can - be found at ``/usr/share/clear/update-ca/Swupd_Root.pem``. As a result, - the integrity of the certificate does not need validated. It is already - trusted. - - .. note:: - - The certificate used by ``swupd`` and the certificate used for the - distribution are different because these are different entities that - require separate identities. - -#. Ensure the signature of the MoM was signed using the certificate. This - validates that the update content is trusted and that it has not been + certificate. This validates the image is trusted and it has not been modified. .. code-block:: console - openssl smime -verify -in sha256sums.sig -inform der -content Manifest.MoM -CAfile ClearLinuxRoot.pem + openssl smime -verify -in clear-$(curl + https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig + -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem + +#. The output should contain ``Verification successful``. If the output + contains ``bad_signature`` anywhere, then the image cannot be trusted. + +Update content validation +========================= + +``swupd`` validates all the processed update content automatically before it +is applied. The process ``swupd`` follows internally is illustrated here with +manual steps using the latest |CL| release. There is no need to perform these +steps manually as a part of a ``swupd update``. + + +#. Download the :abbr:`MoM (top-level manifest)` and the signature of the + MoM. + + .. code-block:: console + + # MoM curl -O https://download.clearlinux.org/update/$(curl + https://download.clearlinux.org/latest)/Manifest.MoM + # Signature of MoM curl -O + https://download.clearlinux.org/update/$(curl + https://download.clearlinux.org/latest)/Manifest.sig .. note:: - The SHA512 sum of the MoM is not signed. Instead, the MoM is signed + The certificate used for signing the MoM is distributed with |CL| + at :file:`/usr/share/clear/update-ca/Swupd_Root.pem`. As a result, the + integrity of the certificate does not require validation; it is already + trusted. + + The certificate used by ``swupd`` and the certificate used for the + distribution's image are different because these are different entities + requiring separate identities. + +#. Ensure the signature of the MoM used the certificate. This signature + validates the update content is trusted and it has not been modified. + + .. code-block:: console + + openssl smime -verify -in sha256sums.sig -inform der -content + Manifest.MoM -CAfile ClearLinuxRoot.pem + + .. note:: + + The SHA512 sum of the MoM is not signed. Instead, the MoM is signed directly because it is small in size compared to an image of |CL|. #. The output should contain ``Verification successful``. If the output - contains ``bad_signature`` at all, then the MoM cannot be trusted. Because - the MoM contains a list of hashes for bundle manifests, if the MoM cannot be - trustes, then bundle content cannot be trusted. \ No newline at end of file + contains ``bad_signature`` anywhere, then the MoM cannot be trusted. + Because the MoM contains a list of hashes for bundle manifests, if the MoM + cannot be trusted, then the bundle content cannot be trusted. \ No newline at end of file From b96a823d51762b34132cfc3944d428619340e434 Mon Sep 17 00:00:00 2001 From: George T Kramer Date: Tue, 4 Apr 2017 11:03:08 -0700 Subject: [PATCH 4/5] Minor phrasing changes for clarity --- source/validate_sigs.rst | 64 ++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 35 deletions(-) diff --git a/source/validate_sigs.rst b/source/validate_sigs.rst index 78ea7428..6b08a6a3 100644 --- a/source/validate_sigs.rst +++ b/source/validate_sigs.rst @@ -3,9 +3,10 @@ Validating signatures ##################### -|CLOSIA| offers a way to validate the content of an image or an update. -All validation of content works by creating and signing a hash. If -the signature is valid, then the chain of trust implies the content is valid. +|CLOSIA| offers a way to validate the content of an image or an update. All +validation of content works by creating and signing a hash. A valid signature +creates a chain of trust. A broken chain of trust, seen as an invalid +signature, means the content is not valid. This guide covers how to validate the contents of an image, which is a manual process, and describes the automatic process ``swupd`` performs internally to @@ -22,14 +23,12 @@ used for illustrative purposes. You may use any image of |CL| you choose. .. code-block:: console - # Image curl -O https://download.clearlinux.org/current/clear-$(curl - https://download.clearlinux.org/latest)-installer.img.xz - # Signature of SHA512 sum of image curl -O - https://download.clearlinux.org/current/clear-$(curl - https://download.clearlinux.org/latest)-installer.img.xz- - SHA512SUMS.sig - # Certificate curl -O https://download.clearlinux.org/releases/$(curl - https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem + # Image + curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz + # Signature of SHA512 sum of image + curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig + # Certificate + curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem #. Generate the SHA256 sum for the certificate. @@ -42,16 +41,13 @@ used for illustrative purposes. You may use any image of |CL| you choose. .. code-block:: console - 4b0ca67300727477913c331ff124928a98bcf2fb12c011a855f17cd73137a890 - ClearLinuxRoot.pem + 4b0ca67300727477913c331ff124928a98bcf2fb12c011a855f17cd73137a890 ClearLinuxRoot.pem #. Generate the SHA512 sum of the image and save it to a file. .. code-block:: console - sha512sum ./clear-$(curl - https://download.clearlinux.org/latest)-installer.img.xz > - sha512sum.out + sha512sum ./clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz > sha512sum.out .. important:: @@ -59,38 +55,34 @@ used for illustrative purposes. You may use any image of |CL| you choose. SHA512 sum of the image. Without it, the validation of the signature of the image will fail. -#. Ensure the signature of the SHA512 sum of the image was signed using the +#. Ensure the signature of the SHA512 sum of the image was created using the certificate. This validates the image is trusted and it has not been modified. .. code-block:: console - openssl smime -verify -in clear-$(curl - https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig - -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem + openssl smime -verify -in clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem #. The output should contain ``Verification successful``. If the output - contains ``bad_signature`` anywhere, then the image cannot be trusted. + contains ``bad_signature`` anywhere, then the image is not trustworthy. Update content validation ========================= -``swupd`` validates all the processed update content automatically before it -is applied. The process ``swupd`` follows internally is illustrated here with -manual steps using the latest |CL| release. There is no need to perform these -steps manually as a part of a ``swupd update``. - +``swupd`` validates all update content automatically before applying the +update content. The process ``swupd`` follows internally is illustrated here +with manual steps using the latest |CL| release. There is no need to perform +these steps manually when performing a ``swupd update``. #. Download the :abbr:`MoM (top-level manifest)` and the signature of the MoM. .. code-block:: console - # MoM curl -O https://download.clearlinux.org/update/$(curl - https://download.clearlinux.org/latest)/Manifest.MoM - # Signature of MoM curl -O - https://download.clearlinux.org/update/$(curl - https://download.clearlinux.org/latest)/Manifest.sig + # MoM + curl -O https://download.clearlinux.org/update/$(curl https://download.clearlinux.org/latest)/Manifest.MoM + # Signature of MoM + curl -O https://download.clearlinux.org/update/$(curl https://download.clearlinux.org/latest)/Manifest.sig .. note:: @@ -99,17 +91,19 @@ steps manually as a part of a ``swupd update``. integrity of the certificate does not require validation; it is already trusted. + .. note:: + The certificate used by ``swupd`` and the certificate used for the distribution's image are different because these are different entities requiring separate identities. -#. Ensure the signature of the MoM used the certificate. This signature - validates the update content is trusted and it has not been modified. +#. Ensure the signature of the MoM was created using the certificate. This + signature validates the update content is trustworthy and has not been + modified. .. code-block:: console - openssl smime -verify -in sha256sums.sig -inform der -content - Manifest.MoM -CAfile ClearLinuxRoot.pem + openssl smime -verify -in sha256sums.sig -inform der -content Manifest.MoM -CAfile ClearLinuxRoot.pem .. note:: From 6708de460d22d247391047ffe6bd1715d297dfef Mon Sep 17 00:00:00 2001 From: Rodrigo Caballero Date: Thu, 6 Apr 2017 12:24:47 -0500 Subject: [PATCH 5/5] Replace a note with an important notice. Signed-off-by: Rodrigo Caballero --- source/validate_sigs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/validate_sigs.rst b/source/validate_sigs.rst index 6b08a6a3..87bdc334 100644 --- a/source/validate_sigs.rst +++ b/source/validate_sigs.rst @@ -91,7 +91,7 @@ these steps manually when performing a ``swupd update``. integrity of the certificate does not require validation; it is already trusted. - .. note:: + .. important:: The certificate used by ``swupd`` and the certificate used for the distribution's image are different because these are different entities