From e2eda3ff5b15558c1709a641cb1a065cc84fc4ae Mon Sep 17 00:00:00 2001 From: Paul Meyer <49727155+katexochen@users.noreply.github.com> Date: Tue, 12 Mar 2024 12:59:53 +0100 Subject: [PATCH] readme: update with changes from user manual Co-authored-by: Moritz Eckert Signed-off-by: Paul Meyer <49727155+katexochen@users.noreply.github.com> --- README.md | 68 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 49 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index d0a12c9bd7..0503054e77 100644 --- a/README.md +++ b/README.md @@ -10,22 +10,53 @@ It currently targets the [CoCo preview on AKS](https://learn.microsoft.com/en-us ## The Contrast Coordinator -The Contrast Coordinator is the central remote attestation component of a Contrast deployment. It's a certificate -authority and issues certificates for workload pods running inside confidential containers. The Coordinator -is configured with a *manifest*, a configuration file that holds the reference values of all other parts of -a deployment. The Coordinator ensures that your app's topology adheres to your specified manifest. It verifies -the identity and integrity of all your services and establishes secure, encrypted communication channels between -the different parts of your deployment. As your app needs to scale, the Coordinator transparently verifies new -instances and then provides them with mesh credentials. - -To verify your deployment, the remote attestation of the Coordinator and its manifest offers a single remote -attestation statement for your entire deployment. Anyone can use this to verify the integrity of your distributed -app, making it easier to assure stakeholders of your app's security. +The Contrast Coordinator is the central remote attestation service of a Contrast deployment. +It runs inside a confidential container inside your cluster. +The Coordinator can be verified via remote attestation, and a Contrast deployment is self-contained. +The Coordinator is configured with a *manifest*, a configuration file containing the reference attestation values of your deployment. +It ensures that your deployment's topology adheres to your specified manifest by verifying the identity and integrity of all confidential pods inside the deployment. +The Coordinator is also a certificate authority and issues certificates for your workload pods during the attestation procedure. +Your workload pods can establish secure, encrypted communication channels between themselves based on these certificates and the Coordinator as the root CA. +As your app needs to scale, the Coordinator transparently verifies new instances and then provides them with their certificates to join the deployment. + +To verify your deployment, the Coordinator's remote attestation statement combined with the manifest offers a concise single remote attestation statement for your entire deployment. +A third party can use this to verify the integrity of your distributed app, making it easy to assure stakeholders of your app's identity and integrity. + +## The Manifest + +The manifest is the configuration file for the Coordinator, defining your confidential deployment. +It is automatically generated from your deployment by the Contrast CLI. +It currently consists of the following parts: + +* *Policies*: The identities of your Pods, represented by the hashes of their respective runtime policies. +* *Reference Values*: The remote attestation reference values for the Kata confidential micro-VM that is the runtime environment of your Pods. +* *WorkloadOwnerKeyDigest*: The workload owner's public key digest. Used for authenticating subsequent manifest updates. + +## Runtime Policies + +Runtime Policies are a mechanism to enable the use of the (untrusted) Kubernetes API for orchestration while ensuring the confidentiality and integrity of your confidential containers. +They allow us to enforce the integrity of your containers' runtime environment as defined in your deployment files. +The runtime policy mechanism is based on the Open Policy Agent (OPA) and translates the Kubernetes deployment YAMLs into OPA's Rego policy language. +The Kata Agent inside the confidential micro-VM then enforces the policy by only acting on permitted requests. +The Contrast CLI provides the tooling for automatically translating Kubernetes deployment YAMLs into OPA's Rego policy language. + +The trust chain goes as follows: + +1. The Contrast CLI generates a policy and attaches it to the pod definition. +2. Kubernetes schedules the pod on a node with kata-cc-isolation runtime. +3. Containerd takes the node, starts the Kata Shim and creates the pod sandbox. +4. The Kata runtime starts a CVM with the policy's digest as `HOSTDATA`. +5. The Kata runtime sets the policy using the `SetPolicy` method. +6. The Kata agent verifies that the incoming policy's digest matches `HOSTDATA`. +7. The CLI sets a manifest in the Contrast Coordinator, including a list of permitted policies. +8. The Contrast Coordinator verifies that the started pod has a permitted policy hash in its `HOSTDATA` field. + +After the last step, we know that the policy has not been tampered with and, thus, that the workload is as intended. ## The Contrast Initializer Contrast provides an Initializer that handles the remote attestation on the workload side transparently and -fetches the workload certificate. The Initializer runs as init container before your workload is started. +fetches the workload certificate. The Initializer runs as an init container before your workload is started. ## Installation @@ -43,7 +74,7 @@ confidential and deploying it together with Contrast. ### Prerequisite -A CoCo enabled cluster is required to run Contrast. Create it using the `az` CLI: +A CoCo enabled cluster is required to run Contrast. Create it using the [`az`](https://docs.microsoft.com/en-us/cli/azure/) CLI: ```sh az extension add \ @@ -193,20 +224,19 @@ curl --cacert ./verify/mesh-root.pem "https://${lbip}:8443" ## Current limitations -Contrast is in an early development stage and most underlying projects are under development, too. -As a result there are currently certain limitations, from which we try to document the most significant -ones here: +Contrast is in an early preview stage, and most underlying projects are still under development as well. +As a result, there are currently certain limitations from which we try to document the most significant ones here: -- Only availabile on AKS with CoCo preview (AMD SEV-SNP) +- Only available on AKS with CoCo preview (AMD SEV-SNP) - Persistent volumes currently not supported in CoCo - While workload policies are functional in general, but [not covering all edge cases](https://github.com/microsoft/kata-containers/releases/tag/genpolicy-0.6.2-5) - Port-forwarding isn't supported by Kata Containers yet -- CLI only available for Linux (mostly because upstream dependencies are not availabile for other platforms) +- CLI is only available for Linux (mostly because upstream dependencies are not available for other platforms) ## Upcoming Contrast features - Transparent service mesh (apps can currently use mTLS with Coordinator certs for secure communication) -- Plugin key management service (KMS) for attestation/coordinator certificate based key release +- Plugin for a key management service (KMS) for attestation/coordinator certificate-based key release - High availability (distributed Contrast Coordinator) ## Contributing