From 40b590a7f4c79f12bab80872c0187f9396c92939 Mon Sep 17 00:00:00 2001 From: marinamoore Date: Wed, 3 Jun 2020 14:09:02 -0700 Subject: [PATCH 1/7] Replace strict JSON requirement with a flexible requirement. Clarify that file extensions may change if a different data format is used. --- tuf-spec.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 09c7d67..7268fa8 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -411,34 +411,36 @@ repo](https://github.com/theupdateframework/specification/issues). + **3.1.2 Metadata files** The filenames and directory structure of repository metadata are strictly - defined. The following are the metadata files of top-level roles relative + defined. All metadata filenames will have an extension based on the + metaformat, for example json metadata files would have an EXT of json. + The following are the metadata files of top-level roles relative to the base URL of metadata available from a given repository mirror. - /root.json + /root.EXT Signed by the root keys; specifies trusted keys for the other top-level roles. - /snapshot.json + /snapshot.EXT Signed by the snapshot role's keys. Lists the version numbers of all - target metadata files: the top-level targets.json and all delegated + target metadata files: the top-level targets.EXT and all delegated roles. - /targets.json + /targets.EXT Signed by the target role's keys. Lists hashes and sizes of target files. Specifies delegation information and trusted keys for delegated target roles. - /timestamp.json + /timestamp.EXT Signed by the timestamp role's keys. Lists hash(es), size, and version number of the snapshot file. This is the first and potentially only file that needs to be downloaded when clients poll for the existence of updates. - /mirrors.json (optional) + /mirrors.EXT (optional) Signed by the mirrors role's keys. Lists information about available mirrors and the content available from each mirror. @@ -452,13 +454,13 @@ repo](https://github.com/theupdateframework/specification/issues). A delegated role file is located at: - /DELEGATED_ROLE.json + /DELEGATED_ROLE.EXT where DELEGATED_ROLE is the name of the delegated role that has been - specified in targets.json. If this role further delegates trust to a role + specified in targets.EXT. If this role further delegates trust to a role named ANOTHER_ROLE, that role's signed metadata file is made available at: - /ANOTHER_ROLE.json + /ANOTHER_ROLE.EXT Delegated target roles are authorized by the keys listed in the directly delegating target role. @@ -472,7 +474,9 @@ repo](https://github.com/theupdateframework/specification/issues). * **4.1. Metaformat** - All documents use a subset of the JSON object format, with + Implementers of TUF may use any data format for metadata files as long as + all fields in this specification are included. The examples in this document + use a subset of the JSON object format, with floating-point numbers omitted. When calculating the digest of an object, we use the "canonical JSON" subdialect as described at http://wiki.laptop.org/go/Canonical_JSON From 7433b438398c50437a450417229984eb0860100a Mon Sep 17 00:00:00 2001 From: marinamoore Date: Thu, 4 Jun 2020 08:05:50 -0700 Subject: [PATCH 2/7] remove references to json --- tuf-spec.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 7268fa8..371ba78 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -332,7 +332,7 @@ repo](https://github.com/theupdateframework/specification/issues). The snapshot role signs a metadata file that provides information about the latest version of all targets metadata on the repository - (the top-level targets.json and all delegated roles). This information allows + (the top-level targets role and all delegated roles). This information allows clients to know which metadata files have been updated and also prevents mix-and-match attacks. @@ -498,8 +498,7 @@ repo](https://github.com/theupdateframework/specification/issues). KEYID is the identifier of the key signing the ROLE dictionary. - SIGNATURE is a hex-encoded signature of the canonical JSON form of - ROLE. + SIGNATURE is a hex-encoded signature of the metadata for ROLE. All keys have the format: @@ -572,7 +571,7 @@ repo](https://github.com/theupdateframework/specification/issues). PUBLIC is in PEM format and a string. The KEYID of a key is the hexdigest of the SHA-256 hash of the - canonical JSON form of the key. + metadata format encoding of the key. Metadata date-time data follows the ISO 8601 standard. The expected format of the combined date and time string is "YYYY-MM-DDTHH:MM:SSZ". Time is From 660b71efc4899b6b5e7b009cee109c48a8232000 Mon Sep 17 00:00:00 2001 From: marinamoore Date: Fri, 5 Jun 2020 09:11:27 -0700 Subject: [PATCH 3/7] add canonicalization requirement for metaformat --- tuf-spec.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 371ba78..db24947 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -475,8 +475,11 @@ repo](https://github.com/theupdateframework/specification/issues). * **4.1. Metaformat** Implementers of TUF may use any data format for metadata files as long as - all fields in this specification are included. The examples in this document - use a subset of the JSON object format, with + all fields in this specification are included and TUF clients are able to + interpret them without ambiguity. Implementers should choose a data format + that allows for canonicalization, or one that will decode data + deterministically by default so that signatures can be accurately verified. + The examples in this document use a subset of the JSON object format, with floating-point numbers omitted. When calculating the digest of an object, we use the "canonical JSON" subdialect as described at http://wiki.laptop.org/go/Canonical_JSON @@ -498,7 +501,8 @@ repo](https://github.com/theupdateframework/specification/issues). KEYID is the identifier of the key signing the ROLE dictionary. - SIGNATURE is a hex-encoded signature of the metadata for ROLE. + SIGNATURE is a hex-encoded signature of the canonical form of + the metadata for ROLE. All keys have the format: From d2e2b8e966bae77409199d5b0bb7a7fc0962f846 Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Fri, 5 Jun 2020 09:12:07 -0700 Subject: [PATCH 4/7] Update tuf-spec.md Co-authored-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 db24947..a10d7e8 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -411,7 +411,7 @@ repo](https://github.com/theupdateframework/specification/issues). + **3.1.2 Metadata files** The filenames and directory structure of repository metadata are strictly - defined. All metadata filenames will have an extension based on the + defined. All metadata filenames will have an extension (EXT) based on the metaformat, for example json metadata files would have an EXT of json. The following are the metadata files of top-level roles relative to the base URL of metadata available from a given repository mirror. From 7847845c408d879ef69cdc2cfd27215a1e140d9d Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Tue, 9 Jun 2020 07:11:41 -0700 Subject: [PATCH 5/7] Update tuf-spec.md Co-authored-by: lukpueh --- tuf-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tuf-spec.md b/tuf-spec.md index a10d7e8..b0ce351 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -575,7 +575,7 @@ repo](https://github.com/theupdateframework/specification/issues). PUBLIC is in PEM format and a string. The KEYID of a key is the hexdigest of the SHA-256 hash of the - metadata format encoding of the key. + canonical form of the key. Metadata date-time data follows the ISO 8601 standard. The expected format of the combined date and time string is "YYYY-MM-DDTHH:MM:SSZ". Time is From 402faf3c02ec636c4eb4df127c825067b98630df Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Tue, 9 Jun 2020 07:46:37 -0700 Subject: [PATCH 6/7] Update tuf-spec.md Co-authored-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 b0ce351..74f25ea 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -412,7 +412,7 @@ repo](https://github.com/theupdateframework/specification/issues). The filenames and directory structure of repository metadata are strictly defined. All metadata filenames will have an extension (EXT) based on the - metaformat, for example json metadata files would have an EXT of json. + metaformat, for example JSON metadata files would have an EXT of json. The following are the metadata files of top-level roles relative to the base URL of metadata available from a given repository mirror. From a765b3e1275cd023d5fe11ad08fb296c3eb95ff3 Mon Sep 17 00:00:00 2001 From: marinamoore Date: Tue, 9 Jun 2020 07:51:24 -0700 Subject: [PATCH 7/7] update version and date --- tuf-spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 74f25ea..d313f09 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -1,8 +1,8 @@ #

The Update Framework Specification -Last modified: **2 June 2020** +Last modified: **9 June 2020** -Version: **1.0.3** +Version: **1.0.4** 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