ug: offline-update: Add info on bundle expiration

Signed-off-by: Mike Sul <[email protected]>

source/user-guide/offline-update/offline-update.rst

@@ -52,6 +52,78 @@ Use the command ``fioctl targets offline-update <target-name> <dst> <--tag <tag>
 .. note::
     In order to download all artifacts, ``fioctl`` requires token with scopes: ``targets:read``, ``ci:read``.
 
+Controlling the Expiration Time of the Offline Update Bundle
+------------------------------------------------------------
+
+The offline update content, referred to as the "bundle," obtained through the ``fioctl targets offline-update`` command,
+comes with an expiration time. If the expiration time of the bundle has passed, the offline update will fail.
+
+.. sidebar:: Error if root or targets metadata expires before the specified expiration time
+
+    .. code-block:: bash
+
+        Getting CI Target details; target: intel-corei7-64-lmp-2377, tag: master...
+        Refreshing and downloading TUF metadata for Target intel-corei7-64-lmp-2377 to 2377/tuf...
+        ERROR: Failed to download TUF metadata: HTTP error during POST 'https://api.foundries.io/ota/factories/<factory>/targets/intel-corei7-64-lmp-2377/meta/': 400 BAD REQUEST
+        = Root metadata expire (2024-07-06T07:56:57Z) before the specified expiration time (2025-02-11T09:17:39Z)
+
+        Getting production Target details; target: intel-corei7-64-lmp-2356, tag: master...
+        Refreshing and downloading TUF metadata for Target intel-corei7-64-lmp-2356 to 2356/tuf...
+        ERROR: Failed to download TUF metadata: HTTP error during POST 'https://api.foundries.io/ota/factories/<factory>/targets/intel-corei7-64-lmp-2356/meta/': 400 BAD REQUEST
+        = Targets metadata expire (2025-01-28T16:38:23Z) before the specified expiration time (2025-02-06T09:27:35Z)
+
+
+Use the ``--expires-days`` parameter of the ``fioctl targets offline-update`` command to set the desired expiration time of the bundle.
+If the command fails because the root or targets metadata expires sooner than the date specified in the parameter,
+refresh the root or targets accordingly and then re-run the command.
+
+To refresh root role metadata use one of the ``fioctl keys tuf`` commands that update the root metadata,
+for example ``fioctl keys tuf updates rotate-offline-key --role=root``.
+The expiration time is set to year since the moment when the root metadata is updated.
+
+To refresh targets role metadata use one of the following depending on targets type, CI or wave/production.
+
+* CI targets - Trigger a new CI build, it will create a new target and update CI targets role metadata expiration time to 1 year since the moment of creation.
+* Wave or production targets - Create a new wave for the given target version.
+  Use ``--expires-days`` or ``--expires-at`` parameters of the ``fioctl waves init`` command to set a desired expiration time.
+
+Therefore, the `--expires-days` parameter in the primary knob to tune the bundle expiration time up to 1 year (the maximum validity period of root metadata).
+Root and/or CI/wave/production targets refreshing serves as the secondary mechanism that should be applied
+if the desired expiration time occurs later than the root's and/or the targets' expiration, respectively.
+
+Understanding the Math Behind the Offline Update Bundle Expiration Time
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The expiration time of the bundle is determined by the expiration times of the TUF metadata it encompasses.
+Specifically, it equals the minimum value among the expiration times across all TUF roles' metadata.
+Let's review the expiration times for each TUF role, including the default values set by FoundriesFactory,
+and explore how users can manage them.
+
+* CI/Wave/Production *root* role metadata
+    The expiration time is set to 1 year from the moment a new version of the root role metadata is generated.
+    A new version is generated whenever a user makes any changes to TUF keys, such as key rotation, deletion, addition, and so forth.
+
+* CI *timestamp*, *snapshot*, and *targets* roles metadata
+    The default expiration time is set to 1 year.
+    Users have the option to overwrite this default value using the factory config parameter :ref:`tuf.targets_expire_after <def-tuf-expiration>`.
+    Additionally, the FoundriesFactory automatically refreshes these metadata for one month before their expiration.
+
+* Wave/Production *timestamp* roles metadata
+    The expiration time is set to 7 days.
+    The `TUF specification`_ recommends setting a short expiration date and re-signing it frequently.
+    This allows clients to quickly detect if they are being prevented from obtaining the most recent metadata ("indefinite freeze attacks").
+    The FoundriesFactory automatically refreshes the metadata for an additional 7 days just before expiration.
+
+* Wave/Production *snapshot* and *targets* roles metadata
+    The default expiration time is set to 1 year.
+    A user can overwrite the default value using the ``--expires-days`` or ``--expires-at parameter`` of the ``fioctl wave init`` command.
+
+The ``--expires-in-days`` parameter of the ``fioctl targets offline-update command`` instructs it to set
+the expiration time of the TUF timestamp role metadata to the one specified by the user.
+It's important to note that the user-specified expiration time is applied only to the bundle's copy
+of the metadata and does not affect the factory's metadata.
+
+
 Performing the Offline Update
 -----------------------------
 
@@ -202,5 +274,8 @@ There are a few points to take into account by the custom client application:
 .. _TUF metadata:
    https://theupdateframework.io/metadata/
 
+.. _TUF specification:
+   https://theupdateframework.github.io/specification/latest/
+
 .. _OSTree:
   https://github.com/ostreedev/ostree