diff --git a/dev-docs/user-manual.md b/dev-docs/user-manual.md deleted file mode 100644 index 9a14380f1..000000000 --- a/dev-docs/user-manual.md +++ /dev/null @@ -1,95 +0,0 @@ -## Features - -### 🔒 Everything always encrypted - -* Runtime encryption: All Pods run inside AMD SEV-based Confidential VMs (CVMs). Support for Intel TDX will be added in the future. -* PKI and mTLS: All pod-to-pod traffic can be encrypted and authenticated with Contrast's workload certificates. - -### 🔍 Everything verifiable - -* Workload attestation based on the identity of your container and the remote-attestation feature of [Confidential Containers](https://github.com/confidential-containers) -* "Whole deployment" attestation based on Contrast's [Coordinator attestation service](#the-contrast-coordinator) -* Runtime environment integrity verification based runtime policies -* Kata micro-VMs and single workload isolation provide a minimal Trusted Computing Base (TCB) - -### 🏝️ Everything isolated - -* Runtime policies enforce strict isolation of your containers from the Kubernetes layer and the infrastructure. -* Pod isolation: Pods are isolated from each other. -* Namespace isolation: Contrast can be deployed independently in multiple namespaces. - -### 🧩 Lightweight and easy to use - -* Install in Kubernetes cluster as a day-2 operation. -* Compatible with managed Kubernetes. -* Minimal DevOps involvement. -* Simple CLI tool to get started. - -## Components - -### The Contrast Coordinator - -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's 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's 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 YAML into Rego policy language of OPA. -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 YAML into Rego policy language of OPA. - -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 hasn't 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 an init container before your workload is started. - -## Current limitations - -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 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 is only available for Linux (mostly because upstream dependencies aren't available for other platforms) - -## Upcoming Contrast features - -- Transparent service mesh (apps can currently use mTLS with Coordinator certs for secure communication) -- Plugin for a key management service (KMS) for attestation/coordinator certificate-based key release -- High availability (distributed Contrast Coordinator)