docs: publish to 2.0

This commit is contained in:
Thomas Tendyck 2022-10-10 09:24:55 +02:00 committed by Thomas Tendyck
parent 617a55a230
commit 7003a86363
8 changed files with 73 additions and 87 deletions

View File

@ -4,7 +4,7 @@ This page explains Constellation's attestation process and highlights the corner
## Terms
The following lists a few terms and concepts that helps to understand the attestation concept of Constellation.
The following lists terms and concepts that help to understand the attestation concept of Constellation.
### Trusted Platform Module (TPM)
@ -32,8 +32,8 @@ Thus, storing the measurements of multiple components into the same PCR irrevers
### 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 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.
### Remote attestation (RA)
@ -54,7 +54,7 @@ Such an attestation statement guarantees the confidentiality and integrity of a
### Attested TLS (aTLS)
In a CC environment, attested TLS (aTLS) can be used to establish secure connections between two parties utilizing the remote attestation features of the CC components.
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.
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.
@ -80,7 +80,7 @@ The solution is a verifiable boot chain and an integrity-protected runtime envir
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.
CVM technologies differ in how they implement runtime measurements, but the general concepts are similar to those of a TPM.
For simplicity, we use TPM terminology like *PCR* in the following.
For simplicity, TPM terminology like *PCR* is used 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.
@ -100,42 +100,39 @@ Finally, the measurement of the *clusterID* can be compared by calculating it wi
### Runtime measurements
Constellation utilizes runtime measurement to implement the measured boot approach.
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.
The runtime measurements contain two types of values.
The runtime measurements consist of two types of values:
First, are the ones produced by the cloud infrastructure and firmware of the CVM.
Depending on the cloud environment they can contain non-reproducible values.
Those correspond to measurements of closed-source firmware components and other values controlled by the cloud provider.
While not being directly verifiable, they can be compared against previously observed values.
As part of the [signed image measurements](#chain-of-trust), Constellation provides measurements that are known, previously observed values.
Thereby, Constellation enables users to identify changes and deviations and allows them to act accordingly.
See how to [fetch](../workflows/verify-cluster.md#fetch-measurements) the latest measurements and verify a cluster.
* **Measurements produced by the cloud infrastructure and firmware of the CVM**:
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.
Second, are the measurements produced by the Constellation bootloader and boot chain itself.
The Constellation Bootloader is the first part of the Constellation stack that takes over from the CVM firmware and measures the rest of the boot chain.
Refer to [images](images.md) for more details on the Constellation boot chain.
* **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 [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.
Constellation allows to specify in the config which measurements should be enforced during the attestation process
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.
<tabs groupId="csp">
<tabItem value="azure" label="Azure">
Constellation leverages the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements.
The vTPM on Azure CVMs adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification of the [Trusted Computing Group](https://trustedcomputinggroup.org/resource/trusted-platform-module-tpm-summary/).
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 value can be generated offline and compared to the one in the vTPM
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 and verifiable |
|---------------|-------------------------------------|---------------------------------|-----------------------------|
| 0 | Firmware | Azure | No |
| 1 | Firmware | Azure | No |
@ -155,17 +152,17 @@ The latter means that value can be generated offline and compared to the one in
</tabItem>
<tabItem value="gcp" label="GCP">
Constellation leverages the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements.
Note that the vTPM in GCP doesn't run inside the hardware-protected CVM context, but is emulated on the hypervisor level.
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 on GCP CVMs adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification of the [Trusted Computing Group](https://trustedcomputinggroup.org/resource/trusted-platform-module-tpm-summary/).
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 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 value can be generated offline and compared to the one in the vTPM.
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 and verifiable |
|---------------|----------------------------------|-------------------------------|-----------------------------|
| 0 | CVM constant string | GCP | No |
| 1 | Reserved | GCP | No |
@ -212,19 +209,16 @@ A user can [verify](../workflows/verify-cluster.md) this statement and compare t
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.
When building Constellation images the process entails creating the ground truth runtime measurements.
The builds of Constellation images are reproducible and the measurements of an image can be recalculated and verified by everyone.
The build process of Constellation images also creates the ground truth runtime measurements. <!-- soon: The builds of Constellation images are reproducible and the measurements of an image can be recalculated and verified by everyone. -->
With every release, Edgeless Systems publishes signed runtime measurements.
When installing the Constellation CLI, the release binary is also signed by Edgeless Systems.
The [installation guide](../architecture/orchestration.md#verify-your-cli-installation) explains how this signature can be verified.
The release binary is also signed by Edgeless Systems.
The [installation guide](../architecture/orchestration.md#verify-your-cli-installation) explains how you can verify this signature.
The CLI contains the public key required to verify signed runtime measurements from Edgeless Systems.
When a new cluster is [created](../workflows/create.md) or updated, the CLI automatically verifies the measurements for the selected image.
Alternatively, Constellation has the option to use and verify custom build images.
For this, the CLI can be provided with a custom public key for verification.
When a cluster is [created](../workflows/create.md) or [upgraded](../workflows/upgrade.md), the CLI automatically verifies the measurements for the selected image.
Thus, we've a chain of trust based on cryptographic signatures, which goes from CLI to runtime measurements to images. This is illustrated in the following diagram.
Thus, there's a chain of trust based on cryptographic signatures, which goes from CLI to runtime measurements to images. This is illustrated in the following diagram.
```mermaid
flowchart LR
@ -232,6 +226,6 @@ flowchart LR
C[User]-- "verifies (cosign)" -->B[CLI]
B[CLI]-- "contains" -->D["Public Key"]
A[Edgeless]-- "signs" -->E["Runtime measurements"]
D["Public Key"]-- "verifies" -->E["Runtime measurements"]
D["Public key"]-- "verifies" -->E["Runtime measurements"]
E["Runtime measurements"]-- "verify" -->F["Constellation cluster"]
```

View File

@ -33,9 +33,9 @@ The remote attestation statement of a Constellation cluster combines *baseID* an
Constellation encrypts all cluster network communication using the [container network interface (CNI)](https://github.com/containernetworking/cni).
See [network encryption](networking.md) for more details.
The Cilium agent running on each cluster node will establish a secure WireGuard tunnel between it and all other known nodes in the cluster.
Each node automatically creates its own [Curve25519](http://cr.yp.to/ecdh.html) encryption key-pair and distributes its public key via Kubernetes.
Each nodes public key is then used by other nodes to decrypt and encrypt traffic from and to Cilium-managed endpoints running on that node.
The Cilium agent running on each node establishes a secure [WireGuard](https://www.wireguard.com/) tunnel between it and all other known nodes in the cluster.
Each node creates its own [Curve25519](http://cr.yp.to/ecdh.html) encryption key pair and distributes its public key via Kubernetes.
A node uses another node's public key to decrypt and encrypt traffic from and to Cilium-managed endpoints running on that node.
Connections are always encrypted peer-to-peer using [ChaCha20](http://cr.yp.to/chacha.html) with [Poly1305](http://cr.yp.to/mac.html).
WireGuard implements [forward secrecy with key rotation every 2 minutes](https://lists.zx2c4.com/pipermail/wireguard/2017-December/002141.html).
Cilium supports [key rotation](https://docs.cilium.io/en/stable/gettingstarted/encryption-ipsec/#key-rotation) for the long-term node keys via Kubernetes secrets.
@ -61,10 +61,10 @@ As a cluster administrator, when creating a cluster, you can use the Constellati
#### Key material and key derivation
During the creation of a Constellation, the cluster's master secret is used to derive a KEK.
During the creation of a Constellation cluster, the cluster's master secret is used to derive a KEK.
This means creating two clusters with the same master secret will yield the same KEK.
Any data encryption key (DEK) is derived from the KEK via HKDF.
Note that the master secret is recommended to be unique for every Constellation cluster and shouldn't be reused (except in case of [recovering](../workflows/recovery.md) a cluster).
Note that the master secret is recommended to be unique for every cluster and shouldn't be reused (except in case of [recovering](../workflows/recovery.md) a cluster).
#### State and storage
@ -91,7 +91,7 @@ User-managed key management is under active development and will be available so
In scenarios where constellation-managed key management isn't an option, this mode allows you to keep full control of your keys.
For example, compliance requirements may force you to keep your KEKs in an on-prem key management system (KMS).
During the creation of a Constellation, you specify a KEK present in a remote KMS.
During the creation of a Constellation cluster, you specify a KEK present in a remote KMS.
This follows the common scheme of "bring your own key" (BYOK).
Constellation will support several KMSs for managing the storage and access of your KEK.
Initially, it will support the following KMSs:

View File

@ -10,14 +10,13 @@ Cilium is actively working on implementing a feature called [`host-to-host`](htt
With `host-to-host`, all traffic between nodes will be tunneled via WireGuard (host-to-host, host-to-pod, pod-to-host, pod-to-pod).
Until the `host-to-host` feature is released, Constellation enables `pod-to-pod` encryption.
This mode encrypts all traffic between Kubernetes pods using WireGuard tunnels.
Constellation uses an extended version of `pod-to-pod` called *strict* mode.
When using Cilium in the default setup but with encryption enabled, there is a [known issue](https://docs.cilium.io/en/v1.12/gettingstarted/encryption/#egress-traffic-to-not-yet-discovered-remote-endpoints-may-be-unencrypted)
that can cause pod-to-pod traffic to be unencrypted.
Constellation uses strict mode to mitigates this issue.
We change the default behavior of traffic that's destined for an unknown endpoint to not be send out in plaintext to instead being dropped.
The strict mode can distinguish between traffic that's send to an pod from traffic that's destined for an cluster-external endpoint, since it knows the pod's CIDR range.
To mitigate this issue, Constellation adds a *strict* mode to Cilium's `pod-to-pod` encryption.
This mode changes the default behavior of traffic that's destined for an unknown endpoint to not be send out in plaintext, but instead being dropped.
The strict mode distinguishes between traffic that's send to a pod from traffic that's destined for a cluster-external endpoint by considering the pod's CIDR range.
The last remaining traffic that's not encrypted is traffic originating from hosts.
Traffic originating from hosts isn't encrypted yet.
This mainly includes health checks from Kubernetes API server.
Also, traffic proxied over the API server via e.g. `kubectl port-forward` isn't encrypted.

View File

@ -8,45 +8,42 @@ The CLI is also used for updating your cluster.
## Workspaces
Each Constellation cluster has an associated *workspace*.
The workspace is where the persistent data such as the Constellation state, config, and ID files are stored.
The workspace is where data such as the Constellation state, config, and ID files are stored.
Each workspace is associated with a single cluster and configuration.
Currently, the CLI stores state in the local filesystem making the current directory the active workspace.
The CLI stores state in the local filesystem making the current directory the active workspace.
Multiple clusters require multiple workspaces, hence, multiple directories.
Note that every operation on a cluster always has to be performed from the directory associated with its workspace.
## Cluster creation process
Releases of Constellation are [published on GitHub](https://github.com/edgelesssys/constellation/releases).
To allow for fine-grained configuration of your cluster and cloud environment, Constellation supports an extensive configuration file with strong defaults. [Generating the configuration file](../workflows/create.md#configuration) is typically the first thing you do in the workspace.
To allow for fine-grained configuration of your cluster and cloud environment, Constellation supports an extensive configuration file with strong defaults.
The CLI provides you with a good default configuration which can be generated with `constellation config generate`. Some cloud account-specific information is always required and to be set by the user.
The following files are generated during the creation of a Constellation cluster and stored in the current workspace:
Altogether, the following files are generated during the creation of a Constellation cluster and stored in the current workspace:
* a configuration file
* a state file
* an ID file
* a base64 encoded master secret
* a Base64-encoded master secret
* a Kubernetes `kubeconfig` file.
Constellation must store the state of its created infrastructure and configuration.
This state is used by Constellation to map real-world resources to your configuration and keep track of metadata.
This state is stored by default in a local file named `constellation-state.json`.
This state is stored in a local file named `constellation-state.json`.
After the successful creation of your cluster, the CLI will provide you with a Kubernetes `kubeconfig` file.
This file provides you with access to your Kubernetes cluster and configures the [kubectl](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) tool.
After the creation of your cluster, the CLI will provide you with a Kubernetes `kubeconfig` file.
This file grants you access to your Kubernetes cluster and configures the [kubectl](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) tool.
In addition, the cluster's [identifier](orchestration.md#post-installation-configuration) is returned and stored in a file called `constellation-id.json`
### Creation process details
1. The CLI `create` command creates the confidential VMs (CVMs) resources in your cloud environment and configures the network
1. The CLI `create` command creates the confidential VM (CVM) resources in your cloud environment and configures the network
2. Each CVM boots the Constellation node image and measures every component in the boot chain
3. The first component launched in each node is the [*Bootstrapper*](components.md#bootstrapper)
4. The *Bootstrapper* waits until it either receives an initialization request or discovers an initialized cluster
5. The CLI `init` command connects to the *Bootstrapper* of a selected node, sends the configuration, and initiates the initialization of the cluster
6. The *Bootstrapper* of **that** node [initializes the Kubernetes cluster](components.md#bootstrapper) and deploys the other Constellation [components](components.md) including the [*JoinService*](components.md#joinservice)
7. Subsequently, the *Bootstrappers* of the other nodes discover the initialized cluster and send join requests to the *JoinService*
8. As part of the join request each node includes an attestation statement of its boot measurements as a form of authentication
8. As part of the join request each node includes an attestation statement of its boot measurements as authentication
9. The *JoinService* verifies the attestation statements and joins the nodes to the Kubernetes cluster
10. This process is repeated for every node joining the cluster later (e.g., through autoscaling)
@ -62,7 +59,7 @@ Without it, you won't be able to modify or terminate your cluster.
After the initialization, the CLI will present you with a couple of tokens:
* The [*master secret*](keys.md#master-secret) (stored in the `constellation-mastersecret.json` file by default)
* The [*clusterID*](keys.md#cluster-identity) of your cluster in base64 format
* The [*clusterID*](keys.md#cluster-identity) of your cluster in Base64 encoding
You can read more about these values and their meaning in the guide on [cluster identity](keys.md#cluster-identity).
@ -73,16 +70,16 @@ The *clusterID* uniquely identifies a cluster and can be used to [verify your cl
## Upgrades
Constellation images and components might need to be upgraded to new versions during the lifetime of a cluster.
Constellation images and components may need to be upgraded to new versions during the lifetime of a cluster.
Constellation implements a rolling update mechanism ensuring no downtime of the control or data plane.
You can upgrade a Constellation cluster with a single operation by using the CLI.
For step-by-step instructions on how to do this, refer to [Upgrade Constellation](../workflows/upgrade.md).
For step-by-step instructions on how to do this, refer to [Upgrade your cluster](../workflows/upgrade.md).
### Attestation of upgrades
The new verification hashes (measurements) are released together with every image.
With every new image, corresponding measurements are released.
During an update procedure, the CLI provides the new measurements to the [JoinService](components.md#joinservice) securely.
New measurements for an updated image are automatically pulled and verified by the CLI following the [supply chain security concept](attestation.md#chain-of-trust) of Constellation.
The [attestation section](attestation.md#cluster-facing-attestation) describes in detail how these measurements are then used by the JoinService for the attestation of nodes.
The updated measurements are reproducible based on the updated node images, hence, auditable by the customer.
<!-- soon: As the [builds of the Constellation images are reproducible](attestation.md#chain-of-trust), the updated measurements are auditable by the customer. -->

View File

@ -4,13 +4,14 @@ 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 installation and updates
## About orchestration and updates
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).
## About the components and attestation
Constellation manages the nodes and network in your cluster. All nodes are bootstrapped by the [*Bootstrapper*](components.md#bootstrapper). They're verified and authenticated by the [*JoinService*](components.md#joinservice) before being added to the cluster and the network. Finally, the entire cluster can be verified via the [*VerificationService*](components.md#verification-service) using [remote attestation](attestation.md).
Constellation manages the nodes and network in your cluster. All nodes are bootstrapped by the [*Bootstrapper*](components.md#bootstrapper). They're verified and authenticated by the [*JoinService*](components.md#joinservice) before being added to the cluster and the network. Finally, the entire cluster can be verified via the [*VerificationService*](components.md#verificationservice) using [remote attestation](attestation.md).
## About node images and verified boot
@ -20,4 +21,4 @@ You can learn more about [the images](images.md) and how verified boot ensures t
## About key management and cryptographic primitives
Encryption of data at-rest, in-transit, and in-use is the fundamental building block for confidential computing and Constellation. Learn more about the [keys and cryptographic primitives](keys.md) used in Constellation and about [encrypted persistent storage](encrypted-storage.md).
Encryption of data at-rest, in-transit, and in-use is the fundamental building block for confidential computing and Constellation. Learn more about the [keys and cryptographic primitives](keys.md) used in Constellation, [encrypted persistent storage](encrypted-storage.md), and [network encryption](networking.md).

View File

@ -1,12 +1,7 @@
# Versions and support policy
This page details which guarantees Constellation makes regarding versions, compatibility, and life cycle.
All released components of Constellation use a three-digit version number, of the form `v<MAJOR>.<MINOR>.<PATCH>`.
## Release cadence
All [components](components.md) of Constellation are released in lock step on the first Tuesday of every month. This release primarily introduces new features, but may also include security or performance improvements. The `MINOR` version will be incremented as part of this release.
All [components](components.md) of Constellation use a three-digit version number of the form `v<MAJOR>.<MINOR>.<PATCH>`.
The components are released in lock step, usually on the first Tuesday of every month. This release primarily introduces new features, but may also include security or performance improvements. The `MINOR` version will be incremented as part of this release.
Additional `PATCH` releases may be created on demand, to fix security issues or bugs before the next `MINOR` release window.

View File

@ -164,16 +164,6 @@
"label": "Overview",
"id": "architecture/overview"
},
{
"type": "doc",
"label": "Components",
"id": "architecture/components"
},
{
"type": "doc",
"label": "Attestation",
"id": "architecture/attestation"
},
{
"type": "doc",
"label": "Cluster orchestration",
@ -184,6 +174,16 @@
"label": "Versions and support",
"id": "architecture/versions"
},
{
"type": "doc",
"label": "Components",
"id": "architecture/components"
},
{
"type": "doc",
"label": "Attestation",
"id": "architecture/attestation"
},
{
"type": "doc",
"label": "Images",