From f7e5e192f577f165bde7811be9cec43697fbf4a5 Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Tue, 3 Oct 2023 12:09:56 +0100 Subject: [PATCH] doc: clarifications regards tuf keys Signed-off-by: Camila Macedo --- .../ota/production-targets.rst | 18 ++++++++++++++++++ .../reference-manual/security/offline-keys.rst | 18 ++++++++++-------- 2 files changed, 28 insertions(+), 8 deletions(-) diff --git a/source/reference-manual/ota/production-targets.rst b/source/reference-manual/ota/production-targets.rst index c66b5c153..b65a8198f 100644 --- a/source/reference-manual/ota/production-targets.rst +++ b/source/reference-manual/ota/production-targets.rst @@ -35,6 +35,9 @@ Waves allow Factory operators to control an exact time when devices see a new ve Performing a Production OTA --------------------------- +.. note:: + The process for performing a Production OTA needs the :ref:`ref-offline-keys` (``targets.key.tgz``) which will be used to sign production targets. + A user should define a process to select CI builds which need to be delivered to production devices. Let's assume a user selected a CI build version 42 as ready to be run in production. To start the production release process, a user would create a new wave using the below command:: @@ -48,6 +51,21 @@ That TUF targets role only includes a single Target from CI build (in above exam .. note:: We recommend that a user generates :ref:`OSTree static deltas` before rolling out waves to devices. + This optimizes the OTA update download process. + +.. note:: + + If you encounter issues while creating the weave, particularly the following error: + + .. code-block:: shell + + 409 CONFLICT + = Conflict: /ota/repo/qemu/api/v1/user_repo/root/updates? + = Only one TUF root updates transaction can be active at a time + + It indicates a conflict with an active TUF root update. + The Factory admin might able to sort it out by running ``fioctl keys tuf updates cancel``. + After that, it is possible generate a new ``targets.key.tgz``. Once created, a new wave can be rolled out to Factory production devices, all at once or in phases. There are several ways how a wave can be rolled out: diff --git a/source/reference-manual/security/offline-keys.rst b/source/reference-manual/security/offline-keys.rst index f0d80e941..c3cb7eaf3 100644 --- a/source/reference-manual/security/offline-keys.rst +++ b/source/reference-manual/security/offline-keys.rst @@ -60,11 +60,12 @@ Onwards, use a shorter command to rotate your (offline) TUF root key:: .. note:: Here and below the ``root.keys.tgz`` file is the one created during the first offline TUF root key rotation. -When rotating the TUF root key, the newly generated key is added to the keys tarball (``root.keys.tgz`` in examples). -That file **must never be lost**. -Otherwise, it will be impossible to make any future updates to the Factory TUF keys. -That will lead to the inability to deliver new :ref:`Over-the-Air (OTA) updates ` to your Factory devices. -Therefore, after each TUF root key rotation, we recommend that you `Backup Offline TUF Keys`_ as described below. +.. important:: + When rotating the TUF root key, the newly generated key is added to the keys tarball (``root.keys.tgz`` in examples). + That file **must never be lost**. + Otherwise, it will be impossible to make any future updates to the Factory TUF keys. + That will lead to the inability to deliver new :ref:`Over-the-Air (OTA) updates ` to your Factory devices. + Therefore, after each TUF root key rotation, we recommend that you `Backup Offline TUF Keys`_ as described below. How to Rotate Offline TUF Targets Key ------------------------------------- @@ -108,9 +109,10 @@ This will perform the following steps: That approach makes it possible to distribute the targets key among a wider set of Factory admins, and allow them to sign production targets without exposing the TUF root key to the wider audience. -After each TUF targets key rotation we recommend that you `Backup Offline TUF Keys`_ as described below. -If you lose the offline TUF targets key, a new key can be generated if you have your Factory offline TUF root key. -However, losing this key may be inconvenient if more than one Factory admin can manage production targets. +.. important:: + After each TUF targets key rotation we recommend that you `Backup Offline TUF Keys`_ as described below. + If you lose the offline TUF targets key, a new key can be generated if you have your Factory offline TUF root key. + However, losing this key may be inconvenient if more than one Factory admin can manage production targets. How to View Offline TUF Keys ----------------------------