Skip to content

Commit d2c9c7b

Browse files
author
Lukas Puehringer
committed
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
1 parent 7f356e4 commit d2c9c7b

1 file changed

Lines changed: 90 additions & 70 deletions

File tree

‎tuf-spec.md‎

Lines changed: 90 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -931,12 +931,16 @@ The "signed" portion of <dfn>targets.json</dfn> is as follows:
931931
"version" : <a for="role">VERSION</a>,
932932
"expires" : <a>EXPIRES</a>,
933933
"targets" : <a>TARGETS</a>,
934-
("delegations" : <a>DELEGATIONS</a>)
934+
(<a>"keys_for_delegations"</a>: {
935+
<a for="root">KEYID</a> : <a>KEY</a>,
936+
... },
937+
<a>"delegations"</a> : [ <a>DELEGATION</a>, ... ])
935938
}
936939
</pre>
937940

938-
<a>SPEC_VERSION</a>, <a for="role">VERSION</a> and <a>EXPIRES</a> are the same
939-
as is described for the <a>root.json</a> file.
941+
<a>SPEC_VERSION</a>, <a for="role">VERSION</a>, <a>EXPIRES</a>,
942+
<a for="root">KEYID</a>, and <a>KEY</a> are the same as is described for the
943+
<a>root.json</a> file.
940944

941945
<dfn for="targets-obj">TARGETS</dfn> is an object whose format is the following:
942946

@@ -989,50 +993,35 @@ as is described for the <a>root.json</a> file.
989993
<a>TARGETPATH</a>. The application may use this information to guide
990994
download decisions.
991995

996+
: <dfn>"keys_for_delegations"</dfn>
997+
::
998+
A list of the public keys to verify signatures of delegated targets roles.
999+
Revocation and replacement of delegated targets roles keys is done by
1000+
changing the keys in this field in the delegating role's metadata.
1001+
9921002
<dfn>DELEGATIONS</dfn> is an OPTIONAL object and if defined it has the following
9931003
format:
994-
9951004
<pre highlight="json">
9961005
{
997-
"keys" : {
998-
<a for="role">KEYID</a> : <a>KEY</a>,
999-
...
1000-
},
1001-
"roles" : [
1002-
{
1003-
"name": <a>ROLENAME</a>,
1004-
"keyids" : [ <a for="role">KEYID</a>, ... ] ,
1005-
"threshold" : <a>THRESHOLD</a>,
1006-
(<a>"path_hash_prefixes"</a> : [ <a>HEX_DIGEST</a>, ... ] |
1007-
<a for="delegation-role">"paths"</a> : [ <a>PATHPATTERN</a>, ... ]),
1008-
"terminating": <a>TERMINATING</a>,
1009-
},
1010-
...
1011-
]
1006+
"name": <a>DELEGATION_NAME</a>,
1007+
(<a>"path_hash_prefixes"</a> : [ <a>HEX_DIGEST</a>, ... ] |
1008+
<a for="delegation-role">"paths"</a> : [ <a>PATHPATTERN</a>, ... ]),
1009+
"terminating": <a>TERMINATING</a>,
1010+
"min_roles_in_agreement": <a>NUM_ROLES</a>,
1011+
"roleinfo" : [{
1012+
"rolename": <a>ROLENAME</a>,
1013+
"keyids" : [ <a for="root">KEYID</a>, ... ] ,
1014+
"threshold" : <a>THRESHOLD</a>
1015+
}, ... ]
10121016
}
10131017
</pre>
10141018

1015-
<a for="root">KEYID</a> and <a>KEY</a> are the same as is described for the
1016-
<a>root.json</a> file.
1017-
1018-
: <dfn>ROLENAME</dfn>
1019-
::
1020-
A string giving the name of the delegated role. For example, "projects".
1021-
The rolename MUST be unique in the delegations object: multiple roles with
1022-
the same rolename are not allowed within a <a>DELEGATIONS</a>.
1019+
<a for="root">KEYID</a> and <a>THRESHOLD</a> are the same as is described
1020+
for the <a>root.json</a> file.
10231021

1024-
: <dfn>TERMINATING</dfn>
1022+
: <dfn>DELEGATION_NAME</dfn>
10251023
::
1026-
A boolean indicating whether subsequent delegations should be considered.
1027-
1028-
As explained in the [Diplomat paper
1029-
](https://theupdateframework.io/papers/protect-community-repositories-nsdi2016.pdf),
1030-
terminating delegations instruct the client not to consider future trust
1031-
statements that match the delegation's pattern, which stops the delegation
1032-
processing once this delegation (and its descendants) have been processed.
1033-
A terminating delegation for a package causes any further statements about a
1034-
package that are not made by the delegated party or its descendants to be
1035-
ignored.
1024+
A string giving the name of the delegation.
10361025

10371026
The <a>"path_hash_prefixes"</a> and <a for="delegation-role">"paths"</a>
10381027
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.
10761065
but not `"targets/foo.tgz"`
10771066
* a <a>PATHPATTERN</a> of `"foo.tgz"` would match only `"foo.tgz"`
10781067

1068+
: <dfn>TERMINATING</dfn>
1069+
::
1070+
A boolean indicating whether subsequent delegations should be considered.
1071+
1072+
As explained in the [Diplomat paper
1073+
](https://theupdateframework.io/papers/protect-community-repositories-nsdi2016.pdf),
1074+
terminating delegations instruct the client not to consider future trust
1075+
statements that match the delegation's pattern, which stops the delegation
1076+
processing once this delegation (and its descendants) have been processed.
1077+
A terminating delegation for a package causes any further statements about a
1078+
package that are not made by the delegated party or its descendants to be
1079+
ignored.
1080+
1081+
: <dfn>NUM_ROLES</dfn>
1082+
::
1083+
An integer describing the minimum number of delegated targets roles that
1084+
must be in agreement about targets hashes and lengths entrusted by the
1085+
delegation. The delegated targets roles for a given delegation are listed
1086+
in its "roleinfo" field.
1087+
1088+
: <dfn>ROLENAME</dfn>
1089+
::
1090+
A string giving the name of the delegated role. For example, "projects".
1091+
The rolename MUST be unique in the delegations object: multiple roles with
1092+
the same rolename are not allowed within a <a>DELEGATIONS</a>.
1093+
10791094

1080-
Prioritized delegations allow clients to resolve conflicts between delegated
1081-
roles that share responsibility for overlapping target paths. To resolve
1082-
conflicts, clients must consider metadata in order of appearance of delegations;
1083-
we treat the order of delegations such that the first delegation is trusted
1084-
over the second one, the second delegation is trusted more than the third
1085-
one, and so on. Likewise, the metadata of the first delegation will override that
1086-
of the second delegation, the metadata of the second delegation will override
1087-
that of the third one, etc. In order to accommodate prioritized
1088-
delegations, the "roles" key in the <a>DELEGATIONS</a> object above points to an array
1089-
of delegated roles, rather than to a hash table.
1095+
Prioritization exists both for delegations and delegated targets roles. That
1096+
is, if delegations handle overlapping targets paths, clients MUST consider
1097+
them in the order of their appearance in the "delegations" field. The
1098+
first delegation is trusted over the second one, the second delegation is
1099+
trusted over the third one, and so on. Likewise, in a multi-role delegation,
1100+
if <a>NUM_ROLES</a> is less than or equal to half the number of roles in
1101+
"roleinfo", different groups of roles may have different agreements
1102+
on targets hashes or lengths. Such conflicts must be
1103+
resolved by prioritizing the first role in the list, that specifies target
1104+
metadata agreed to by at least <a>NUM_ROLES</a>.
10901105

1091-
The metadata files for delegated target roles has the same format as the
1106+
The metadata files for delegated targets roles have the same format as the
10921107
top-level <a>targets.json</a> metadata file.
10931108

10941109
<div class="example" id="example-targets.json">
@@ -1106,29 +1121,34 @@ A <a>targets.json</a> example file:
11061121
"signed": {
11071122
"_type": "targets",
11081123
"spec_version": "1.0.0",
1109-
"delegations": {
1110-
"keys": {
1111-
"f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
1112-
"keytype": "ed25519",
1113-
"scheme": "ed25519",
1114-
"keyval": {
1115-
"public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
1116-
}
1117-
}
1118-
},
1119-
"roles": [
1120-
{
1121-
"keyids": [
1122-
"f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
1123-
],
1124-
"name": "project",
1125-
"paths": [
1126-
"project/file3.txt"
1127-
],
1128-
"threshold": 1
1124+
"keys_for_delegations": {
1125+
"f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
1126+
"keytype": "ed25519",
1127+
"scheme": "ed25519",
1128+
"keyval": {
1129+
"public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
11291130
}
1130-
]
1131+
}
11311132
},
1133+
"delegations": [
1134+
{
1135+
"name": "project-delegation",
1136+
"paths": [
1137+
"project/file3.txt"
1138+
],
1139+
"terminating": true,
1140+
"min_roles_in_agreement": 1,
1141+
"roleinfo": [
1142+
{
1143+
"name": "project",
1144+
"keyids": [
1145+
"f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
1146+
],
1147+
"threshold": 1
1148+
}
1149+
]
1150+
}
1151+
],
11321152
"expires": "2030-01-01T00:00:00Z",
11331153
"targets": {
11341154
"file1.txt": {

0 commit comments

Comments
 (0)