diff --git a/source/user-guide/offline-update/offline-update.rst b/source/user-guide/offline-update/offline-update.rst index 7a178bac..c34599a6 100644 --- a/source/user-guide/offline-update/offline-update.rst +++ b/source/user-guide/offline-update/offline-update.rst @@ -52,6 +52,78 @@ 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*, 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 `. + 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