editorial: draft: Improve instructions to verify source VSAs (#1498)

The prior instructions weren't complete and were somewhat spread out.
Tried to consolidate in one spot. Also fixed a typo in the general
verification summary docs that incorrectly referenced slsaResult instead
of verificationResult.

fixes #1445

---------

Signed-off-by: Tom Hennen <tomhennen@google.com>

Author: TomHennen

docs/spec/draft/source-requirements.md

@@ -590,10 +590,8 @@ Example implementations:
 
 #### How to verify
 
--   VSAs for source revisions MUST follow [the standard method of VSA verification](./verification_summary.md#how-to-verify).
--   Users SHOULD check that an allowed branch is listed in `subject.annotations.sourceRefs` to ensure the revision is from an appropriate context within the repository.
--   Users SHOULD check that the expected `SLSA_SOURCE_LEVEL_` is listed within `verifiedLevels`.
--   Users MUST ignore any unrecognized values in `verifiedLevels`.
+See [Verifying Source](./verifying-source.md) for instructions how to verify
+VSAs for Source Revisions.
 
 ### Source provenance attestations
 

docs/spec/draft/verification_summary.md

@@ -299,8 +299,8 @@ Verification MUST include the following steps:
     value. This step ensures that the consumer is using the VSA for the
     producer's intended purpose.
 
-6.  Verify that the value for `slsaResult` is `PASSED`. This step ensures the
-    artifact is suitable for the consumer's purposes.
+6.  Verify that the value for `verificationResult` is `PASSED`. This step
+    ensures the artifact is suitable for the consumer's purposes.
 
 7.  Verify that `verifiedLevels` contains the expected value. This step ensures
     that the artifact is suitable for the consumer's purposes.

docs/spec/draft/verifying-source.md

@@ -25,7 +25,7 @@ recording the result of prior verifications. Source VSAs may be issued by a VSA
 provider to make a SLSA source level determination based on the content of those
 attestations.
 
-## How to verify SLSA a source revision
+## How to verify a source revision
 
 The source consumer checks:
 
@@ -88,17 +88,10 @@ Once, when bootstrapping the verifier:
 
     </details>
 
-Given a revision and its VSA:
-
-1.  [Verify][validation-model] the envelope's signature using the roots of
-    trust, resulting in a list of recognized public keys (or equivalent).
-2.  [Verify][validation-model] that statement's `subject` matches the digest of
-    the revision in question.
-3.  Verify that the `predicateType` is `https://slsa.dev/verification_summary/v1`.
-4.  Look up the SLSA Source Level in the roots of trust, using the recognized
-    public keys and the `verifier.id`, defaulting to SLSA Source L1.
-
-[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model
+Given a revision and its VSA follow the
+[VSA verification instructions](./verification_summary.md#how-to-verify) and the
+[validation-model] using the revision identifier to perform subject matching and
+checking the `verifier.id` against the root-of-trust described above.
 
 ### Step 2: Check Expectations
 
@@ -117,12 +110,15 @@ fields:
 
 | What | Why
 | ---- | ---
-| Verifier (SCS) identity from [Step 1] | To prevent an adversary from substituting a VSA making false claims from an unintended SCS.
+| `verifier.id` identity from [Step 1] | To prevent an adversary from substituting a VSA making false claims from an unintended SCS.
+| `subject.digest` from [Step 1] | To prevent an adversary from substituting a VSA from another revision.
+| `verificationResult` | To prevent an adversary from providing a VSA for a revision that failed some aspect of the organization's expectations.
 | `predicate.resourceUri` | To prevent an adversary from substituting a VSA for the intended repository (e.g. `git+https://github.com/IntendedOrg/hello-world`) for another (e.g. `git+https://github.com/AdversaryOrg/hello-world`)
 | `subject.annotations.sourceRefs` | To prevent an adversary from substituting the intended revision from one branch (e.g. `release`) with another (e.g. `experimental_auth`).
 | `verifiedLevels` | To ensure the expected controls were in place for the creation of the revision. E.g. `SLSA_SOURCE_LEVEL_3`, `ORG_SOURCE_STATIC_ANALYSIS`, etc...
 
 [Threat "B"]: threats#b-modifying-the-source
+[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model
 
 ### Step 3: Verify Evidence using Source Provenance [optional]