From 1290aad6d6605b2e07ca3c742713138649cb6945 Mon Sep 17 00:00:00 2001 From: Felix Schuster Date: Fri, 14 Oct 2022 09:26:56 +0200 Subject: [PATCH] WIP --- docs/docs/architecture/attestation.md | 16 +++++++--------- docs/docs/architecture/components.md | 15 +++++++++------ docs/docs/architecture/overview.md | 2 ++ 3 files changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/docs/architecture/attestation.md b/docs/docs/architecture/attestation.md index f335038f6..0cf432afe 100644 --- a/docs/docs/architecture/attestation.md +++ b/docs/docs/architecture/attestation.md @@ -4,7 +4,7 @@ This page explains Constellation's attestation process and highlights the corner ## Terms -The following lists terms and concepts that help to understand the attestation concept of Constellation. +The following lists important terms and concepts. ### Trusted Platform Module (TPM) @@ -18,22 +18,20 @@ A runtime measurement is a cryptographic hash of the memory pages of a so called ### Platform Configuration Register (PCR) -A Platform Configuration Register (PCR) is a memory location in the TPM that has some unique properties. -To store a new value in a PCR, the existing value is extended with a new value as follows: +A Platform Configuration Register (PCR) is a memory location in the TPM that has some unique properties. PCRs cannot be written, they can only be "extended". +When a PCR is extended with a value, the PCR's new value `PCR[n]` is calculated as follows: ``` -PCR[N] = HASHalg( PCR[N] || ArgumentOfExtend ) +PCR[n] = Hash( PCR[n-1] || value ) ``` -The PCRs are typically used to store runtime measurements. -The new value of a PCR is always an extension of the existing value. -Thus, storing the measurements of multiple components into the same PCR irreversibly links them together. +Thus, the value of a PCR always depends on all previous values. PCRs are typically used to store runtime measurements. In that case, the value of a PCR uniquely reflects the sequence of runtime measurements it was extended with. ### Measured boot Measured boot builds on the concept of chained runtime measurements. -Each component in the boot chain loads and measures the next component into the PCR before executing it. -By comparing the resulting PCR values against trusted reference values, the integrity of the entire boot chain and thereby the running system can be ensured. +Each component in the boot chain loads and measures the next component and extends the measurements into the PCR. +By comparing the resulting PCR values against reference values, the integrity of the entire boot chain can be ensured. ### Remote attestation (RA) diff --git a/docs/docs/architecture/components.md b/docs/docs/architecture/components.md index f29037b09..798e17ea7 100644 --- a/docs/docs/architecture/components.md +++ b/docs/docs/architecture/components.md @@ -1,7 +1,9 @@ # Components -Constellation takes care of bootstrapping and initializing a Confidential Kubernetes cluster. -During the lifetime of the cluster, it handles day 2 operations such as key management, remote attestation, and updates. +(**FS: Overall, good**) + +Constellation takes care of bootstrapping and initializing a Confidential Kubernetes cluster. (**FS: weird**) +During the lifetime of the cluster, it handles day 2 operations such as key management, remote attestation, and updates. (**FS: features**) These features are provided by several components: * The [Bootstrapper](components.md#bootstrapper) initializes a Constellation node and bootstraps the cluster @@ -9,7 +11,7 @@ These features are provided by several components: * The [VerificationService](components.md#verificationservice) provides remote attestation functionality * The [Key Management Service (KMS)](components.md#kms) manages Constellation-internal keys -The relations between components are shown in the following diagram: +The relations between components are shown in the following diagram: (**FS: this doesn't look quite right. Talk to Moritz. Maybe remove.**) ```mermaid flowchart LR @@ -34,18 +36,19 @@ flowchart LR ## Bootstrapper +**FS: some context missing** The *Bootstrapper* is the first component launched after booting a Constellation node image. It sets up that machine as a Kubernetes node and integrates that node into the Kubernetes cluster. -To this end, the *Bootstrapper* first downloads and [verifies](https://blog.sigstore.dev/kubernetes-signals-massive-adoption-of-sigstore-for-protecting-open-source-ecosystem-73a6757da73) the [Kubernetes components](https://kubernetes.io/docs/concepts/overview/components/) at the configured versions. +To this end, the *Bootstrapper* first downloads and [verifies](https://blog.sigstore.dev/kubernetes-signals-massive-adoption-of-sigstore-for-protecting-open-source-ecosystem-73a6757da73) the [Kubernetes components](https://kubernetes.io/docs/concepts/overview/components/) at the configured versions. (**FS: where are they configured?**) The *Bootstrapper* tries to find an existing cluster and if successful, communicates with the [JoinService](components.md#joinservice) to join the node. Otherwise, it waits for an initialization request to create a new Kubernetes cluster. ## JoinService -The *JoinService* runs as [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) on each control-plane node. +The *JoinService* runs as [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) on each control-plane node (**FS: should we define control-plane somewhere?**). New nodes (at cluster start, or later through autoscaling) send a request to the service over [attested TLS (aTLS)](attestation.md#attested-tls-atls). The *JoinService* verifies the new node's certificate and attestation statement. -If attestation is successful, the new node is supplied with an encryption key from the [*KMS*](components.md#kms) for its state disk, and a Kubernetes bootstrap token. +If attestation is successful, the new node is supplied with an encryption key from the [*KMS*](components.md#kms) (**FS: we should make clear that this is our own KMS**) for its state disk and a Kubernetes bootstrap token. ```mermaid diff --git a/docs/docs/architecture/overview.md b/docs/docs/architecture/overview.md index 9f45a6ea3..a2a667df2 100644 --- a/docs/docs/architecture/overview.md +++ b/docs/docs/architecture/overview.md @@ -1,11 +1,13 @@ # Overview +**FS: OK'ish but not great. Do we need this section at all? Probably not.** Constellation is a cloud-based confidential orchestration platform. The foundation of Constellation is Kubernetes and therefore shares the same technology stack and architecture principles. To learn more about Constellation and Kubernetes, see [product overview](../overview/product.md). ## About orchestration and updates +**FS: this is more like How-To** As a cluster administrator, you can use the [Constellation CLI](orchestration.md) to install and deploy a cluster. Updates are provided in accordance with the [support policy](versions.md).