Skip to content

Commit 6933985

Browse files
committed
Clarify snapshot and timestamp METAFILES
Generally clarify what files are listed under METAFILES in snapshot.json and timestamp.json and under what circumstances the LENGTH and HASHES field for a METAFILE can be omitted (and why it should be omitted).
1 parent 170b063 commit 6933985

File tree

1 file changed

+19
-15
lines changed

1 file changed

+19
-15
lines changed

tuf-spec.md

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -713,10 +713,9 @@ repo](https://github.com/theupdateframework/specification/issues).
713713

714714
* **4.4. File formats: snapshot.json**
715715

716-
The snapshot.json file is signed by the snapshot role. It lists the version
717-
numbers of only the top-level targets and all delegated targets role metadata.
718-
The metadata length and hashes are OPTIONAL for the top-level targets and
719-
all delegated targets roles.
716+
The snapshot.json file is signed by the snapshot role. It MUST list the
717+
version numbers of the top-level targets metadata and all delegated targets
718+
metadata. It MAY also list their lengths and file hashes.
720719

721720
The "signed" portion of snapshot.json is as follows:
722721

@@ -736,18 +735,23 @@ repo](https://github.com/theupdateframework/specification/issues).
736735
, ...
737736
}
738737

739-
METAPATH is the metadata file's path on the repository relative to the
740-
metadata base URL.
738+
METAPATH is the file path of the metadata on the repository relative to the
739+
metadata base URL. For snapshot.json, these are top-level targets metadata
740+
and delegated targets metadata.
741741

742-
VERSION is listed for the top-level targets and all delegated targets roles
743-
available on the repository.
742+
VERSION is the integer version number as shown in the metadata file at
743+
METAPATH.
744744

745-
LENGTH is the integer length in bytes of the metadata file. It is
746-
OPTIONAL for all roles.
745+
LENGTH is the integer length in bytes of the metadata file at METAPATH. It
746+
is OPTIONAL and can be omitted to reduce the snapshot metadata file size. In
747+
that case the client MUST use a custom download limit for the listed
748+
metadata.
747749

748-
HASHES is the dictionary that specifies one or more hashes, including
749-
the cryptographic hash function. For example: { "sha256": HASH, ... }. It is
750-
OPTIONAL for all roles.
750+
HASHES is a dictionary that specifies one or more hashes of the metadata
751+
file at METAPATH, including their cryptographic hash function. For example:
752+
{ "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce
753+
the snapshot metadata file size. In that case the repository MUST guarantee
754+
that VERSION alone unambiguously identifies the metadata at METAPATH.
751755

752756
A snapshot.json example file:
753757

@@ -962,8 +966,8 @@ repo](https://github.com/theupdateframework/specification/issues).
962966

963967
* **4.6. File formats: timestamp.json**
964968

965-
The timestamp file is signed by a timestamp key. It indicates the
966-
latest versions of other files and is frequently resigned to limit the
969+
The timestamp file is signed by a timestamp key. It indicates the latest
970+
versions the snapshot metadata and is frequently resigned to limit the
967971
amount of time a client can be kept unaware of interference with obtaining
968972
updates.
969973

0 commit comments

Comments
 (0)