diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index 5c3860bdc..cfec1b15a 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -45,54 +45,6 @@ environment, and the compute platform they used. > We may consider the addition of an L4 to the Build Environment track, which > covers hardware-attested runtime integrity checking during a build. -### Build environment model - -

Model Build Environment

- -The Build Environment track expands upon the [build model] by explicitily -separating the *build image* and *compute platform* from the abstract build -environment and build platform. - -A typical build environment will go through the following lifecycle: - -1. *Build image creation*: A build image producer creates different build - images through a dedicated build process. For the SLSA Environment track, - the build image producer outputs provenance describing this process. -2. *Build environment instantiation*: The hosted build platform calls - into the *host interface* to create a new instance of a build environment - from a given build image. The *build agent* begins to wait for an incoming - build dispatch. For the SLSA Environment track, the host interface in the - compute platform attests to the integrity of the environment's *initial - state* during its boot process. -3. *Build dispatch*: When the tenant dispatches a new build, the hosted - build platform assigns the build to a created build environment. - For the SLSA Environment track, the build platform - attests to the binding between a build environment and *build ID*. -4. *Build execution*: Finally, the *build executor* running within the - environment executes the tenant's build definition. - -### Definitions - -The Build Environment track specifies the following supply chain components -and roles: - -| Primary Term | Description -| --- | --- -| Build ID | An immutable identifier assigned uniquely to a specific execution of a tenant's build. In practice, the build ID may be a cryptographic key or other unique and immutable identfier (e.g., a UUID) associated with the build execution. -| Build image | The template for a build environment, such as a VM or container image. Individual components of a build image include the root filesystem, pre-installed guest OS and packages, the build executor, and the build agent. -| Build image producer | The party that creates and distributes build images. In practice, the build image producer may be the hosted build platform or a third party in a bring-your-own (BYO) build image setting. -| Build executor | A platform-provided program dedicated to executing the tenant’s build definition, i.e., running the build, within the build environment. The build executor must be included in the build image's measurement. -| Build agent | A program that interacts with the hosted build platform's control plane from within a running build environment. The build agent must be included in the build image's measurement. -| Build dispatch | The process of assigning a tenant's build to a pre-deployed build environment on a hosted build platform. -| Compute platform | The compute system and infrastructure underlying a build platform, i.e., the host system (hypervisor and/or OS) and hardware. In practice, the compute platform and the build platform may be managed by the same or distinct organizations. -| Host interface | The component in the compute platform that the hosted build platform uses to request resources for deploying new build environments, i.e., the VMM/hypervisor or container orchestrator. -| Boot process | In the context of builds, the process of loading and executing the layers of firmware and/or software needed to start up a build environment on the host compute platform. -| Measurement | The cryptographic hash of some component or system state in the build environment, including software binaries, configuration, or initialized run-time data. -| Quote | (Virtual) hardware-signed data that contains one or more (virtual) hardware-generated measurements. Quotes may additionally include nonces for replay protection, firmware information, or other platform metadata. -| Reference value | A specific measurement used as the good known value for a given build environment component or state. - -TODO: Disambiguate similar terms (e.g., image, build job, build runner) - ### Build environment threats TODO @@ -345,8 +297,7 @@ TODO [Secure Boot]: https://wiki.debian.org/SecureBoot#What_is_UEFI_Secure_Boot.3F [TPM]: https://trustedcomputinggroup.org/resource/tpm-library-specification/ [VSA]: verification_summary.md -[build image]: #definitions -[build model]: terminology.md#build-model +[build image]: terminology.md#build-environment-model [confidential computing]: https://confidentialcomputing.io/wp-content/uploads/sites/10/2023/03/Common-Terminology-for-Confidential-Computing.pdf [hosted]: requirements.md#isolation-strength [several classes]: #build-environment-threats diff --git a/docs/spec/draft/terminology.md b/docs/spec/draft/terminology.md index aed23abea..c2ba58e2b 100644 --- a/docs/spec/draft/terminology.md +++ b/docs/spec/draft/terminology.md @@ -127,6 +127,51 @@ of build types](/provenance/v1#index-of-build-types). +### Build environment model + +**TODO:** Add figure + +The Build Environment (BuildEnv) track expands upon the [build model](#build-model) +by explicitily separating the *build image* and *compute platform* from the abstract +build environment and build platform. + +A typical build environment will go through the following lifecycle: + +1. *Build image creation*: A build image producer creates different build + images through a dedicated build process. For the SLSA BuildEnv track, + the build image producer outputs provenance describing this process. +2. *Build environment instantiation*: The hosted build platform calls + into the *host interface* to create a new instance of a build environment + from a given build image. The *build agent* begins to wait for an incoming + build dispatch. For the SLSA BuildEnv track, the host interface in the + compute platform attests to the integrity of the environment's *initial + state* during its boot process. +3. *Build dispatch*: When the tenant dispatches a new build, the hosted + build platform assigns the build to a created build environment. + For the SLSA BuildEnv track, the build platform + attests to the binding between a build environment and *build ID*. +4. *Build execution*: Finally, the *build executor* running within the + environment executes the tenant's build definition. + +The BuildEnv track uses the following roles, components, and concepts: + +| Primary Term | Description +| --- | --- +| Build ID | An immutable identifier assigned uniquely to a specific execution of a tenant's build. In practice, the build ID may be an identifier, such as a UUID, associated with the build execution. +| Build image | The template for a build environment, such as a VM or container image. Individual components of a build image include the root filesystem, pre-installed guest OS and packages, the build executor, and the build agent. +| Build image producer | The party that creates and distributes build images. In practice, the build image producer may be the hosted build platform or a third party in a bring-your-own (BYO) build image setting. +| Build executor | A platform-provided program dedicated to executing the tenant’s build definition, i.e., running the build, within the build environment. The build executor must be included in the build image's measurement. +| Build agent | A program that interacts with the hosted build platform's control plane from within a running build environment. The build agent must be included in the build image's measurement. +| Build dispatch | The process of assigning a tenant's build to a pre-deployed build environment on a hosted build platform. +| Compute platform | The compute system and infrastructure underlying a build platform, i.e., the host system (hypervisor and/or OS) and hardware. In practice, the compute platform and the build platform may be managed by the same or distinct organizations. +| Host interface | The component in the compute platform that the hosted build platform uses to request resources for deploying new build environments, i.e., the VMM/hypervisor or container orchestrator. +| Boot process | In the context of builds, the process of loading and executing the layers of firmware and/or software needed to start up a build environment on the host compute platform. +| Measurement | The cryptographic hash of some component or system state in the build environment, including software binaries, configuration, or initialized run-time data. +| Quote | (Virtual) hardware-signed data that contains one or more (virtual) hardware-generated measurements. Quotes may additionally include nonces for replay protection, firmware information, or other platform metadata. +| Reference value | A specific measurement used as the good known value for a given build environment component or state. + +**TODO:** Disambiguate similar terms (e.g., image, build job, build runner) + ### Package model Software is distributed in identifiable units called packages