diff --git a/docs/docs/architecture/attestation.md b/docs/docs/architecture/attestation.md index 6674e06ecb..662b38f33d 100644 --- a/docs/docs/architecture/attestation.md +++ b/docs/docs/architecture/attestation.md @@ -39,8 +39,8 @@ The root filesystem contains all components of the container's runtime environm In the userland, the guest agent takes care of enforcing the [runtime policy](../components/overview.md#runtime-policies) of the pod. While the policy is passed in during the initialization procedure via the host, the evidence for the runtime policy is part of the CPU measurements. During the [deployment](../deployment.md#generate-policy-annotations-and-manifest) the policy is annotated to the Kubernetes Pod resources. -On AMD SEV-SNP the hash of the policy is then added to the attestation report via the `HOSTDATA` field by the hypervisor. -When provided with the policy from the Kata host, the guest agent verifies that the policy's hash matches the one in the `HOSTDATA` field. +The hypervisor adds the hash of the policy to the attestation report via the HOSTDATA (on AMD SEV-SNP) or MRCONFIGID (Intel TDX) fields. +When provided with the policy from the Kata host, the guest agent verifies that the policy's hash matches the one in the `HOSTDATA`/`MRCONFIGID` field. In summary a Pod's evidence is the attestation report of the CPU that provides evidence for runtime environment and the runtime policy. @@ -92,7 +92,7 @@ By validating the runtime environment and the policies enforced on it, Contrast ### How does Contrast ensure the security of the attestation process? -Contrast leverages hardware-rooted security features such as AMD SEV-SNP to generate cryptographic evidence of a pod’s current state and configuration. +Contrast leverages hardware-rooted security features such as AMD SEV-SNP or Intel TDX to generate cryptographic evidence of a pod’s current state and configuration. This evidence is checked against pre-defined appraisal policies to guarantee that only verified and authorized pods are part of a Contrast deployment. ### What security benefits does attestation provide? diff --git a/docs/docs/components/policies.md b/docs/docs/components/policies.md index dbffdd2db6..1932280e57 100644 --- a/docs/docs/components/policies.md +++ b/docs/docs/components/policies.md @@ -36,10 +36,10 @@ These constitute the policy's *OCI data*. ## Evaluation The generated policy document is annotated to the pod definitions in Base64 encoding. -This annotation is propagated to the Kata runtime, which calculates the SHA256 checksum for the policy and uses that as SNP `HOSTDATA` for the confidential micro-VM. +This annotation is propagated to the Kata runtime, which calculates the SHA256 checksum for the policy and uses that as SNP `HOSTDATA` or TDX `MRCONFIGID` for the confidential micro-VM. After the VM launched, the runtime calls the agent's `SetPolicy` method with the full policy document. -If the policy doesn't match the checksum in `HOSTDATA`, the agent rejects the policy. +If the policy doesn't match the checksum in `HOSTDATA` or `MRCONFIGID`, the agent rejects the policy. Otherwise, it applies the policy to all future `AgentService` requests. ## Guarantees @@ -66,12 +66,12 @@ Contrast verifies its confidential containers following these steps: 1. The Contrast CLI generates a policy and attaches it to the pod definition. 2. Kubernetes schedules the pod on a node with the confidential computing runtime. 3. Containerd invokes the Kata runtime to create the pod sandbox. -4. The Kata runtime starts a CVM with the policy's digest as `HOSTDATA`. +4. The Kata runtime starts a CVM with the policy's digest as `HOSTDATA`/`MRCONFIGID`. 5. The Kata runtime sets the policy using the `SetPolicy` method. -6. The Kata agent verifies that the incoming policy's digest matches `HOSTDATA`. +6. The Kata agent verifies that the incoming policy's digest matches `HOSTDATA`/`MRCONFIGID`. 7. The CLI sets a manifest in the Contrast Coordinator, including a list of permitted policies. 8. The Contrast Initializer sends an attestation report to the Contrast Coordinator, asking for a mesh certificate. -9. The Contrast Coordinator verifies that the started pod has a permitted policy hash in its `HOSTDATA` field. +9. The Contrast Coordinator verifies that the started pod has a permitted policy hash in its `HOSTDATA`/`MRCONFIGID` field. After the last step, we know that the policy hasn't been tampered with and, thus, that the workload matches expectations and may receive mesh certificates. diff --git a/docs/docs/components/runtime.md b/docs/docs/components/runtime.md index a0be9e3043..b40992b6ac 100644 --- a/docs/docs/components/runtime.md +++ b/docs/docs/components/runtime.md @@ -31,7 +31,7 @@ spec: ## Node-level components The runtime consists of additional software components that need to be installed -and configured on every SEV-SNP-enabled worker node. +and configured on every SEV-SNP-enabled/TDX-enabled worker node. This installation is performed automatically by the [`node-installer` DaemonSet](#node-installer-daemonset). ![Runtime components](../_media/runtime.svg) diff --git a/docs/docs/deployment.md b/docs/docs/deployment.md index cc330e4b79..88f2d11618 100644 --- a/docs/docs/deployment.md +++ b/docs/docs/deployment.md @@ -8,7 +8,10 @@ confidential and deploying it together with Contrast. A running CoCo-enabled cluster is required for these steps, see the [setup guide](./getting-started/cluster-setup.md) on how to set up a cluster on AKS. -A running CoCo-enabled cluster is required for these steps, see the [setup guide](./getting-started//bare-metal.md) on how to set up a bare metal cluster. +A running CoCo-enabled cluster is required for these steps, see the [setup guide](./getting-started/bare-metal.md) on how to set up a bare metal cluster. + + +A running CoCo-enabled cluster is required for these steps, see the [setup guide](./getting-started/bare-metal.md) on how to set up a bare metal cluster. @@ -31,6 +34,11 @@ kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/downloa kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/runtime-k3s-qemu-snp.yml ``` + +```sh +kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/runtime-k3s-qemu-tdx.yml +``` + ## Deploy the Contrast Coordinator @@ -49,6 +57,11 @@ kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/downloa kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/coordinator-k3s-qemu-snp.yml ``` + +```sh +kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/coordinator-k3s-qemu-tdx.yml +``` + ## Prepare your Kubernetes resources @@ -194,6 +207,11 @@ contrast generate --reference-values aks-clh-snp resources/ contrast generate --reference-values k3s-qemu-snp resources/ ``` + +```sh +contrast generate --reference-values k3s-qemu-tdx resources/ +``` + :::warning @@ -221,6 +239,11 @@ contrast generate --reference-values aks-clh-snp --skip-initializer resources/ contrast generate --reference-values k3s-qemu-snp --skip-initializer resources/ ``` + +```sh +contrast generate --reference-values k3s-qemu-tdx --skip-initializer resources/ +``` + diff --git a/docs/docs/examples/emojivoto.md b/docs/docs/examples/emojivoto.md index ad9bb53cc9..bf89a6c8b9 100644 --- a/docs/docs/examples/emojivoto.md +++ b/docs/docs/examples/emojivoto.md @@ -63,6 +63,11 @@ kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/downloa kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/runtime-k3s-qemu-snp.yml ``` + +```sh +kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/runtime-k3s-qemu-tdx.yml +``` + ### Deploy the Contrast Coordinator @@ -81,6 +86,11 @@ kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/downloa kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/coordinator-k3s-qemu-snp.yml ``` + +```sh +kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/coordinator-k3s-qemu-tdx.yml +``` + ### Generate policy annotations and manifest @@ -100,6 +110,11 @@ contrast generate --reference-values aks-clh-snp deployment/ contrast generate --reference-values k3s-qemu-snp deployment/ ``` + +```sh +contrast generate --reference-values k3s-qemu-tdx deployment/ +``` + :::note[Runtime class and Initializer] diff --git a/docs/docs/features-limitations.md b/docs/docs/features-limitations.md index 14940308b7..a6809ccf53 100644 --- a/docs/docs/features-limitations.md +++ b/docs/docs/features-limitations.md @@ -33,3 +33,7 @@ The policy limitations, in particular the missing guarantee that our service mes The Contrast Coordinator is a singleton and can't be scaled to more than one instance. When this instance's pod is restarted, for example for node maintenance, it needs to be recovered manually. In a future release, we plan to support distributed Coordinator instances that can recover automatically. + +## Attestation + +Attestation for TDX isn't completely implemented yet and shouldn't yet be relied upon for security. This will be fixed in a future release. diff --git a/docs/docs/getting-started/bare-metal.md b/docs/docs/getting-started/bare-metal.md index b34e193fff..b918aba570 100644 --- a/docs/docs/getting-started/bare-metal.md +++ b/docs/docs/getting-started/bare-metal.md @@ -2,15 +2,29 @@ ## Hardware and firmware setup + + 1. Update your BIOS to a version that supports AMD SEV-SNP. Updating to the latest available version is recommended as newer versions will likely contain security patches for AMD SEV-SNP. 2. Enter BIOS setup to enable SMEE, IOMMU, RMP coverage, and SEV-SNP. Set the SEV-ES ASID Space Limit to a non-zero number (higher is better). 3. Download the latest firmware version for your processor from [AMD](https://www.amd.com/de/developer/sev.html), unpack it, and place it in `/lib/firmware/amd`. Consult AMD's [Using SEV with AMD EPYC Processors user guide](https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/tuning-guides/58207-using-sev-with-amd-epyc-processors.pdf) for more information. + + +Follow Canonical's instructions on [setting up Intel TDX in the host's BIOS](https://github.com/canonical/tdx?tab=readme-ov-file#43-enable-intel-tdx-in-the-hosts-bios). + + ## Kernel Setup -1. Install a kernel with version 6.11 or greater. If you're following this guide before 6.11 has been released, use 6.11-rc3. Don't use 6.11-rc4 - 6.11-rc6 as they contain a regression. 6.11-rc7+ might work. + + +Install a kernel with version 6.11 or greater. If you're following this guide before 6.11 has been released, use 6.11-rc3. Don't use 6.11-rc4 - 6.11-rc6 as they contain a regression. 6.11-rc7+ might work. + + +Follow Canonical's instructions on [setting up Intel TDX on Ubuntu 24.04](https://github.com/canonical/tdx?tab=readme-ov-file#41-install-ubuntu-2404-server-image). Note that Contrast currently only supports Intel TDX with Ubuntu 24.04. + + ## K3s Setup diff --git a/tools/vale/styles/config/vocabularies/edgeless/accept.txt b/tools/vale/styles/config/vocabularies/edgeless/accept.txt index 7fe510c59c..88e4673f64 100644 --- a/tools/vale/styles/config/vocabularies/edgeless/accept.txt +++ b/tools/vale/styles/config/vocabularies/edgeless/accept.txt @@ -18,6 +18,7 @@ bootloader Bootstrapper cachable cachix +Canonical changeset CLI cloud