From cc00f7ff506af3295c44b838958560a46dbfde35 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Wed, 5 Feb 2020 11:59:36 +0000 Subject: [PATCH 01/10] LENGTH isn't optional in timestamp.json for snapshot.json In step 3 of the client application detailed workflow the spec states that the client download "up to the number of bytes specified in the timestamp metadata file" which suggests that LENGTH is not optional in the METAFILES entry for snapshot.json in the timestamp.json file. Signed-off-by: Joshua Lock --- tuf-spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 417a890..15ad23f 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -975,9 +975,9 @@ repo](https://github.com/theupdateframework/specification/issues). "meta" : METAFILES } - METAFILES is the same is described for the snapshot.json file. In the case - of the timestamp.json file, this MUST only include a description of the - snapshot.json file. + METAFILES is the same as is described for the snapshot.json file. In the + case of the timestamp.json file, this MUST only include a description of the + snapshot.json file and the LENGTH of the snapshot.json file is REQUIRED. A signed timestamp.json example file: From 0c73d445f2d6368efb1395e3b45099f1e6219466 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Wed, 5 Feb 2020 13:53:03 +0000 Subject: [PATCH 02/10] Clarify timestamp.json METAFILES format The listing for snapshot.json in timestamp.json REQUIRES both the length and the hashes field, unlike snapshot.json where these are OPTIONAL. Fixes #38 Signed-off-by: Joshua Lock --- tuf-spec.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 15ad23f..4c70218 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -975,9 +975,30 @@ repo](https://github.com/theupdateframework/specification/issues). "meta" : METAFILES } - METAFILES is the same as is described for the snapshot.json file. In the - case of the timestamp.json file, this MUST only include a description of the - snapshot.json file and the LENGTH of the snapshot.json file is REQUIRED. + METAFILES is an object whose format is the following: + + { METAPATH : { + "version" : VERSION, + "length" : LENGTH, | + "hashes" : HASHES } + , ... + } + + METAPATH is the snapshot.json file's path on the repository relative to the + metadata base URL. + + VERSION is the version of the snapshot metadata as listed in the + snapshot.json file. + + LENGTH is the integer length in bytes of the snapshot metadata file. + + HASHES is the dictionary that specifies one or more hashes of the snapshot + metadata file, including the cryptographic hash function. For example: + { "sha256": HASH, ... }. + + Note: METAFILES is the same as is described for the snapshot.json file, only + the LENGTH and HASHES are not optional and in the case of the timestamp.json + file, this MUST only include a description of the snapshot.json file. A signed timestamp.json example file: From 3ca7683fd842cdbe5c843dc343bb78b857e5320b Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Tue, 11 Feb 2020 11:33:20 +0100 Subject: [PATCH 03/10] Revert "97312dd" and "d97da38" This reverts commits: - Clarify timestamp.json METAFILES format 97312ddd239746a213694ce772e9bccbf4123f39 - LENGTH isn't optional in timestamp.json for snapshot.json d97da38eebe584c94cb1fd59be267cf87b9b38c1 --- tuf-spec.md | 25 ++----------------------- 1 file changed, 2 insertions(+), 23 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 4c70218..417a890 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -975,31 +975,10 @@ repo](https://github.com/theupdateframework/specification/issues). "meta" : METAFILES } - METAFILES is an object whose format is the following: - - { METAPATH : { - "version" : VERSION, - "length" : LENGTH, | - "hashes" : HASHES } - , ... - } - - METAPATH is the snapshot.json file's path on the repository relative to the - metadata base URL. - - VERSION is the version of the snapshot metadata as listed in the + METAFILES is the same is described for the snapshot.json file. In the case + of the timestamp.json file, this MUST only include a description of the snapshot.json file. - LENGTH is the integer length in bytes of the snapshot metadata file. - - HASHES is the dictionary that specifies one or more hashes of the snapshot - metadata file, including the cryptographic hash function. For example: - { "sha256": HASH, ... }. - - Note: METAFILES is the same as is described for the snapshot.json file, only - the LENGTH and HASHES are not optional and in the case of the timestamp.json - file, this MUST only include a description of the snapshot.json file. - A signed timestamp.json example file: { From e53f11c6e1ff69c9558b871173eb5803fee05bf5 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Tue, 11 Feb 2020 11:42:00 +0100 Subject: [PATCH 04/10] Clarify snapshot download limit on client Describe how to use a client-defined upper limit for snapshot metadata if timestamp does not specify its length. --- tuf-spec.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 417a890..dea58dc 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -1149,8 +1149,10 @@ as FILENAME.EXT. file. If the new timestamp metadata file has expired, discard it, abort the update cycle, and report the potential freeze attack. -**3**. **Download snapshot metadata file**, up to the number of bytes specified -in the timestamp metadata file. If consistent snapshots are not used (see +**3**. **Download snapshot metadata file**, up to the number of bytes +specified in the timestamp metadata file. If not specified, download up to a +number of bytes set by the authors of the application using TUF. This may be +tens of kilobytes. If consistent snapshots are not used (see Section 7), then the filename used to download the snapshot metadata file is of the fixed form FILENAME.EXT (e.g., snapshot.json). Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where From a5848e758a7aab27cb7143ecec287251a4f6d382 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Tue, 11 Feb 2020 12:25:45 +0100 Subject: [PATCH 05/10] 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). --- tuf-spec.md | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index dea58dc..07ee5c5 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -709,10 +709,9 @@ repo](https://github.com/theupdateframework/specification/issues). * **4.4. File formats: snapshot.json** - The snapshot.json file is signed by the snapshot role. It lists the version - numbers of only the top-level targets and all delegated targets role metadata. - The metadata length and hashes are OPTIONAL for the top-level targets and - all delegated targets roles. + The snapshot.json file is signed by the snapshot role. It MUST list the + version numbers of the top-level targets metadata and all delegated targets + metadata. It MAY also list their lengths and file hashes. The "signed" portion of snapshot.json is as follows: @@ -732,18 +731,23 @@ repo](https://github.com/theupdateframework/specification/issues). , ... } - METAPATH is the metadata file's path on the repository relative to the - metadata base URL. + METAPATH is the file path of the metadata on the repository relative to the + metadata base URL. For snapshot.json, these are top-level targets metadata + and delegated targets metadata. - VERSION is listed for the top-level targets and all delegated targets roles - available on the repository. + VERSION is the integer version number as shown in the metadata file at + METAPATH. - LENGTH is the integer length in bytes of the metadata file. It is - OPTIONAL for all roles. + LENGTH is the integer length in bytes of the metadata file at METAPATH. It + is OPTIONAL and can be omitted to reduce the snapshot metadata file size. In + that case the client MUST use a custom download limit for the listed + metadata. - HASHES is the dictionary that specifies one or more hashes, including - the cryptographic hash function. For example: { "sha256": HASH, ... }. It is - OPTIONAL for all roles. + HASHES is a dictionary that specifies one or more hashes of the metadata + file at METAPATH, including their cryptographic hash function. For example: + { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce + the snapshot metadata file size. In that case the repository MUST guarantee + that VERSION alone unambiguously identifies the metadata at METAPATH. A snapshot.json example file: @@ -958,8 +962,8 @@ repo](https://github.com/theupdateframework/specification/issues). * **4.6. File formats: timestamp.json** - The timestamp file is signed by a timestamp key. It indicates the - latest versions of other files and is frequently resigned to limit the + The timestamp file is signed by a timestamp key. It indicates the latest + versions the snapshot metadata and is frequently resigned to limit the amount of time a client can be kept unaware of interference with obtaining updates. From e360733f434cb91964ea67431ddb780a41215d48 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Tue, 3 Mar 2020 10:53:02 +0100 Subject: [PATCH 06/10] Fix typo in "4.6. File formats: timestamp.json" --- tuf-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tuf-spec.md b/tuf-spec.md index 07ee5c5..faa5a38 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -963,7 +963,7 @@ repo](https://github.com/theupdateframework/specification/issues). * **4.6. File formats: timestamp.json** The timestamp file is signed by a timestamp key. It indicates the latest - versions the snapshot metadata and is frequently resigned to limit the + version of the snapshot metadata and is frequently resigned to limit the amount of time a client can be kept unaware of interference with obtaining updates. From 4f6ce2ef14be381d167f5724956e0eb1c7816ff4 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Tue, 3 Mar 2020 11:05:53 +0000 Subject: [PATCH 07/10] Ensure steps in the detailed workflow are consistent in use of variables Update the modified step 3 to use a named variable for the application author defined number of bytes to download a snapshot metadata file. Re-name prior variables, starting at W, to ensure an alphabetically consistent list of variables used in each step. Signed-off-by: Joshua Lock --- tuf-spec.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index faa5a38..c0bf195 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -1076,8 +1076,8 @@ repo](https://github.com/theupdateframework/specification/issues). * **1.1**. Let N denote the version number of the trusted root metadata file. * **1.2**. **Try downloading version N+1 of the root metadata file**, up to - some X number of bytes (because the size is unknown). The value for X is set - by the authors of the application using TUF. For example, X may be tens of + some W number of bytes (because the size is unknown). The value for W is set + by the authors of the application using TUF. For example, W may be tens of kilobytes. The filename used to download the root metadata file is of the fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is not available, or we have downloaded more than Y number of root metadata files @@ -1129,9 +1129,9 @@ repo](https://github.com/theupdateframework/specification/issues). * **1.10**. **Set whether consistent snapshots are used as per the trusted root metadata file** (see Section 4.3). -**2**. **Download the timestamp metadata file**, up to Y number of bytes -(because the size is unknown.) The value for Y is set by the authors of the -application using TUF. For example, Y may be tens of kilobytes. The filename +**2**. **Download the timestamp metadata file**, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename used to download the timestamp metadata file is of the fixed form FILENAME.EXT (e.g., timestamp.json). The client MUST write the file to non-volatile storage as FILENAME.EXT. @@ -1153,9 +1153,9 @@ as FILENAME.EXT. file. If the new timestamp metadata file has expired, discard it, abort the update cycle, and report the potential freeze attack. -**3**. **Download snapshot metadata file**, up to the number of bytes -specified in the timestamp metadata file. If not specified, download up to a -number of bytes set by the authors of the application using TUF. This may be +**3**. **Download snapshot metadata file**, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be tens of kilobytes. If consistent snapshots are not used (see Section 7), then the filename used to download the snapshot metadata file is of the fixed form FILENAME.EXT (e.g., snapshot.json). Otherwise, the filename is From d8dcf66186dbbfc7131b8b0873eab75373336279 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Tue, 3 Mar 2020 11:12:05 +0000 Subject: [PATCH 08/10] Bump patch version to 1.0.1 Signed-off-by: Joshua Lock --- tuf-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tuf-spec.md b/tuf-spec.md index c0bf195..1c3c45e 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -2,7 +2,7 @@ Last modified: **5 March 2020** -Version: **1.0.0** +Version: **1.0.1** We strive to make the specification easy to implement, so if you come across any inconsistencies or experience any difficulty, do let us know by sending an From 081e56a20dec4fabf68ea9075c9c90d37a7f365d Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Thu, 5 Mar 2020 11:14:52 +0100 Subject: [PATCH 09/10] Clarify snapshot+targets metadata hash check Update the client workflow to clarify that snapshot metadata hashes can only be checked if timestamp lists the optional hashes, and, similarly, targets metadata hashes can only be checked if snapshot lists the optional hashes. --- tuf-spec.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 1c3c45e..9a78add 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -1165,10 +1165,10 @@ the timestamp metadata file. In either case, the client MUST write the file to non-volatile storage as FILENAME.EXT. * **3.1**. **Check against timestamp metadata.** The hashes and version - number of the new snapshot metadata file MUST match the hashes and version - number listed in timestamp metadata. If hashes and version do not match, - discard the new snapshot metadata, abort the update cycle, and report the - failure. + number of the new snapshot metadata file MUST match the hashes (if any) and + version number listed in the trusted timestamp metadata. If hashes and + version do not match, discard the new snapshot metadata, abort the update + cycle, and report the failure. * **3.2**. **Check signatures.** The new snapshot metadata file MUST have been signed by a threshold of keys specified in the trusted root metadata @@ -1213,11 +1213,12 @@ VERSION_NUMBER is the version number of the targets metadata file listed in the snapshot metadata file. In either case, the client MUST write the file to non-volatile storage as FILENAME.EXT. - * **4.1**. **Check against snapshot metadata.** The hashes (if any), and - version number of the new targets metadata file MUST match the trusted - snapshot metadata. This is done, in part, to prevent a mix-and-match attack - by man-in-the-middle attackers. If the new targets metadata file does not - match, discard it, abort the update cycle, and report the failure. + * **4.1**. **Check against snapshot metadata.** The hashes and version + number of the new targets metadata file MUST match the hashes (if any) and + version number listed in the trusted snapshot metadata. This is done, in + part, to prevent a mix-and-match attack by man-in-the-middle attackers. If + the new targets metadata file does not match, discard it, abort the update + cycle, and report the failure. * **4.2**. **Check for an arbitrary software attack.** The new targets metadata file MUST have been signed by a threshold of keys specified in the From 53f6ea3ef7e2858c56012f4e34541e801dec9664 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Fri, 6 Mar 2020 09:44:24 +0100 Subject: [PATCH 10/10] Update Last modified: **6 March 2020** --- tuf-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tuf-spec.md b/tuf-spec.md index 9a78add..3fc49d5 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -1,6 +1,6 @@ #

The Update Framework Specification -Last modified: **5 March 2020** +Last modified: **6 March 2020** Version: **1.0.1**