Update VSA for SLSA v1.1

Signed-off-by: kpk47 <[email protected]>

docs/verification_summary/v1.md

@@ -34,11 +34,14 @@ Understanding of SLSA [Software Attestations](/attestation-model),
 
 A Verification Summary Attestation (VSA) is an attestation that some entity
 (`verifier`) verified one or more software artifacts (the `subject` of an
-in-toto attestation [Statement]) by evaluating the artifact and a `bundle`
-of attestations against some `policy`.  Users who trust the `verifier` may
-assume that the artifacts met the indicated SLSA level without themselves
-needing to evaluate the artifact or to have access to the attestations the
-`verifier` used to make its determination.
+in-toto attestation [Statement]) by evaluating the artifact and an
+attestation against some `policy`.  Specifically, a VSA is a claim by
+`verifier` that `subject` passed the policy for `resourceUri`. Users who trust
+the `verifier` may assume that the artifacts identified by the
+`(subject, resourceUri)` pair met the indicated SLSA level without
+themselves needing to evaluate the artifact or to have access to the
+attestations the `verifier` used to make its determination.
+
 
 The VSA also allows consumers to determine the verified levels of
 all of an artifact’s _transitive_ dependencies.  The verifier does this by
@@ -122,7 +125,7 @@ of the other top-level fields, such as `subject`, see [Statement]._
 > can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot
 > sign for the "Google Cloud Deploy" verifier.
 >
-> The field is required, even if it is implicit from the signer, to aid readability and
+> This field is required, even if it is implicit from the signer, to aid readability and
 > debugging. It is an object to allow additional fields in the future, in case one
 > URI is not sufficient.
 
@@ -132,21 +135,25 @@ of the other top-level fields, such as `subject`, see [Statement]._
 > URI indicating the verifier’s identity.
 
 <a id="timeVerified"></a>
-`timeVerified` _string ([Timestamp]), required_
+`timeVerified` _string ([Timestamp]), optional_
 
 > Timestamp indicating what time the verification occurred.
 
 <a id="resourceUri"></a>
 `resourceUri` _string ([ResourceURI]), required_
 
 > URI that identifies the resource associated with the artifact being verified.
+>
+> This field is required to prevent confusion attacks. E.g., a VSA indicating
+> that a package can be published as `foo` should not be useable to publish
+> the package as `bar`.
 
 <a id="policy"></a>
-`policy` _object ([ResourceDescriptor]), required_
+`policy` _object ([ResourceDescriptor]), optional_
 
 > Describes the policy that the `subject` was verified against.
 >
-> The entry MUST contain a `uri`.
+> This field is RECOMMENDED.
 
 <a id="inputAttestations"></a>
 `inputAttestations` _array ([ResourceDescriptor]), optional_
@@ -167,7 +174,7 @@ of the other top-level fields, such as `subject`, see [Statement]._
 > Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification.
 
 <a id="verifiedLevels"></a>
-`verifiedLevels` _array ([SlsaResult]), required_
+`verifiedLevels` _array ([SlsaResult]), optional_
 
 > Indicates the highest level of each track verified for the artifact (and not
 > its dependencies), or "FAILED" if policy verification failed.
@@ -240,6 +247,23 @@ WARNING: This is just for demonstration purposes.
 
 <div id="slsaresult">
 
+## How to Verify
+
+Verification SHOULD include the following steps
+1. Verify the signature on the VSA envelope using the preconfigured roots of trust.
+2. Verify the statemet's `subject` matches the digest of the artifact in question.
+3. Verify that the `predicateType` is `https://slsa.dev/verification_summary/v1`.
+4. Verify  the `verifier` matches the public key (or equivalent) used to verify the signature in step 1.
+5. Verify that the value for `resourceUri` in the VSA matches the expected value.
+
+Resulting threat mitigation: See
+[Verifying artifacts](/spec/v1.0/verifying-artifacts) for details about which
+threats are addressed by verifying each SLSA level.
+
+IMPORTANT: A VSA does not protect against compromise of the verifier, such as by
+a malicious insider. Instead, VSA users SHOULD carefully consider which
+verifiers they add to their roots of trust.
+
 ## _SlsaResult (String)_
 
 </div>