Merge pull request #57 from lukpueh/adopt-tap3-metadata

lukpueh · web-flow · commit 4bae5d868e25 · 2020-05-27T17:05:45.000+02:00
Adopt TAP 3 multi-role delegations metadata format
diff --git a/tuf-spec.md b/tuf-spec.md
@@ -793,7 +793,10 @@ repo](https://github.com/theupdateframework/specification/issues).
          "version" : VERSION,
          "expires" : EXPIRES,
          "targets" : TARGETS,
-         ("delegations" : DELEGATIONS)
+         ("keys" : {
+             KEYID : KEY,
+             ... },
+         "delegations" : [ DELEGATION, ... ])
        }
 
    TARGETS is an object whose format is the following:
@@ -828,27 +831,26 @@ 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" 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,
+          "roles": [{
+            "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.
@@ -891,18 +893,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 "roles"
+   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 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.
+
+
+   The metadata files for delegated targets roles has the same format as the
    top-level targets.json metadata file.
 
    A targets.json example file:
@@ -918,29 +931,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": {
+         "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": {
@@ -1247,9 +1265,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 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.
