From 42b51dc3bab47ff016949ad5b87deacf86831e89 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Mon, 7 Aug 2023 09:01:45 -0400 Subject: [PATCH] editorial: state `predicateType` explicitly (#935) In the top of the Provenance and VSA specification pages, explicitly state the `predicateType` and instruct the reader to use this string rather than the URL. Also move the link to in-toto and the RFC 2119 blurb (if present) up there as well. Motivation: 1. Remove ambiguity, particularly around trailing slashes. 2. Open the path to move provenance and VSA underneath the spec directory, so that everything is versioned together. If that happens, we'll redirect the `predicateType` URI to the latest minor version. Signed-off-by: Mark Lodato --- docs/provenance/v0.1.md | 13 +++++++++++++ docs/provenance/v0.2.md | 17 +++++++++++----- docs/provenance/v1-rc1.md | 30 +++++++++++++++-------------- docs/provenance/v1-rc2.md | 30 +++++++++++++++-------------- docs/provenance/v1.md | 30 +++++++++++++++-------------- docs/verification_summary/v0.1.md | 17 +++++++++++----- docs/verification_summary/v0.2.md | 17 +++++++++++----- docs/verification_summary/v1-rc2.md | 17 +++++++++++----- docs/verification_summary/v1.md | 17 +++++++++++----- 9 files changed, 121 insertions(+), 67 deletions(-) diff --git a/docs/provenance/v0.1.md b/docs/provenance/v0.1.md index 375310d7d..93fb11d2f 100644 --- a/docs/provenance/v0.1.md +++ b/docs/provenance/v0.1.md @@ -11,6 +11,18 @@ something was produced. For higher SLSA levels and more resilient integrity guarantees, provenance requirements are stricter and need a deeper, more technical understanding of the predicate. +This document defines the following predicate type within the [in-toto +attestation] framework: + +```json +"predicateType": "https://slsa.dev/provenance/v0.1" +``` + +> Important: Always use the above string for `predicateType` rather than what is +> in the URL bar. The `predicateType` URI will always resolve to the latest +> minor version of this specification. See [parsing rules](#parsing-rules) for +> more information. + ## Purpose Describe how an artifact or set of artifacts was produced. @@ -488,5 +500,6 @@ Execution of arbitrary commands: [Statement]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#statement [Timestamp]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#Timestamp [TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#TypeURI +[in-toto attestation]: https://github.com/in-toto/attestation [parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#parsing-rules [provenance requirements]: ../spec/v0.1/requirements#provenance-requirements diff --git a/docs/provenance/v0.2.md b/docs/provenance/v0.2.md index b03884cac..b0e6e265f 100644 --- a/docs/provenance/v0.2.md +++ b/docs/provenance/v0.2.md @@ -11,6 +11,18 @@ something was produced. For higher SLSA levels and more resilient integrity guarantees, provenance requirements are stricter and need a deeper, more technical understanding of the predicate. +This document defines the following predicate type within the [in-toto +attestation] framework: + +```json +"predicateType": "https://slsa.dev/provenance/v0.2" +``` + +> Important: Always use the above string for `predicateType` rather than what is +> in the URL bar. The `predicateType` URI will always resolve to the latest +> minor version of this specification. See [parsing rules](#parsing-rules) for +> more information. + ## Purpose Describe how an artifact or set of artifacts was produced. @@ -18,11 +30,6 @@ Describe how an artifact or set of artifacts was produced. This predicate is the recommended way to satisfy the SLSA [provenance requirements]. -## Prerequisite - -Understanding of SLSA [Software Attestations](/attestation-model) -and the larger [in-toto attestation] framework. - ## Model Provenance is an attestation that some entity (`builder`) produced one or more diff --git a/docs/provenance/v1-rc1.md b/docs/provenance/v1-rc1.md index e9887f2b2..e94787824 100644 --- a/docs/provenance/v1-rc1.md +++ b/docs/provenance/v1-rc1.md @@ -3,11 +3,6 @@ title: Provenance description: Description of SLSA provenance specification for verifying where, when, and how something was produced. layout: standard --- - - To trace software back to the source and define the moving parts in a complex supply chain, provenance needs to be there from the very beginning. It's the verifiable information about software artifacts describing where, when and how @@ -15,6 +10,22 @@ something was produced. For higher SLSA levels and more resilient integrity guarantees, provenance requirements are stricter and need a deeper, more technical understanding of the predicate. +This document defines the following predicate type within the [in-toto +attestation] framework: + +```json +"predicateType": "https://slsa.dev/provenance/v1-rc1" +``` + +> Important: Always use the above string for `predicateType` rather than what is +> in the URL bar. The `predicateType` URI will always resolve to the latest +> minor version of this specification. See [parsing rules](#parsing-rules) for +> more information. + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + ## Purpose Describe how an artifact or set of artifacts was produced so that: @@ -26,15 +37,6 @@ Describe how an artifact or set of artifacts was produced so that: This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance requirements](/spec/v1.0-rc1/requirements#provenance-generation). -## Prerequisite - -Understanding of SLSA [Software Attestations](/attestation-model) -and the larger [in-toto attestation] framework. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - ## Model Provenance is an attestation that the `builder` produced the `subject` software diff --git a/docs/provenance/v1-rc2.md b/docs/provenance/v1-rc2.md index f3eed6507..9ebeb1828 100644 --- a/docs/provenance/v1-rc2.md +++ b/docs/provenance/v1-rc2.md @@ -3,11 +3,6 @@ title: Provenance description: Description of SLSA provenance specification for verifying where, when, and how something was produced. layout: standard --- - - To trace software back to the source and define the moving parts in a complex supply chain, provenance needs to be there from the very beginning. It's the verifiable information about software artifacts describing where, when and how @@ -15,6 +10,22 @@ something was produced. For higher SLSA levels and more resilient integrity guarantees, provenance requirements are stricter and need a deeper, more technical understanding of the predicate. +This document defines the following predicate type within the [in-toto +attestation] framework: + +```json +"predicateType": "https://slsa.dev/provenance/v1-rc2" +``` + +> Important: Always use the above string for `predicateType` rather than what is +> in the URL bar. The `predicateType` URI will always resolve to the latest +> minor version of this specification. See [parsing rules](#parsing-rules) for +> more information. + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + ## Purpose Describe how an artifact or set of artifacts was produced so that: @@ -26,15 +37,6 @@ Describe how an artifact or set of artifacts was produced so that: This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance requirements](/spec/v1.0-rc2/requirements#provenance-generation). -## Prerequisite - -Understanding of SLSA [Software Attestations](/attestation-model) -and the larger [in-toto attestation] framework. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - ## Model Provenance is an attestation that a particular build platform produced a set of diff --git a/docs/provenance/v1.md b/docs/provenance/v1.md index af8b1c6b9..67a156e4f 100644 --- a/docs/provenance/v1.md +++ b/docs/provenance/v1.md @@ -3,11 +3,6 @@ title: Provenance description: Description of SLSA provenance specification for verifying where, when, and how something was produced. layout: standard --- - - To trace software back to the source and define the moving parts in a complex supply chain, provenance needs to be there from the very beginning. It's the verifiable information about software artifacts describing where, when and how @@ -15,6 +10,22 @@ something was produced. For higher SLSA levels and more resilient integrity guarantees, provenance requirements are stricter and need a deeper, more technical understanding of the predicate. +This document defines the following predicate type within the [in-toto +attestation] framework: + +```json +"predicateType": "https://slsa.dev/provenance/v1" +``` + +> Important: Always use the above string for `predicateType` rather than what is +> in the URL bar. The `predicateType` URI will always resolve to the latest +> minor version of this specification. See [parsing rules](#parsing-rules) for +> more information. + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + ## Purpose Describe how an artifact or set of artifacts was produced so that: @@ -26,15 +37,6 @@ Describe how an artifact or set of artifacts was produced so that: This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance requirements](/spec/v1.0/requirements#provenance-generation). -## Prerequisite - -Understanding of SLSA [Software Attestations](/attestation-model) -and the larger [in-toto attestation] framework. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - ## Model Provenance is an attestation that a particular build platform produced a set of diff --git a/docs/verification_summary/v0.1.md b/docs/verification_summary/v0.1.md index 45686b07e..7f26d67c5 100644 --- a/docs/verification_summary/v0.1.md +++ b/docs/verification_summary/v0.1.md @@ -7,6 +7,18 @@ layout: standard Verification summary attestations communicate that an artifact has been verified at a specific SLSA level and details about that verification. +This document defines the following predicate type within the [in-toto +attestation] framework: + +```json +"predicateType": "https://slsa.dev/verification_summary/v0.1" +``` + +> Important: Always use the above string for `predicateType` rather than what is +> in the URL bar. The `predicateType` URI will always resolve to the latest +> minor version of this specification. See [parsing rules](#parsing-rules) for +> more information. + ## Purpose Describe what SLSA level an artifact or set of artifacts was verified at @@ -25,11 +37,6 @@ This might be necessary for legal reasons (keeping a software supplier confidential) or for security reasons (not revealing that an embargoed patch has been included). -## Prerequisite - -Understanding of SLSA [Software Attestations](/attestation-model), -[SLSA Provenance](/provenance), and the larger [in-toto attestation] framework. - ## Model A Verification Summary Attestation (VSA) is an attestation that some entity diff --git a/docs/verification_summary/v0.2.md b/docs/verification_summary/v0.2.md index 92e3af641..dd95a7f86 100644 --- a/docs/verification_summary/v0.2.md +++ b/docs/verification_summary/v0.2.md @@ -7,6 +7,18 @@ layout: standard Verification summary attestations communicate that an artifact has been verified at a specific SLSA level and details about that verification. +This document defines the following predicate type within the [in-toto +attestation] framework: + +```json +"predicateType": "https://slsa.dev/verification_summary/v0.2" +``` + +> Important: Always use the above string for `predicateType` rather than what is +> in the URL bar. The `predicateType` URI will always resolve to the latest +> minor version of this specification. See [parsing rules](#parsing-rules) for +> more information. + ## Purpose Describe what SLSA level an artifact or set of artifacts was verified at @@ -25,11 +37,6 @@ This might be necessary for legal reasons (keeping a software supplier confidential) or for security reasons (not revealing that an embargoed patch has been included). -## Prerequisite - -Understanding of SLSA [Software Attestations](/attestation-model), -[SLSA Provenance](/provenance), and the larger [in-toto attestation] framework. - ## Model A Verification Summary Attestation (VSA) is an attestation that some entity diff --git a/docs/verification_summary/v1-rc2.md b/docs/verification_summary/v1-rc2.md index ad8c092ab..a1ae3a510 100644 --- a/docs/verification_summary/v1-rc2.md +++ b/docs/verification_summary/v1-rc2.md @@ -7,6 +7,18 @@ layout: standard Verification summary attestations communicate that an artifact has been verified at a specific SLSA level and details about that verification. +This document defines the following predicate type within the [in-toto +attestation] framework: + +```json +"predicateType": "https://slsa.dev/verification_summary/v1-rc2" +``` + +> Important: Always use the above string for `predicateType` rather than what is +> in the URL bar. The `predicateType` URI will always resolve to the latest +> minor version of this specification. See [parsing rules](#parsing-rules) for +> more information. + ## Purpose Describe what SLSA level an artifact or set of artifacts was verified at @@ -25,11 +37,6 @@ This might be necessary for legal reasons (keeping a software supplier confidential) or for security reasons (not revealing that an embargoed patch has been included). -## Prerequisite - -Understanding of SLSA [Software Attestations](/attestation-model), -[SLSA Provenance], and the larger [in-toto attestation] framework. - ## Model A Verification Summary Attestation (VSA) is an attestation that some entity diff --git a/docs/verification_summary/v1.md b/docs/verification_summary/v1.md index 820013851..f09b7f85d 100644 --- a/docs/verification_summary/v1.md +++ b/docs/verification_summary/v1.md @@ -7,6 +7,18 @@ layout: standard Verification summary attestations communicate that an artifact has been verified at a specific SLSA level and details about that verification. +This document defines the following predicate type within the [in-toto +attestation] framework: + +```json +"predicateType": "https://slsa.dev/verification_summary/v1" +``` + +> Important: Always use the above string for `predicateType` rather than what is +> in the URL bar. The `predicateType` URI will always resolve to the latest +> minor version of this specification. See [parsing rules](#parsing-rules) for +> more information. + ## Purpose Describe what SLSA level an artifact or set of artifacts was verified at @@ -25,11 +37,6 @@ This might be necessary for legal reasons (keeping a software supplier confidential) or for security reasons (not revealing that an embargoed patch has been included). -## Prerequisite - -Understanding of SLSA [Software Attestations](/attestation-model), -[SLSA Provenance], and the larger [in-toto attestation] framework. - ## Model A Verification Summary Attestation (VSA) is an attestation that some entity