diff --git a/source/clear-linux/how-to/validate-signatures.rst b/source/clear-linux/how-to/validate-signatures.rst index eeff86d9..07a24175 100644 --- a/source/clear-linux/how-to/validate-signatures.rst +++ b/source/clear-linux/how-to/validate-signatures.rst @@ -5,7 +5,7 @@ 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. A valid signature -creates a chain of trust. A broken chain of trust, seen as an invalid +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 @@ -19,7 +19,7 @@ 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 for signing the SHA512 sum. + Clear Linux certificate used for signing the SHA512 sum. .. code-block:: console @@ -27,21 +27,21 @@ used for illustrative purposes. You may use any image of |CL| you choose. 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 + # Clear Linux certificate curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem -#. Generate the SHA256 sum for the certificate. +#. Generate the SHA256 sum of the Clear Linux 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 Clear Linux certificate matches the + 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. @@ -56,14 +56,14 @@ used for illustrative purposes. You may use any image of |CL| you choose. of the image will fail. #. 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. + Clear Linux 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 -#. The output should contain ``Verification successful``. If the output +#. The output should contain ``Verification successful``. If the output contains ``bad_signature`` anywhere, then the image is not trustworthy. Update content validation @@ -74,8 +74,8 @@ 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. +#. Download the :abbr:`MoM (top-level manifest)`, the signature of the MoM, + and the Swupd certificate used for signing the signature of the MoM. .. code-block:: console @@ -83,34 +83,37 @@ these steps manually when performing a ``swupd update``. 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 certificate + curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/Swupd_Root.pem - .. note:: +#. Generate the SHA256 sum of the Swupd certificate. - 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. + .. code-block:: console - .. important:: + sha256sum Swupd_Root.pem - 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 generated SHA256 sum of the Swupd certificate matches following + SHA256 sum to verify the integrity of the certificate. -#. Ensure the signature of the MoM was created using the certificate. This - signature validates the update content is trustworthy and has not been + .. code-block:: console + + ff06fc76ec5148040acb4fcb2bc8105cc72f1963b55de0daf3a4ed664c6fe72c Swupd_Root.pem + +#. Ensure the signature of the MoM was created using the Swupd 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 Manifest.MoM.sig -inform der -content Manifest.MoM -CAfile Swupd_Root.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 SHA512 sum of the MoM is not generated and then 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 +#. The output should contain ``Verification successful``. If the output 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.