clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-08-24 16:57:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

Showing users precicely how swupd validates signatures

Browse Source
This commit is contained in:
George T Kramer
2017-03-22 17:49:43 -07:00
parent 3e0dc35cac
commit a86fc32f22
1 changed files with 47 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/validate_sigs.rst
+47 -74
View File
@@ -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/
#. 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.