diff --git a/docs/verification_summary/v1.md b/docs/verification_summary/v1.md index bdbd16497..a03bb7322 100644 --- a/docs/verification_summary/v1.md +++ b/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,7 +135,7 @@ of the other top-level fields, such as `subject`, see [Statement]._ > URI indicating the verifier’s identity. -`timeVerified` _string ([Timestamp]), required_ +`timeVerified` _string ([Timestamp]), optional_ > Timestamp indicating what time the verification occurred. @@ -140,13 +143,17 @@ of the other top-level fields, such as `subject`, see [Statement]._ `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`. -`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. `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. -`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.