.. _validate-signatures:

Validate signatures
###################

|CL-ATTR| 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 is the same 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
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
   |CL| certificate used for signing the SHA512 sum.

   .. 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

#. Generate the SHA256 sum of the |CL| certificate.

   .. code-block:: console

      sha256sum ClearLinuxRoot.pem

#. Ensure the generated SHA256 sum of the |CL| certificate matches the
   following SHA256 sum to verify the integrity of the certificate.

   .. code-block:: console

      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

#. Ensure the signature of the SHA512 sum of the image was created using the
   |CL| certificate. This validates the image is trusted and it has not
   been modified.

   .. code-block:: console

      openssl smime -verify -purpose any -in clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem

   .. note::

      The `-purpose any` option is required when using OpenSSL 1.1.  If using
      an earlier version of OpenSSL, omit this option to perform signature
      validation.  The `openssl version` command may be used to determine the
      version of OpenSSL in use.

#. The output should contain ``Verification successful``. If the output
   contains ``bad_signature`` anywhere, then the image is not trustworthy.

Update content validation
=========================

``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)`, the signature of the MoM,
   and the Swupd certificate used for signing 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.MoM.sig
      # Swupd certificate
      curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/Swupd_Root.pem

#. Generate the SHA256 sum of the Swupd certificate.

   .. code-block:: console

      sha256sum Swupd_Root.pem

#. Ensure the generated SHA256 sum of the Swupd certificate matches following
   SHA256 sum to verify the integrity of the certificate.

   .. 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 -purpose any -in Manifest.MoM.sig -inform der -content Manifest.MoM -CAfile Swupd_Root.pem

   .. note::

      The `-purpose any` option is required when using OpenSSL 1.1.  If using
      an earlier version of OpenSSL, omit this option to perform signature
      validation.  The `openssl version` command may be used to determine the
      version of OpenSSL in use.

   .. note::

      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
   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.
