From 45645a4f167788a967730bfcdfc71b18a1625021 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 | 121 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 70 insertions(+), 51 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 417a890..5e88d9e 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -789,7 +789,10 @@ repo](https://github.com/theupdateframework/specification/issues). "version" : VERSION, "expires" : EXPIRES, "targets" : TARGETS, - ("delegations" : DELEGATIONS) + ("keys_for_delegations" : { + KEYID : KEY, + ... }, + "delegations" : [ DELEGATION, ... ]) } TARGETS is an object whose format is the following: @@ -824,27 +827,27 @@ repo](https://github.com/theupdateframework/specification/issues). TARGETPATH. The application may use this information to guide download decisions. - DELEGATIONS is an object whose format is the following: + "keys_for_delegations" lists 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. - { "keys" : { - KEYID : KEY, - ... }, - "roles" : [{ - "name": ROLENAME, - "keyids" : [ KEYID, ... ] , - "threshold" : THRESHOLD, - ("path_hash_prefixes" : [ HEX_DIGEST, ... ] | - "paths" : [ PATHPATTERN, ... ]), - "terminating": TERMINATING, - }, ... ] - } + "delegations" is a list of DELEGATION objects whose format is the following: - "keys" lists 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. + { + "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, + }, ... ] + } - ROLENAME is the name of the delegated role. For example, - "projects". + DELEGATION_NAME is the name of the delegation. TERMINATING is a boolean indicating whether subsequent delegations should be considered. @@ -887,18 +890,29 @@ repo](https://github.com/theupdateframework/specification/issues). TARGETSPATH. - 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. - The metadata files for delegated target roles has the same format as the + NUM_ROLES is 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 is the name of the delegated targets role, e.g. "projects", KEYID + identifies a key that is authorized to sign for that role, and THRESHOLD + defines how many keys must sign for that role. + + 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 priorizing the first role in the list, that specifies target + metadata agreed to by at least NUM_ROLES. + + + The metadata files for delegated targets roles has the same format as the top-level targets.json metadata file. A targets.json example file: @@ -914,29 +928,34 @@ repo](https://github.com/theupdateframework/specification/issues). "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 febda3df2ac86d5d5c447a6388fc604bf80f53c6 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Tue, 5 Nov 2019 15:08:07 +0100 Subject: [PATCH 2/3] Clarify TAP3 multi-role delegation client workflow Clarify in step 4.5.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 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 5e88d9e..56389da 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -1259,9 +1259,9 @@ non-volatile storage as FILENAME.EXT. of appearance. * **4.4.2.1**. If the current delegation is a multi-role delegation, - recursively visit each role, and check that each has signed exactly the - same non-custom metadata (i.e., length and hashes) about the target (or - the lack of any such metadata). + recursively visit each role, and check that a defined threshold of + roles has signed exactly the same non-custom metadata (i.e., length and + hashes) about the target (or the lack of any such metadata). * **4.4.2.2**. If the current delegation is a terminating delegation, then jump to step 5. From 39624170582d98e32e2e02f779dcff944b361797 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 | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 56389da..82a78b7 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -789,7 +789,7 @@ repo](https://github.com/theupdateframework/specification/issues). "version" : VERSION, "expires" : EXPIRES, "targets" : TARGETS, - ("keys_for_delegations" : { + ("keys" : { KEYID : KEY, ... }, "delegations" : [ DELEGATION, ... ]) @@ -827,10 +827,9 @@ repo](https://github.com/theupdateframework/specification/issues). TARGETPATH. The application may use this information to guide download decisions. - "keys_for_delegations" lists 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. + "keys" lists 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 a list of DELEGATION objects whose format is the following: @@ -840,7 +839,7 @@ repo](https://github.com/theupdateframework/specification/issues). "paths" : [ PATHPATTERN, ... ]), "terminating": TERMINATING, "min_roles_in_agreement" : NUM_ROLES, - "roleinfo": [{ + "roles": [{ "rolename": ROLENAME, "keyids": [ KEYID ], "threshold": THRESHOLD, @@ -893,7 +892,7 @@ repo](https://github.com/theupdateframework/specification/issues). NUM_ROLES is 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" + delegated targets roles for a given delegation are listed in its "roles" field. ROLENAME is the name of the delegated targets role, e.g. "projects", KEYID @@ -905,8 +904,8 @@ repo](https://github.com/theupdateframework/specification/issues). 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 + if NUM_ROLES is less than or equal to half the number of roles in the + "roles" field, different groups of roles may have different agreements on targets hashes or lengths. Such conflicts must be resolved by priorizing the first role in the list, that specifies target metadata agreed to by at least NUM_ROLES. @@ -928,7 +927,7 @@ repo](https://github.com/theupdateframework/specification/issues). "signed": { "_type": "targets", "spec_version": "1.0.0", - "keys_for_delegations": { + "keys": { "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": { "keytype": "ed25519", "scheme": "ed25519", @@ -945,7 +944,7 @@ repo](https://github.com/theupdateframework/specification/issues). ], "terminating": true, "min_roles_in_agreement" : 1, - "roleinfo": [ + "roles": [ { "name": "project", "keyids": [ @@ -1259,9 +1258,9 @@ non-volatile storage as FILENAME.EXT. of appearance. * **4.4.2.1**. If the current delegation is a multi-role delegation, - recursively visit each role, and check that a defined threshold of - roles has signed exactly the same non-custom metadata (i.e., length and - hashes) about the target (or the lack of any such metadata). + 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). * **4.4.2.2**. If the current delegation is a terminating delegation, then jump to step 5.