From 97721ff784d6324e2f7dd06dd7e7446759f1aa0b Mon Sep 17 00:00:00 2001 From: Mike Sul Date: Mon, 12 Feb 2024 11:28:01 +0100 Subject: [PATCH] ug: offline-update: Add info on bundle expiration Signed-off-by: Mike Sul --- .../offline-update/offline-update.rst | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/source/user-guide/offline-update/offline-update.rst b/source/user-guide/offline-update/offline-update.rst index 7a178bac..adaa382e 100644 --- a/source/user-guide/offline-update/offline-update.rst +++ b/source/user-guide/offline-update/offline-update.rst @@ -52,6 +52,76 @@ Use the command ``fioctl targets offline-update <--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//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//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``, ``Targets`` + 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 `. + Additionally, the FoundriesFactory automatically refreshes these metadata for one month before their expiration. + +* Wave/Production ``Timestamp`` + The expiration time is set to 7 days. + The FoundriesFactory automatically refreshes the metadata for an additional 7 days just before expiration. + +* Wave/Production ``Snapshot``,``Targets`` + 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 -----------------------------