From 107be1580502b1c411aadd303b4758431bbee6e3 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Thu, 11 Nov 2021 13:21:10 +0000 Subject: [PATCH] Clean up "Writing consistent snapshots" section (#187) * Match how metadata and target filenames are referred to in the detailed client workflow, i.e. filename.ext -> FILENAME.EXT * Remove suggestion to write a version of the root metadata without a version prefix. We only ever look for version-prefixed version of root metadata. * More use of RFC-2119 keywords to clarify repository handling of consistent snapshots * Link to CONSISTENT_SNAPSHOT attribute definition * Clarify that all versions of root metadata MUST be kept for outdated clients to be able to update Signed-off-by: Joshua Lock Co-authored-by: lukpueh Co-authored-by: Trishank Karthik Kuppusamy --- tuf-spec.md | 66 +++++++++++++++++++++++++---------------------------- 1 file changed, 31 insertions(+), 35 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index a4ddc83..164c6b5 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -3,7 +3,7 @@ Title: The Update Framework Specification Shortname: TUF Status: LS Abstract: A framework for securing software update systems. -Date: 2021-09-07 +Date: 2021-09-21 Editor: Justin Cappos, NYU Editor: Trishank Karthik Kuppusamy, Datadog Editor: Joshua Lock, VMware @@ -16,7 +16,7 @@ Boilerplate: copyright no, conformance no Local Boilerplate: header yes Markup Shorthands: css no, markdown yes Metadata Include: This version off, Abstract off -Text Macro: VERSION 1.0.25 +Text Macro: VERSION 1.0.26 Note: We strive to make the specification easy to implement, so if you come @@ -1585,49 +1585,45 @@ without interrupting that client. We now explain how a repository should write metadata and targets to produce self-contained consistent snapshots. -Simply put, TUF should write every metadata file as such: if the -file had the original name of filename.ext, then it should be written to -non-volatile storage as version_number.filename.ext, where version_number -is an integer. +Simply put, every metadata file MUST be named as such: if the +file had the original name of FILENAME.EXT, then it MUST be written to +non-volatile storage as VERSION_NUMBER.FILENAME.EXT, where VERSION_NUMBER +is the integer version number listed in the metadata file. -On the other hand, consistent target files should be written to -non-volatile storage as digest.filename.ext. This means that if the +On the other hand, consistent target files MUST be written to +non-volatile storage as HASH.FILENAME.EXT. This means that if the referrer metadata lists N cryptographic hashes of the referred file, then -there must be N identical copies of the referred file, where each file will +there MUST be N identical copies of the referred file, where each file will be distinguished only by the value of the digest in its filename. The modified filename need not include the name of the cryptographic hash function used to produce the digest because, on a read, the choice of function follows from the selection of a digest (which includes the name of the cryptographic function) from all digests in the referred file. -Additionally, the timestamp metadata (timestamp.json) should also be -written to non-volatile storage whenever it is updated. It is OPTIONAL for -an implementation to write identical copies at -version_number.timestamp.json for record-keeping purposes, because a -cryptographic hash of the timestamp metadata is usually not known in -advance. The same step applies to the root metadata (root.json), although -an implementation must write both root.json and version_number.root.json -because it is possible to download root metadata both with and without -known version numbers. These steps are required because these are the only -metadata files that may be requested without known version numbers. - -Most importantly, no metadata file format must be updated to refer to the -names of metadata or target files with their version numbers included. In -other words, if a metadata file A refers to another metadata file B as -filename.ext, then the filename must remain as filename.ext and not -version_number.filename.ext. This rule is in place so that metadata signed -by roles with offline keys will not be forced to sign for the metadata file -whenever it is updated. In the next subsection, we will see how clients -will reproduce the name of the intended file. - -Finally, the root metadata should write the Boolean "consistent_snapshot" -attribute at the root level of its keys of attributes. If consistent -snapshots are not written by the repository, then the attribute may either -be left unspecified or be set to the False value. Otherwise, it must be -set to the True value. +Timestamp metadata (timestamp.EXT) MUST be written to non-volatile storage +without a version prefix whenever it is updated. This is required because +timestamp metadata is the only metadata file that may be requested without known +version numbers. It is OPTIONAL for an implementation to write an identical copy +of timestamp.EXT to the respective VERSION_NUMBER.timestamp.EXT for +record-keeping purposes. + +Most importantly, metadata file formats SHALL NOT be updated to refer to the +names of metadata or target files with their consistent snapshot prefix +included. In other words, if a metadata file A refers to another metadata file B +as FILENAME.EXT, then the filename listed in the metadata MUST remain as +FILENAME.EXT and not VERSION_NUMBER.FILENAME.EXT. This rule is in place so that +metadata signed by roles with offline keys will not be forced to sign for the +metadata file whenever it is updated. In the next subsection, we will see how +clients will reproduce the name of the intended file. + +Finally, when consistent snapshots are written by the repository the root +metadata MUST write the boolean CONSISTENT_SNAPSHOT attribute at the root +level of its keys of attributes set to the true value. If consistent snapshots +are not written by the repository, then the attribute MAY either be left +unspecified or be set to the false value. Regardless of whether consistent snapshots are ever used or not, all -released versions of root metadata files should always be provided +released versions of root metadata files MUST always be provided so that outdated clients can update to the latest available root.