Skip to content

Commit 4bae5d8

Browse files
lukpuehlukpueh
authored
Merge pull request #57 from lukpueh/adopt-tap3-metadata
Adopt TAP 3 multi-role delegations metadata format
2 parents 69b8456 + 3962417 commit 4bae5d8

File tree

1 file changed

+72
-54
lines changed

1 file changed

+72
-54
lines changed

‎tuf-spec.md

Lines changed: 72 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -793,7 +793,10 @@ repo](https://github.com/theupdateframework/specification/issues).
793793
"version" : VERSION,
794794
"expires" : EXPIRES,
795795
"targets" : TARGETS,
796-
("delegations" : DELEGATIONS)
796+
("keys" : {
797+
KEYID : KEY,
798+
... },
799+
"delegations" : [ DELEGATION, ... ])
797800
}
798801

799802
TARGETS is an object whose format is the following:
@@ -828,27 +831,26 @@ repo](https://github.com/theupdateframework/specification/issues).
828831
TARGETPATH. The application may use this information to guide download
829832
decisions.
830833

831-
DELEGATIONS is an object whose format is the following:
834+
"keys" lists the public keys to verify signatures of delegated targets
835+
roles. Revocation and replacement of delegated targets roles keys is done by
836+
changing the keys in this field in the delegating role's metadata.
832837

833-
{ "keys" : {
834-
KEYID : KEY,
835-
... },
836-
"roles" : [{
837-
"name": ROLENAME,
838-
"keyids" : [ KEYID, ... ] ,
839-
"threshold" : THRESHOLD,
840-
("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
841-
"paths" : [ PATHPATTERN, ... ]),
842-
"terminating": TERMINATING,
843-
}, ... ]
844-
}
838+
"delegations" is a list of DELEGATION objects whose format is the following:
845839

846-
"keys" lists the public keys to verify signatures of delegated targets roles.
847-
Revocation and replacement of delegated targets roles keys is done by
848-
changing the keys in this field in the delegating role's metadata.
840+
{
841+
"name": DELEGATION_NAME,
842+
("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
843+
"paths" : [ PATHPATTERN, ... ]),
844+
"terminating": TERMINATING,
845+
"min_roles_in_agreement" : NUM_ROLES,
846+
"roles": [{
847+
"rolename": ROLENAME,
848+
"keyids": [ KEYID ],
849+
"threshold": THRESHOLD,
850+
}, ... ]
851+
}
849852

850-
ROLENAME is the name of the delegated role. For example,
851-
"projects".
853+
DELEGATION_NAME is the name of the delegation.
852854

853855
TERMINATING is a boolean indicating whether subsequent delegations should be
854856
considered.
@@ -891,18 +893,29 @@ repo](https://github.com/theupdateframework/specification/issues).
891893
TARGETSPATH.
892894

893895

894-
Prioritized delegations allow clients to resolve conflicts between delegated
895-
roles that share responsibility for overlapping target paths. To resolve
896-
conflicts, clients must consider metadata in order of appearance of delegations;
897-
we treat the order of delegations such that the first delegation is trusted
898-
over the second one, the second delegation is trusted more than the third
899-
one, and so on. Likewise, the metadata of the first delegation will override that
900-
of the second delegation, the metadata of the second delegation will override
901-
that of the third one, etc. In order to accommodate prioritized
902-
delegations, the "roles" key in the DELEGATIONS object above points to an array
903-
of delegated roles, rather than to a hash table.
904896

905-
The metadata files for delegated target roles has the same format as the
897+
NUM_ROLES is the minimum number of delegated targets roles that must be in
898+
agreement about targets hashes and lengths entrusted by the delegation. The
899+
delegated targets roles for a given delegation are listed in its "roles"
900+
field.
901+
902+
ROLENAME is the name of the delegated targets role, e.g. "projects", KEYID
903+
identifies a key that is authorized to sign for that role, and THRESHOLD
904+
defines how many keys must sign for that role.
905+
906+
Prioritization exists both for delegations and delegated targets roles. That
907+
is, if delegations handle overlapping targets paths, clients MUST consider
908+
them in the order of their appearance in the "delegations" field. The
909+
first delegation is trusted over the second one, the second delegation is
910+
trusted over the third one, and so on. Likewise, in a multi-role delegation,
911+
if NUM_ROLES is less than or equal to half the number of roles in the
912+
"roles" field, different groups of roles may have different agreements
913+
on targets hashes or lengths. Such conflicts must be
914+
resolved by priorizing the first role in the list, that specifies target
915+
metadata agreed to by at least NUM_ROLES.
916+
917+
918+
The metadata files for delegated targets roles has the same format as the
906919
top-level targets.json metadata file.
907920

908921
A targets.json example file:
@@ -918,29 +931,34 @@ repo](https://github.com/theupdateframework/specification/issues).
918931
"signed": {
919932
"_type": "targets",
920933
"spec_version": "1.0.0",
921-
"delegations": {
922-
"keys": {
923-
"f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
924-
"keytype": "ed25519",
925-
"scheme": "ed25519",
926-
"keyval": {
927-
"public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
928-
}
929-
}
930-
},
931-
"roles": [
932-
{
933-
"keyids": [
934-
"f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
935-
],
936-
"name": "project",
937-
"paths": [
938-
"project/file3.txt"
939-
],
940-
"threshold": 1
934+
"keys": {
935+
"f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
936+
"keytype": "ed25519",
937+
"scheme": "ed25519",
938+
"keyval": {
939+
"public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
941940
}
942-
]
941+
}
943942
},
943+
"delegations": [
944+
{
945+
"name": "project-delegation",
946+
"paths": [
947+
"project/file3.txt"
948+
],
949+
"terminating": true,
950+
"min_roles_in_agreement" : 1,
951+
"roles": [
952+
{
953+
"name": "project",
954+
"keyids": [
955+
"f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
956+
],
957+
"threshold": 1
958+
}
959+
]
960+
}
961+
],
944962
"expires": "2030-01-01T00:00:00Z",
945963
"targets": {
946964
"file1.txt": {
@@ -1247,9 +1265,9 @@ non-volatile storage as FILENAME.EXT.
12471265
of appearance.
12481266

12491267
* **4.4.2.1**. If the current delegation is a multi-role delegation,
1250-
recursively visit each role, and check that each has signed exactly the
1251-
same non-custom metadata (i.e., length and hashes) about the target (or
1252-
the lack of any such metadata).
1268+
recursively visit each role, and check that a defined minimum number of
1269+
roles agrees about non-custom metadata, i.e. length and hashes of the
1270+
target (or the lack of any such metadata).
12531271

12541272
* **4.4.2.2**. If the current delegation is a terminating delegation,
12551273
then jump to step 5.

0 commit comments

Comments
 (0)