diff --git a/docs/docs/architecture/attestation.md b/docs/docs/architecture/attestation.md index 0cf432afe..e3feecc30 100644 --- a/docs/docs/architecture/attestation.md +++ b/docs/docs/architecture/attestation.md @@ -4,10 +4,12 @@ This page explains Constellation's attestation process and highlights the corner ## Terms +(**FS: section should go to the end of page**) The following lists important terms and concepts. ### Trusted Platform Module (TPM) +(**FS: it is probably confusing that we introduce a TPM here as a distinct piece of HW although in the best case, we never actually use a TPM. Maybe a Note window can clear this up.**) A TPM chip is a dedicated tamper-resistant crypto-processor. It can securely store artifacts such as passwords, certificates, encryption keys, or *runtime measurements* (more on this below). When a TPM is implemented in software, it's typically called a *virtual* TPM (vTPM). @@ -35,36 +37,33 @@ By comparing the resulting PCR values against reference values, the integrity of ### Remote attestation (RA) -Remote attestation is the process of verifying certain properties of an application or platform, such as integrity and confidentiality, from a remote location. -In the case of a measured boot, the goal is to obtain a signed attestation statement on the PCR values of the boot measurements. -The statement can then be verified and compared to a set of trusted reference values. -This way, the integrity of the platform can be ensured before sharing secrets with it. +Remote attestation is the process of issuing a cryptographic certificate for certain security-relevant properties of a system or application. Such certificates are also known as attestation statements. They are typically issued by trusted hardware components like a TPM and can be verified by remote entitities. Remote attestation is typically used to bootstrap secure channels to a remote system or application. + +In the case of measured boot, the attestation statement contains the PCR values of the boot process. After verifiying the signature of the attestation statement, the receiving entity typically compares the contained PCR values to expected reference values. This way, the integrity of the platform can be ensured before sharing secrets with it. ### Confidential virtual machine (CVM) -Confidential computing (CC) is the protection of data in-use with hardware-based trusted execution environments (TEEs). +(**FS: good in general, but maybe duplicate with something from "Basics"?**) +Confidential computing is the protection of data in-use with hardware-based trusted execution environments (TEEs). With CVMs, TEEs encapsulate entire virtual machines and isolate them against the hypervisor, other VMs, and direct memory access. After loading the initial VM image into encrypted memory, the hypervisor calls for a secure processor to measure these initial memory pages. -The secure processor locks these pages and generates an attestation report on the initial page measurements. +The secure processor locks these pages and generates an attestation statement on the initial page measurements. CVM memory pages are encrypted with a key that resides inside the secure processor, which makes sure only the guest VM can access them. -The attestation report is signed by the secure processor and can be verified using remote attestation via the certificate authority of the hardware vendor. +The attestation statement is signed by the secure processor and can be verified using remote attestation via the certificate authority of the hardware vendor. Such an attestation statement guarantees the confidentiality and integrity of a CVM. ### Attested TLS (aTLS) -In a CC environment, attested TLS (aTLS) can be used to establish secure connections between two parties using the remote attestation features of the CC components. +We use the term *attested TLS* (aTLS) to describe the concept of using remote attestation-based authentication in a TLS handshake. aTLS modifies the TLS handshake to include attestation statements for TLS certificates. This removes the need for a central certificate authority (CA), as the authenticity of (self-signed) TLS certificates can be verified using attestation statements. -aTLS modifies the TLS handshake by embedding an attestation statement into the TLS certificate. -Instead of relying on a certificate authority, aTLS uses this attestation statement to establish trust in the certificate. - -The protocol can be used by clients to verify a server certificate, by a server to verify a client certificate, or for mutual verification (mutual aTLS). +Like normal TLS, aTLS can be one-way, e.g., only the server verifies the client, or mutual. ## Overview The challenge for Constellation is to lift a CVM's attestation statement to the Kubernetes software layer and make it end-to-end verifiable. From there, Constellation needs to expand the attestation from a single CVM to the entire cluster. -The [*JoinService*](components.md#joinservice) and [*VerificationService*](components.md#verificationservice) are where all runs together. +The [*JoinService*](components.md#joinservice) and [*VerificationService*](components.md#verificationservice) are where all comes together. Internally, the *JoinService* uses remote attestation to securely join CVM nodes to the cluster. Externally, the *VerificationService* provides an attestation statement for the cluster's CVMs and configuration. @@ -72,32 +71,41 @@ The following explains the details of both steps. ## Node attestation -The idea is that Constellation nodes should have verifiable integrity from the CVM hardware measurement up to the Kubernetes software layer. +The idea is that Constellation nodes have verifiable integrity from the CVM hardware measurement up to the Kubernetes software layer. The solution is a verifiable boot chain and an integrity-protected runtime environment. +### Measuring a node + Constellation uses measured boot within CVMs, measuring each component in the boot process before executing it. -Outside of CC, it's usually implemented via TPMs. +Outside of confidential computing, this is usually implemented via TPMs. CVM technologies differ in how they implement runtime measurements, but the general concepts are similar to those of a TPM. -For simplicity, TPM terminology like *PCR* is used in the following. +For simplicity, we use TPM terminology like *PCR* in the following. When a Constellation node image boots inside a CVM, it uses measured boot for all stages and components of the boot chain. -This process goes up to the root filesystem. -The root filesystem is mounted read-only with integrity protection, guaranteeing forward integrity. -For the details on the image and boot stages see the [image architecture](../architecture/images.md) documentation. -Any changes to the image will inevitably also change the measured boot's PCR values. -To create a node attestation statement, the Constellation image obtains a CVM attestation statement from the hardware. -This includes the runtime measurements and thereby binds the measured boot results to the CVM hardware measurement. +This includes the root filesystem. +The root filesystem is mounted read-only with integrity protection. +Any changes to the Constellation node image will inevitably change the PCR values of the measured boot and thus become evident in the node's attestation statement. +For details, refer to the documentation on [image architecture](../architecture/images.md). -In addition to the image measurements, Constellation extends a PCR during the [initialization phase](../workflows/create.md#the-init-step) that irrevocably marks the node as initialized. -The measurement is created using the [*clusterID*](../architecture/keys.md#cluster-identity), tying all future attestation statements to this ID. -Thereby, an attestation statement is unique for every cluster and a node can be identified unambiguously as being initialized. +During the initialization of a node, a certain PCR is extended with the [cluster's globally unqiue 256-bit ID](../architecture/keys.md#cluster-identity)(**FS: cross-reference**). This has two effects: +* After initialization, nodes are irrevocably marked as *initialized*. (**FS: This is important, because...**) +* Initialized nodes can only be part of one specific cluster. -To verify an attestation, the hardware's signature and a statement are verified first to establish trust in the contained runtime measurements. -If successful, the measurements are verified against the trusted values of the particular Constellation release version. -Finally, the measurement of the *clusterID* can be compared by calculating it with the [master secret](keys.md#master-secret). +(**FS: Nodes are initialized during the initialization phase of the cluster... or ...**) + +### Creating and verifying attestation statements + +Nodes obtain attestation statements for themselves directly from the confidential-computing hardware. The attestation statements include the PCR values described above and a range of other hardware and platform-specific measurements and information. + +Within Constellation, there are two components (**FS: correct?**) that verify attestation statements from nodes: The CLI verifies the attestation statement from of the first node in a cluster. The attestation statements of all subsequent nodes are verified by the [JoinService](../architecture/components.md#joinservice). + +Both components use the same policy (**FS: is this policy implicit or explicit? Need more details here.**) for verification, which demands certain hardware and platform configurations and certain node measurements. The acceptable node measurements are defined in the... (**FS: TODO**) + +(**FS: who checks the initialization status?**) ### Runtime measurements +(**FS: this restates stuff from above.**) Constellation uses runtime measurements to implement the measured boot approach. As stated above, the underlying hardware technology and guest firmware differ in their implementations of runtime measurements. The following gives a detailed description of the available measurements in the different cloud environments. @@ -108,27 +116,22 @@ The runtime measurements consist of two types of values: These are measurements of closed-source firmware and other values controlled by the cloud provider. While not being reproducible for the user, some of them can be compared against previously observed values. Others may change frequently and aren't suitable for verification. -The [signed image measurements](#chain-of-trust) include measurements that are known, previously observed values. * **Measurements produced by the Constellation bootloader and boot chain**: -The Constellation Bootloader takes over from the CVM firmware and [measures the rest of the boot chain](images.md). +The Constellation [Bootloader](images.md#bootloader) (**FS: we should talk about this somewhere.**) takes over from the CVM firmware and [measures the rest of the boot chain](images.md). The Constellation [Bootstrapper](components.md#bootstrapper) is the first user mode component that runs in a Constellation image. -It extends PCR registers with the [IDs](keys.md#cluster-identity) of the cluster marking a node as initialized. +It extends PCR registers with the [IDs](keys.md#cluster-identity) of the cluster marking a node as initialized. (**FS: initialization is duplicate.**) -Constellation allows to specify in the config which measurements should be enforced during the attestation process. -Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. -By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. +All cloud platforms supported by Constellation offer the abstraction of a vTPM for runtime measurements and remote attestation. The following table details what is measured into which PCR on each supported cloud platform. The table also lists which entity performs each measurement and if the measurement is reproducible offline. Only reproducible values can be used for remote attestation. + +In those cases where the table lists more than one measuring entity, them same PCR is subsequently extended by those entities. Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. -This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. -It provides a [measured boot](https://docs.microsoft.com/en-us/azure/security/fundamentals/measured-boot-host-attestation#measured-boot) verification that's based on the trusted launch feature of [Trusted Launch VMs](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch). - -The following table lists all PCR values of the vTPM and the measured components. -It also lists what components of the boot chain did the measurements and if the value is reproducible and verifiable. -The latter means that the value can be generated offline and compared to the one in the vTPM. +This vTPM runs inside the CVM at privilege level 0 (VMPL0) and is thus protected both from the outside as well as other code running inside the CVM. +It provides a [measured boot](https://docs.microsoft.com/en-us/azure/security/fundamentals/measured-boot-host-attestation#measured-boot) verification based on the trusted launch feature of [Trusted Launch VMs](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch). | PCR | Components | Measured by | Reproducible and verifiable | | ----------- | ---------------------------------------------------------------- | ------------------------------- | --------------------------- | @@ -143,9 +146,9 @@ The latter means that the value can be generated offline and compared to the one | 8 | - | - | - | | 9 | initramfs | Linux Kernel | Yes | | 10 | Reserved | - | No | -| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes | +| 11 | Reserved for Unified Kernel Image components | - | Yes | | 12 | Kernel command line | Constellation Bootloader | Yes | -| 13 | Reserved | (Constellation Bootloader) | Yes | +| 13 | Reserved | - | Yes | | 14 | Secure Boot State | Constellation Bootloader | No | | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | @@ -154,14 +157,7 @@ The latter means that the value can be generated offline and compared to the one Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. -Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. - -The vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. -It provides a [launch attestation report](https://cloud.google.com/compute/confidential-vm/docs/monitoring#about_launch_attestation_report_events) that's based on the measured boot feature of [Shielded VMs](https://cloud.google.com/compute/shielded-vm/docs/shielded-vm#measured-boot). - -The following table lists all PCR values of the vTPM and the measured components. -It also lists what components of the boot chain did the measurements and if the value is reproducible and verifiable. -The latter means that the value can be generated offline and compared to the one in the vTPM. +Note that this vTPM doesn't yet run inside the hardware-protected CVM context, but is emulated by the hypervisor. The vTPM provides a [launch attestation report](https://cloud.google.com/compute/confidential-vm/docs/monitoring#about_launch_attestation_report_events) that's based on the measured boot feature of [Shielded VMs](https://cloud.google.com/compute/shielded-vm/docs/shielded-vm#measured-boot). | PCR | Components | Measured by | Reproducible and verifiable | | ----------- | ---------------------------------------------------------------- | ----------------------------- | --------------------------- | @@ -176,9 +172,9 @@ The latter means that the value can be generated offline and compared to the one | 8 | - | - | - | | 9 | initramfs | Linux Kernel | Yes | | 10 | Reserved | - | No | -| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes | +| 11 | Reserved for Unified Kernel Image components | - | Yes | | 12 | Kernel command line | Constellation Bootloader | Yes | -| 13 | Reserved | (Constellation Bootloader) | Yes | +| 13 | Reserved | - | Yes | | 14 | Secure Boot State | Constellation Bootloader | No | | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | @@ -188,14 +184,7 @@ The latter means that the value can be generated offline and compared to the one Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. -The vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. -The VMs are attested by obtaining signed PCR values over the VM's boot configuration from the TPM and comparing them to a known, good state (measured boot). - -The following table lists all PCR values of the vTPM and the measured components. -It also lists what components of the boot chain did the measurements and if the value is reproducible and verifiable. -The latter means that the value can be generated offline and compared to the one in the vTPM. - -| PCR | Components | Measured by | Reproducible and verifiable | +| PCR | Components | Measured by | Reproducible | | ----------- | ---------------------------------------------------------------- | ----------------------------- | --------------------------- | | 0 | Firmware | AWS | No | | 1 | Firmware | AWS | No | @@ -208,9 +197,9 @@ The latter means that the value can be generated offline and compared to the one | 8 | - | - | - | | 9 | initramfs | Linux Kernel | Yes | | 10 | Reserved | - | No | -| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes | +| 11 | Reserved for Unified Kernel Image components | - | Yes | | 12 | Kernel command line | Constellation Bootloader | Yes | -| 13 | Reserved | (Constellation Bootloader) | Yes | +| 13 | Reserved | - | Yes | | 14 | Secure Boot State | Constellation Bootloader | No | | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | @@ -218,34 +207,40 @@ The latter means that the value can be generated offline and compared to the one +Constellation allows to specify in the config (**FS: ref**) which measurements/PCRs should be enforced during the attestation process. (**FS: we need to have a default policy.**) +Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. +By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. + ## Cluster attestation -Cluster-facing, Constellation's [*JoinService*](components.md#joinservice) verifies each node joining the cluster given the configured ground truth runtime measurements. -User-facing, the [*VerificationService*](components.md#verificationservice) provides an interface to verify a node using remote attestation. -By verifying the first node during the [initialization](components.md#bootstrapper) and configuring the ground truth measurements that are subsequently enforced by the *JoinService*, the whole cluster is verified in a transitive way. +Within a cluster, Constellation's [*JoinService*](components.md#joinservice) verifies each node joining the cluster given the configured ground truth runtime measurements. (**FS: this is the first time we're talking about this.**) +Towards the user, the [*VerificationService*](components.md#verificationservice) provides an interface to verify a node using remote attestation. +By verifying the first node during the [initialization](components.md#bootstrapper) and configuring the ground truth measurements that are subsequently enforced by the *JoinService*, the whole cluster is verified in a transitive way. (**FS: This is a good sentence, but it is coming too late and it probably was said several times before. And below...**) -### Cluster-facing attestation +### Node-to-cluster attestation -The *JoinService* is provided with the runtime measurements of the whitelisted Constellation image version as the ground truth. -During the initialization and the cluster bootstrapping, each node connects to the *JoinService* using [aTLS](#attested-tls-atls). +The *JoinService* is provided with the runtime measurements of the whitelisted Constellation image version as the ground truth. (**FS: where is this coming from?**) +During the initialization and the cluster bootstrapping, each node connects to the *JoinService* using [aTLS](#attested-tls-atls). (**FS: repeat?**) During the handshake, the node transmits an attestation statement including its runtime measurements. The *JoinService* verifies that statement and compares the measurements against the ground truth. For details of the initialization process check the [component descriptions](components.md). -After the initialization, every node updates its runtime measurements with the *clusterID* value, marking it irreversibly as initialized. +After the initialization, every node updates its runtime measurements with the *clusterID* value, marking it irreversibly as initialized. (**FS: again?!**) When an initialized node tries to join another cluster, its measurements inevitably mismatch the measurements of an uninitialized node and it will be declined. -### User-facing attestation +### Cluster-to-user attestation The [*VerificationService*](components.md#verificationservice) provides an endpoint for obtaining its hardware-based remote attestation statement, which includes the runtime measurements. A user can [verify](../workflows/verify-cluster.md) this statement and compare the measurements against the configured ground truth and, thus, verify the identity and integrity of all Constellation components and the cluster configuration. Subsequently, the user knows that the entire cluster is in the expected state and is trustworthy. ## Chain of trust +(**FS: Need to reference this earlier. Following text can probably be removed.**) + So far, this page described how an entire Constellation cluster can be verified using hardware attestation capabilities and runtime measurements. The last missing link is how the ground truth in the form of runtime measurements can be securely distributed to the verifying party. -The build process of Constellation images also creates the ground truth runtime measurements. +The build process of Constellation images creates ground truth runtime measurements. With every release, Edgeless Systems publishes signed runtime measurements. The CLI executable is also signed by Edgeless Systems.