Skip to content

Commit c881d30

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 c881d30

File tree

1 file changed

+17
-14
lines changed

1 file changed

+17
-14
lines changed

tuf-spec.md

Lines changed: 17 additions & 14 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,22 @@ repo](https://github.com/theupdateframework/specification/issues).
736735
, ...
737736
}
738737

739-
METAPATH is the metadata file's path on the repository relative to the
738+
METAPATH is the file path of the metadata on the repository relative to the
740739
metadata base URL.
741740

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

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

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.
749+
HASHES is a dictionary that specifies one or more hashes of the metadata
750+
file at METAPATH, including their cryptographic hash function. For example:
751+
{ "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce
752+
the snapshot metadata file size. In that case the repository MUST guarantee
753+
that VERSION alone unambiguously ientifies the metadata at METAPATH.
751754

752755
A snapshot.json example file:
753756

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

963966
* **4.6. File formats: timestamp.json**
964967

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
968+
The timestamp file is signed by a timestamp key. It indicates the latest
969+
versions the snapshot metadata and is frequently resigned to limit the
967970
amount of time a client can be kept unaware of interference with obtaining
968971
updates.
969972

0 commit comments

Comments
 (0)