doc: clarifications regards tuf keys

Signed-off-by: Camila Macedo <[email protected]>

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::
@@ -47,7 +50,22 @@ 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<ref-static-deltas>` before rolling out waves to devices.
+   We recommend users generate :ref:`OSTree static deltas<ref-static-deltas>` prior to 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:

source/reference-manual/security/offline-keys.rst

@@ -19,11 +19,6 @@ makes it hard to perform known attacks by obtaining only one of the secrets.
 
 FoundriesFactory provides the ability to manage TUF keys via dedicated `Fioctl™ <Fioctl_>`_ commands.
 
-.. note::
-    We recommend running the command ``fioctl keys tuf updates review`` from time to time.
-    It will show you a list of our recommendations about improving your TUF usage, which evolve over time.
-    For example, it can show you the up to date information about the `Recommended Offline TUF Keys Schema`_.
-
 How to Rotate Offline TUF Root Key
 ----------------------------------
 
@@ -40,7 +35,7 @@ Thereafter, that (offline) TUF root key must be rotated regularly (at the least
   Factory owners who received it and have not yet downloaded/rotated the initial keys,
   can proceed with the initial rotation as described in this section.
 
-To take your TUF root key offline by performing its first time rotation, use this Fioctl_ command::
+To take your TUF root key offline by performing its first time rotation, use this `Fioctl™ <Fioctl_>`_ command::
 
   fioctl keys tuf rotate-offline-key --role=root --first-time \
     --keys=/absolute/path/to/root.keys.tgz
@@ -60,11 +55,14 @@ 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 <ref-ota>` to your Factory devices.
-Therefore, after each TUF root key rotation, we recommend that you `Backup Offline TUF Keys`_ as described below.
+.. important::
+    You must create a backup of ``root.keys.tgz``
+
+        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 <ref-ota>` 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 +106,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
 ----------------------------
@@ -192,6 +191,11 @@ One command of interest is ``fioctl keys tuf updates review``.
 It analyses your Factory's existing TUF root on the server, and prints a list of recommendations for improving it.
 Over time our engineers will add more items to that list as we develop new security features.
 
+.. note::
+    We recommend running the command ``fioctl keys tuf updates review`` from time to time.
+    It will show you a list of our recommendations about improving your TUF usage, which evolve over time.
+    For example, it can show you the up to date information about the `Recommended Offline TUF Keys Schema`_.
+
 .. _ref-offline-keys-more-than-1-root:
 
 How to Add More Than 1 Offline TUF Keys