Introduce setting and verifying expectations (slsa-framework#571)

Introduce to the specification the so far implicit notion that artefacts 
are automatically verified against a set of expectations (constraints)
before use.

Updates the terminology page to discuss a verification model which
includes certification of systems, expectations, and automatic
verification of artifacts.

Begins to describe requirements for automatic verification of a
package's provenance against known expectations.

Signed-off-by: Joshua Lock <[email protected]>

requirements.md

@@ -63,11 +63,15 @@ Responsibility to implement SLSA is spread across the following parties.
   <td><a href="#ephemeral-isolated">Ephemeral and isolated</a>
   <td> <td> <td>✓
 <tr>
-  <td rowspan=2><a href="#package-ecosystem">Package ecosystem</a>
+  <td rowspan=3><a href="#package-ecosystem">Package ecosystem</a>
   <td colspan=2>Provenance distribution
   <td>✓<td>✓<td>✓
 <tr>
-  <td colspan=2>Expectations and verification
+  <td colspan=2><a href="#setting-expectations">Setting expectations</a>
+  <td>✓<td>✓<td>✓
+<tr>
+  <td colspan=2><a href="#verifying-expectations-for-artifacts">
+    Verifying expectations for artifacts</a>
   <td>✓<td>✓<td>✓
 <tr>
   <td rowspan=1><a href="#consumer">Consumer</a>
@@ -425,15 +429,113 @@ consumers. For the build system, this usually means outputting the provenance as
 part of the build to allow the release process to upload it in a manner
 prescribed by the package ecosystem.
 
+### Setting Expectations
+
+<dfn>Expectations</dfn> define the allowed values for
+[`buildType`](/provenance/v1/#buildType) and
+[`externalParameters`](/provenance/v1/#externalParameters)
+for a given package (assuming the SLSA provenance format) in order to address
+the [build integrity threats](threats#build-integrity-threats).
+> **TODO:** link to more concrete guidance once it's available.
+
+It is important to note that expectations are tied to a *package name*, whereas
+provenance is tied to an *artifact*. Package ecosystem's using the
+[RECOMMENDED suite](/attestation-model#recommended-suite) of attestation
+formats SHOULD list the package name in the provenance attestation statement's
+`subject` field, though the precise semantics for binding a package name to an
+artifact are defined by the package ecosystem.
+
+<table>
+<tr><th>Requirement<th>Description<th>L1<th>L2<th>L3
+
+<tr id="expectations-known">
+<td>Expectations known
+<td>
+
+The package ecosystem MUST ensure that expectations are defined for the package before it is made available to package ecosystem users.
+
+There are several approaches a package ecosystem could take to setting expectations, for example:
+
+-   Requiring the producer to set expectations when registering a new package
+    in the package ecosystem.
+-   Using the values from the package's provenance during its initial
+    publication (trust on first use).
+
+<td>✓<td>✓<td>✓
+<tr id="expectations-changes-auth">
+<td>Changes authorized
+<td>
+
+The package ecosystem MUST ensure that any changes to expectations are
+authorized by the package's producer. This is to prevent a malicious actor
+from updating the expectations to allow building and publishing from a fork
+under the actor's control. Some ways this could be achieved include:
+
+-   Requiring two authorized individuals from the package producer to approve
+    the change.
+-   Requiring consumers to approve changes, in a similar fashion to how SSH
+    host fingerprint changes have to be approved by users.
+-   Disallowing changes altogether, for example by binding the package name to
+    the source repository.
+
+<td><td>✓<td>✓
+</table>
+
+### Verifying expectations for artifacts
+
+It is a critical responsibility of the package ecosystem to verify that the
+provenance for a package matches the expectations defined for that package.
+
+A package version is considered to meet a given SLSA level if and only if the
+package ecosystem has verified its provenance against the package's
+expectations. If expectations are defined for a package but no provenance
+exists for the artifact, this MUST result in verification failure.
+Conversely, if multiple provenance attestations exist, the system SHOULD accept
+any combination that satisifes expectations.
+
+Verifying expectations could happen in multiple places within a package
+ecosystem, for example by using one or more of the following approaches:
+
+-   During package upload, the registry ensures that the package's provenance
+    matches any known expectations for that package before accepting it into
+    the registry.
+-   During client-side installation/deployment of a package, the package
+    ecosystem client ensures that the package's provenance matches the
+    any known expectations for that package before use.
+-   Package ecosystem participants and/or the ecosystem operators perform
+    continuous monitoring of packages to detect any changes to packages which
+    do not match the known expectations. **TODO:** do we need to
+    emphasize that the value of monitoring without enforcement is lower?
+
+All package ecosystem verifiers will require a mapping from builder identity to
+the SLSA level the builder is trusted to meet. How this map is defined,
+distributed, and updated is package ecosystem specific.
+> **TODO:** expand on this map model. Provide examples for ecosystems to follow,
+perhaps in the use-cases, and link to certification.
+
+Verification MUST include the following steps:
+
+-   Ensuring that the builder identity is one of those in the map of trusted
+    builder id's to SLSA level.
+-   [Verification of the provenance](/provenance/v1/#verification) metadata.
+-   Ensuring that the values for `BuildType` and `ExternalParameters` in the
+    provenance match the known expectations. The package ecosystem MAY allow
+    an approved list of `ExternalParameters` to be ignored during verification.
+    Any unrecognized `ExternalParameters` SHOULD cause verification to fail.
+
+NOTE: The term *package ecosystem* MAY be interpreted loosely. For example, one
+could implement a system which is external to the canonical package ecosystem
+and perform SLSA verification for that package ecosystem's contents. This
+combination can be considered a package ecosystem for the purposes of setting
+and verifying expectations.
+
 **TODO:** Update the requirements to provide guidelines for how to implement,
 showing what the options are:
 
--   How to define expectations: explicit vs implicit
+-   Create a more concrete guide on how to do expectations
 -   Whether provenance is generated during the initial build and/or
     after-the-fact using reproducible builds
 -   How provenance is distributed
--   When verification happens: during upload, during download, and/or continuous
-    monitoring
 -   What happens on failure: blocking, warning, and/or asynchronous notification
 
 ## Consumer

terminology.md

@@ -27,6 +27,8 @@ supply chains plus its own sources and builds.
 
 [directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph
 
+**TODO:** update supply chain model to include verification.
+
 ![Software Supply Chain Model](../../images/supply-chain-model.svg)
 
 | Term | Description | Example |
@@ -47,8 +49,9 @@ the steps to execute. In response to an external trigger, the platform runs the
 build by initializing the environment, fetching the source and possibly some
 dependencies, and then starting execution inside the environment. The build then
 performs arbitrary steps, possibly fetching additional dependencies, and outputs
-one or more artifacts.
+one or more artifacts along with provenance metadata for those artifacts.
 
+> **TODO:** move build model into spec versioned folder?
 <p align="center"><img src="../../images/build-model.svg" alt="Model Build"></p>
 
 | Term | Description
@@ -113,3 +116,48 @@ workstation, though this does not meet SLSA 2+.
 | Admin        | developer
 
 </details>
+
+[verification]: #verification-model
+
+### Verification model
+
+Verification in SLSA is performed in two ways. Firstly, the build system is
+certified to ensure conformance with the requirements at the level claimed by
+the build system. This certification should happen on a recurring cadence with
+the outcomes published by the platform operator for their users to review and
+make informed decisions about which builders to trust.
+
+Secondly, artifacts are verified to ensure they meet the producer defined
+expectations of where the package source code was retrieved from and on what
+build system the package was built.
+
+![Verification Model](verification-model.svg)
+
+| Term         | Description |
+|--------------|---- |
+| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly. |
+| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. |
+| Build system certification | [Build systems are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level. |
+
+The examples below suggest some ways that expectations and verification may be
+implemented for different, broadly defined, package ecosystems.
+
+<details><summary>Example: Small software team</summary>
+
+| Term | Example |
+| ---- | ------- |
+| Expectations | Defined by the producer's security personnel and stored in a database. |
+| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. |
+| Build system certification | The build system implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements. |
+
+</details>
+
+<details><summary>Example: Open source language distribution</summary>
+
+| Term | Example |
+| ---- | ------- |
+| Expectations | Defined separately for each package and stored in the package registry. |
+| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. |
+| Build system certification | Performed by the language ecosystem packaging authority. |
+
+</details>