diff --git a/tuf-spec.md b/tuf-spec.md index 9616036..72d38de 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": { + 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" + :: + 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,
+  "roles" : [{
+      "rolename": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD
+    }, ... ]
 }
- KEYID and KEY are the same as is described for the - root.json file. + KEYID and THRESHOLD are the same as is described + for the root.json file. - : ROLENAME + : DELEGATION_NAME :: - 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. - - : 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. + 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. -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. + : 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 "roles" field. -The metadata files for delegated target roles has the same format as the + : 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. + + +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 +"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. + +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": { + "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": { + "keytype": "ed25519", + "scheme": "ed25519", + "keyval": { + "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa" } - ] + } }, + "delegations": [ + { + "name": "project-delegation", + "paths": [ + "project/file3.txt" + ], + "terminating": true, + "min_roles_in_agreement": 1, + "roles": [ + { + "name": "project", + "keyids": [ + "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6" + ], + "threshold": 1 + } + ] + } + ], "expires": "2030-01-01T00:00:00Z", "targets": { "file1.txt": { @@ -1499,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