Use ResourceDescriptor for statement subjects

Update proto definitions, docs/validation etc to reflect this change.

Signed-off-by: Aditya Sirish <[email protected]>

docs/validation.md

@@ -34,17 +34,16 @@ Steps:
     -   `statement` := decode `envelope.payload` as a JSON-encoded
         [Statement]; reject if decoding fails
     -   Reject if `statement.type` != `https://in-toto.io/Statement/v1`
-    -   `artifactNames` := empty set of names
-    -   For each `s` in `statement.subject`:
-        -   For each digest (`alg`, `value`) in `s.digest`:
-            -   If `alg` is in `acceptableDigestAlgorithms`:
-                -   If `hash(alg, artifactToVerify)` == `hexDecode(value)`:
-                    -   Add `s.name` to `artifactNames`
-    -   Reject if `artifactNames` is empty
+    -   `matchedSubjects` := the subset of entries `s` in `statement.subject`
+        where:
+        -   there exists at least one `(alg, value)` in `s.digest` where:
+            -   `alg` is in `acceptableDigestAlgorithms` AND
+            -   `hash(alg, artifactToVerify)` == `hexDecode(value)`
+    -   Reject if `matchedSubjects` is empty
 
 Output (to be fed into policy engine):
 
 -   `statement.predicateType`
 -   `statement.predicate`
--   `artifactNames`
+-   `matchedSubjects`
 -   `attesterNames`

protos/in_toto_attestation/v1/statement.proto

@@ -3,6 +3,7 @@ syntax = "proto3";
 package in_toto_attestation.v1;
 
 import "google/protobuf/struct.proto";
+import "in_toto_attestation/v1/resource_descriptor.proto";
 
 
 option go_package = "github.com/in-toto/attestation/go/v1";
@@ -15,12 +16,7 @@ message Statement {
   // Expected to always be "https://in-toto.io/Statement/v1"
   string type = 1 [json_name = "_type"];
 
-  message Subject {
-    string name = 1;
-    map<string, string> digest = 2;
-  }
-
-  repeated Subject subject = 2;
+  repeated in_toto_attestation.v1.ResourceDescriptor subject = 2;
 
   string predicateType = 3;
 

spec/v1/statement.md

@@ -33,37 +33,27 @@ Additional [parsing rules] apply.
 > Identifier for the schema of the Statement. Always
 > `https://in-toto.io/Statement/v1` for this version of the spec.
 
-`subject` _array of objects, required_
+`subject` _array of [ResourceDescriptor] objects, required_
 
 > Set of software artifacts that the attestation applies to. Each element
-> represents a single software artifact.
+> represents a single software artifact. Each element MUST have `digest` set.
+>
+> The `name` field may be used as an identifier to distinguish this artifact
+> from others within the `subject`. Similarly, other ResourceDescriptor fields
+> may be used as required by the context. The semantics are up to the producer
+> and consumer and they MAY use them when evaluating policy. If the name is not
+> meaningful, leave the field unset or use "\_". For example, a
+> [SLSA Provenance] attestation might use the name to specify output filename,
+> expecting the consumer to only consider entries with a particular name.
+> Alternatively, a vulnerability scan attestation might leave name unset because
+> the results apply regardless of what the artifact is named.
+>
+> If set, `name` and `uri` SHOULD be unique within subject.
 >
 > IMPORTANT: Subject artifacts are matched purely by digest, regardless of
 > content type. If this matters to you, please comment on
 > [GitHub Issue #28](https://github.com/in-toto/attestation/issues/28)
 
-`subject[*].digest` _object ([DigestSet]), required_
-
-> Collection of cryptographic digests for the contents of this artifact.
->
-> Two DigestSets are considered matching if ANY of the fields match. The
-> producer and consumer must agree on acceptable algorithms. If there are no
-> overlapping algorithms, the subject is considered not matching.
-
-`subject[*].name` _string, optional_
-
-> Identifier to distinguish this artifact from others within the `subject`.
->
-> The semantics are up to the producer and consumer and they MAY use it when
-> evaluating policy. If the name is not meaningful, leave the field unset or
-> use "\_". For example, a [SLSA Provenance] attestation might use the name
-> to specify output filename, expecting the consumer to only consider
-> entries with a particular name. Alternatively, a vulnerability scan
-> attestation might leave name unset because the results apply regardless of
-> what the artifact is named.
->
-> If set, `name` SHOULD be unique within subject.
-
 `predicateType` _string ([TypeURI]), required_
 
 > URI identifying the type of the [Predicate].
@@ -74,7 +64,7 @@ Additional [parsing rules] apply.
 > set-but-empty. MAY be omitted if `predicateType` fully describes the
 > predicate.
 
-[DigestSet]: digest_set.md
+[ResourceDescriptor]: resource_descriptor.md
 [JSON]: https://www.json.org/json-en.html
 [Predicate]: predicate.md
 [SLSA Provenance]: https://slsa.dev/provenance