From d2c9c7bf2330879b8229f4885b5b25e62f82c4c3 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Wed, 30 Oct 2019 17:32:01 +0100 Subject: [PATCH 1/3] Adopt TAP 3 multi-role delegations metadata format Update "4.5. File formats: targets.json and delegated target roles" to reflect metadata format introduced by TAP 3 --- tuf-spec.md | 160 +++++++++++++++++++++++++++++----------------------- 1 file changed, 90 insertions(+), 70 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 9616036..6b8dffe 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -931,12 +931,16 @@ The "signed" portion of targets.json is as follows: "version" : VERSION, "expires" : EXPIRES, "targets" : TARGETS, - ("delegations" : DELEGATIONS) + ("keys_for_delegations": { + KEYID : KEY, + ... }, + "delegations" : [ DELEGATION, ... ]) } -SPEC_VERSION, VERSION and EXPIRES are the same -as is described for the root.json file. +SPEC_VERSION, VERSION, EXPIRES, +KEYID, and KEY are the same as is described for the +root.json file. TARGETS is an object whose format is the following: @@ -989,50 +993,35 @@ as is described for the root.json file. TARGETPATH. The application may use this information to guide download decisions. + : "keys_for_delegations" + :: + A list of the public keys to verify signatures of delegated targets roles. + Revocation and replacement of delegated targets roles keys is done by + changing the keys in this field in the delegating role's metadata. + DELEGATIONS is an OPTIONAL object and if defined it has the following format: - 
 {
-  "keys" : {
-      KEYID : KEY,
-      ...
-  },
-  "roles" : [
-    {
-      "name": ROLENAME,
-      "keyids" : [ KEYID, ... ] ,
-      "threshold" : THRESHOLD,
-      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
-      "paths" : [ PATHPATTERN, ... ]),
-      "terminating": TERMINATING,
-    },
-    ...
-  ]
+  "name": DELEGATION_NAME,
+  ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+  "paths" : [ PATHPATTERN, ... ]),
+  "terminating": TERMINATING,
+  "min_roles_in_agreement": NUM_ROLES,
+  "roleinfo" : [{
+      "rolename": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD
+    }, ... ]
 }
- KEYID and KEY are the same as is described for the - root.json file. - - : ROLENAME - :: - A string giving the name of the delegated role. For example, "projects". - The rolename MUST be unique in the delegations object: multiple roles with - the same rolename are not allowed within a DELEGATIONS. + KEYID and THRESHOLD are the same as is described + for the root.json file. - : TERMINATING + : DELEGATION_NAME :: - A boolean indicating whether subsequent delegations should be considered. - - As explained in the [Diplomat paper - ](https://theupdateframework.io/papers/protect-community-repositories-nsdi2016.pdf), - terminating delegations instruct the client not to consider future trust - statements that match the delegation's pattern, which stops the delegation - processing once this delegation (and its descendants) have been processed. - A terminating delegation for a package causes any further statements about a - package that are not made by the delegated party or its descendants to be - ignored. + A string giving the name of the delegation. The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set. @@ -1076,19 +1065,45 @@ attributes are OPTIONAL, if used, exactly one of them should be set. but not `"targets/foo.tgz"` * a PATHPATTERN of `"foo.tgz"` would match only `"foo.tgz"` + : TERMINATING + :: + A boolean indicating whether subsequent delegations should be considered. + + As explained in the [Diplomat paper + ](https://theupdateframework.io/papers/protect-community-repositories-nsdi2016.pdf), + terminating delegations instruct the client not to consider future trust + statements that match the delegation's pattern, which stops the delegation + processing once this delegation (and its descendants) have been processed. + A terminating delegation for a package causes any further statements about a + package that are not made by the delegated party or its descendants to be + ignored. + + : NUM_ROLES + :: + An integer describing the minimum number of delegated targets roles that + must be in agreement about targets hashes and lengths entrusted by the + delegation. The delegated targets roles for a given delegation are listed + in its "roleinfo" field. + + : ROLENAME + :: + A string giving the name of the delegated role. For example, "projects". + The rolename MUST be unique in the delegations object: multiple roles with + the same rolename are not allowed within a DELEGATIONS. + -Prioritized delegations allow clients to resolve conflicts between delegated -roles that share responsibility for overlapping target paths. To resolve -conflicts, clients must consider metadata in order of appearance of delegations; -we treat the order of delegations such that the first delegation is trusted -over the second one, the second delegation is trusted more than the third -one, and so on. Likewise, the metadata of the first delegation will override that -of the second delegation, the metadata of the second delegation will override -that of the third one, etc. In order to accommodate prioritized -delegations, the "roles" key in the DELEGATIONS object above points to an array -of delegated roles, rather than to a hash table. +Prioritization exists both for delegations and delegated targets roles. That +is, if delegations handle overlapping targets paths, clients MUST consider +them in the order of their appearance in the "delegations" field. The +first delegation is trusted over the second one, the second delegation is +trusted over the third one, and so on. Likewise, in a multi-role delegation, +if NUM_ROLES is less than or equal to half the number of roles in +"roleinfo", different groups of roles may have different agreements +on targets hashes or lengths. Such conflicts must be +resolved by prioritizing the first role in the list, that specifies target +metadata agreed to by at least NUM_ROLES. -The metadata files for delegated target roles has the same format as the +The metadata files for delegated targets roles have the same format as the top-level targets.json metadata file.
@@ -1106,29 +1121,34 @@ A targets.json example file: "signed": { "_type": "targets", "spec_version": "1.0.0", - "delegations": { - "keys": { - "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": { - "keytype": "ed25519", - "scheme": "ed25519", - "keyval": { - "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa" - } - } - }, - "roles": [ - { - "keyids": [ - "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6" - ], - "name": "project", - "paths": [ - "project/file3.txt" - ], - "threshold": 1 + "keys_for_delegations": { + "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": { + "keytype": "ed25519", + "scheme": "ed25519", + "keyval": { + "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa" } - ] + } }, + "delegations": [ + { + "name": "project-delegation", + "paths": [ + "project/file3.txt" + ], + "terminating": true, + "min_roles_in_agreement": 1, + "roleinfo": [ + { + "name": "project", + "keyids": [ + "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6" + ], + "threshold": 1 + } + ] + } + ], "expires": "2030-01-01T00:00:00Z", "targets": { "file1.txt": { From e14fdd1fbe3eb1050a2f8da71d0431081592bd5c Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Mon, 30 Nov 2020 10:05:55 +0000 Subject: [PATCH 2/3] Clarify TAP3 multi-role delegation client workflow Clarify in step 5.6.7.2.1 of the client workflow that in a multi-role delegation not each but rather a defined threshold of roles must agree on the target hashes and lengths (see `min_roles_in_agreement`). --- tuf-spec.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/tuf-spec.md b/tuf-spec.md index 6b8dffe..74d38e0 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -1519,7 +1519,12 @@ it in the next step. 2. Otherwise, recursively search the list of delegations in order of appearance. - 1. If the current delegation is a terminating delegation, + 1. If the current delegation is a multi-role delegation, + recursively visit each role, and check that a defined minimum number of + roles agrees about non-custom metadata, i.e. length and hashes of the + target (or the lack of any such metadata). + + 2. If the current delegation is a terminating delegation, then jump to step [[#fetch-target]]. 2. Otherwise, if the current delegation is a From b8d16e941162e41363d86ee67e37a7fc5ed476c5 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Thu, 7 Nov 2019 17:12:17 +0100 Subject: [PATCH 3/3] Rename TAP 3 metadata fields `keys_for_delegations` --> `keys` (the keys field in root.json in reality also lists "keys for delegations", i.e. keys to delegate trust to other top-level roles, but is only called keys) `roleinfo` --> `roles` (keeping the name for delegated roles as it was before TAP3) --- tuf-spec.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 74d38e0..72d38de 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -931,7 +931,7 @@ The "signed" portion of targets.json is as follows: "version" : VERSION, "expires" : EXPIRES, "targets" : TARGETS, - ("keys_for_delegations": { + ("keys": { KEYID : KEY, ... }, "delegations" : [ DELEGATION, ... ]) @@ -993,7 +993,7 @@ The "signed" portion of targets.json is as follows: TARGETPATH. The application may use this information to guide download decisions. - : "keys_for_delegations" + : "keys" :: A list of the public keys to verify signatures of delegated targets roles. Revocation and replacement of delegated targets roles keys is done by @@ -1008,7 +1008,7 @@ format: "paths" : [ PATHPATTERN, ... ]), "terminating": TERMINATING, "min_roles_in_agreement": NUM_ROLES, - "roleinfo" : [{ + "roles" : [{ "rolename": ROLENAME, "keyids" : [ KEYID, ... ] , "threshold" : THRESHOLD @@ -1083,7 +1083,7 @@ attributes are OPTIONAL, if used, exactly one of them should be set. An integer describing the minimum number of delegated targets roles that must be in agreement about targets hashes and lengths entrusted by the delegation. The delegated targets roles for a given delegation are listed - in its "roleinfo" field. + in its "roles" field. : ROLENAME :: @@ -1098,7 +1098,7 @@ them in the order of their appearance in the "delegations" field. The first delegation is trusted over the second one, the second delegation is trusted over the third one, and so on. Likewise, in a multi-role delegation, if NUM_ROLES is less than or equal to half the number of roles in -"roleinfo", different groups of roles may have different agreements +"roles" field, different groups of roles may have different agreements on targets hashes or lengths. Such conflicts must be resolved by prioritizing the first role in the list, that specifies target metadata agreed to by at least NUM_ROLES. @@ -1121,7 +1121,7 @@ A targets.json example file: "signed": { "_type": "targets", "spec_version": "1.0.0", - "keys_for_delegations": { + "keys": { "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": { "keytype": "ed25519", "scheme": "ed25519", @@ -1138,7 +1138,7 @@ A targets.json example file: ], "terminating": true, "min_roles_in_agreement": 1, - "roleinfo": [ + "roles": [ { "name": "project", "keyids": [