diff --git a/content/en/docs/attestation/policies/_index.md b/content/en/docs/attestation/policies/_index.md index 35d71f8..c57d72f 100644 --- a/content/en/docs/attestation/policies/_index.md +++ b/content/en/docs/attestation/policies/_index.md @@ -17,32 +17,32 @@ Confidential Containers uses three types of policies to secure workloads at diff | Policy | Where Enforced | Purpose | Where it is set | |--------|----------------|---------|------------| -| **Agent Policy** | Inside the TEE by Kata Agent | Controls what operations the agent can perform | [Init-Data](../../features/initdata/)) | -| **Resource Policy** | By Trustee KBS | Controls which secrets are released to which workloads | KBS (via KBS Client or config file) | -| **Attestation Policy** | By Trustee AS | Defines how hardware evidence is evaluated | AS (via KBS Client or config file) | +| **Kata Agent Policy** | Inside the TEE by Kata Agent | Controls what operations the agent can perform | [Init-Data](../../features/initdata/)) | +| **KBS Resource Policy** | By Trustee KBS | Controls which secrets are released to which workloads | KBS (via KBS Client or config file) | +| **Attestation Service Policy** | By Trustee AS | Defines how hardware evidence is evaluated | AS (via KBS Client or config file) | -This page focuses on the **two policies managed by Trustee**: resource policies and attestation policies. -For information about agent policies, which control the Kata agent's behavior inside the TEE, +This page focuses on the **two policies managed by Trustee**: KBS resource policies and attestation service policies. +For information about kata agent policies, which control the Kata agent's behavior inside the TEE, see the [Init-Data feature documentation](../../features/initdata/#agent-policy-overview). ### How Policies Work Together -While agent policies are not managed by Trustee, they are cryptographically linked to the attestation process: +While kata agent policies are not managed by Trustee, they are cryptographically linked to the attestation process: -1. **Agent policies** are delivered via Init-Data, which is hashed and measured into the TEE's hardware evidence -2. **Attestation policies** evaluate this hardware evidence to generate an attestation token -3. **Resource policies** can check the Init-Data hash (containing the agent policy) in the attestation token before releasing secrets +1. **Kata agent policies** are delivered via Init-Data, which is hashed and measured into the TEE's hardware evidence +2. **Attestation service policies** evaluate this hardware evidence to generate an attestation token +3. **KBS resource policies** can check the Init-Data hash (containing the kata agent policy) in the attestation token before releasing secrets In fact, resource policies can even check individual fields of the Init-Data claims see [Trustee docs](https://github.com/confidential-containers/trustee/blob/main/attestation-service/docs/attestation_token.md) -This ensures that even though Trustee doesn't manage agent policies directly, it can verify that the correct agent policy was applied to a workload before granting access to secrets. +This ensures that even though Trustee doesn't manage kata agent policies directly, it can verify that the correct kata agent policy was applied to a workload before granting access to secrets. ## Trustee Policies -Trustee manages two different policies that govern when secrets are released: resource policies and attestation policies. These serve distinct purposes. +Trustee manages two different policies that govern when secrets are released: KBS resource policies and attestation service policies. These serve distinct purposes. -Resource policies control which secrets are released and are generally scoped to the workload. -Attestation policies define how TCB claims are compared to reference values to determine +KBS resource policies control which secrets are released and are generally scoped to the workload. +Attestation service policies define how TCB claims are compared to reference values to determine if the enclave is in a valid state. Generally this policy reflects the enclave boot flow. Both policies use OPA. @@ -55,17 +55,17 @@ kbs-client --url config \ --policy-file ``` -The attestation policy is set in a similar manner. +The attestation service policy is set in a similar manner. ```bash kbs-client --url config \ --auth-private-key set-attestation-policy \ --policy-file ``` -## Resource Policies +## KBS Resource Policies -Resource policies, also known as KBS Policies, control whether a resource is released to a guest. -The input to the resource policies is the URI of the resource that is being requested and the +KBS resource policies, also known as KBS Policies, control whether a resource is released to a guest. +The input to the KBS resource policies is the URI of the resource that is being requested and the attestation token which was generated by attestation service for the guest making the request. ### Basic Policies @@ -88,14 +88,14 @@ default allow = true ``` Allowing all requests is generally not secure. -By default the resource policy allows all requests as long as the evidence +By default the KBS resource policy allows all requests as long as the evidence does not come from the sample attester. This means that some TEE must have been used to request the secret although it makes no guarantees about the TCB. If you are testing Trustee without a TEE (with the sample evidence) the default policy will block all of your requests. -Usually the policy should check if the attestation token represents a valid TCB. +Usually the KBS resource policy should check if the attestation token represents a valid TCB. The attestation token is an EAR token, so we can check if it is contraindicated. The `status` field in the EAR token represents an AR4SI Trustworthiness Tier. There are 4 tiers: Contraindicated, Warning, Affirming, @@ -143,7 +143,7 @@ These are `instance_identity`, `configuration`, `executables`, `file_system`, `h Not all of these vectors is in scope for confidential containers. See the next section for how these vectors are calculated. -A resource policy can check each of these values. +A KBS resource policy can check each of these values. For instance this policy builds on the previous one to make sure that in addition to not being contraindicated, the executables trust vector has a particular claim. ```rego @@ -164,7 +164,7 @@ For instance, for the `executables` trust claim the value 2 stands for "Only a recognized genuine set of approved executables have been loaded during the boot process." A full listing of trust vectors and their meanings can be found [here](https://datatracker.ietf.org/doc/draft-ietf-rats-ar4si/). -The policy also takes the requested resource URI as input so the policy can have different behavior depending +The policy also takes the requested resource URI as input so the KBS resource policy can have different behavior depending on which resource is requested. Here is a basic policy checking which resource is requested. @@ -220,21 +220,21 @@ Accessing init-data from policies can be extremely powerful because users can sp This allows users to create their own schemes for identifying guests. For instance, the init-data could be used to assign each guest a UUID or a workload class. -## Attestation Policies +## Attestation Service Policies -Attestation policies are what the attestation service uses to calculate EAR trust vectors +Attestation service policies are what the attestation service uses to calculate EAR trust vectors based on the TCB claims extracted from the hardware evidence by the verifiers. -Essentially the AS policy defines which parts of the evidence are important +Essentially the attestation service policy defines which parts of the evidence are important and how the evidence should be compared to reference values. -The default attestation policy already defines this relationship for TDX and SNP guests +The default attestation service policy already defines this relationship for TDX and SNP guests booted by the Kata shim and running Kata guests. If you are using Confidential Containers with these platforms you probably do not need to change this policy. -If you are using Trustee to boot different types of guests, you might want to adjust the AS policy +If you are using Trustee to boot different types of guests, you might want to adjust the attestation service policy to capture your TCB. -Either way, you'll need to provide the reference values that the policy expects. +Either way, you'll need to provide the reference values that the attestation service policy expects. Take a look at the [default CPU policy](https://github.com/confidential-containers/trustee/blob/main/attestation-service/src/ear_token/ear_default_policy_cpu.rego) to see which values are expected. You only need to provision the reference values for the platform that you are using. diff --git a/content/en/docs/getting-started/securing-workloads.md b/content/en/docs/getting-started/securing-workloads.md index 855e911..5ff8a0f 100644 --- a/content/en/docs/getting-started/securing-workloads.md +++ b/content/en/docs/getting-started/securing-workloads.md @@ -88,22 +88,29 @@ Confidential Containers uses **three types of policies** to protect your workloa | Policy Type | Where Enforced | What It Controls | Configured Via | |------------|----------------|------------------|----------------| -| **Agent Policy** | Inside the TEE by Kata Agent | Which operations the agent can perform (create containers, exec into pods, etc.) | Pod annotation with init-data | -| **Resource Policy** | By Trustee KBS | Which secrets are released to which workloads | KBS Client or Trustee Operator | -| **Attestation Policy** | By Trustee AS | How hardware evidence is evaluated (what TCB is acceptable) | KBS Client or Trustee Operator | +| **Kata Agent Policy** | Inside the TEE by Kata Agent | Which operations the agent can perform (create containers, exec into pods, etc.) | Pod annotation with init-data | +| **KBS Resource Policy** | By Trustee KBS | Which secrets are released to which workloads | KBS Client or Trustee Operator | +| **Attestation Service Policy** | By Trustee AS | How hardware evidence is evaluated (what TCB is acceptable) | KBS Client or Trustee Operator | -{{< figure src="/img/CoCoMeasurementsAndConfig.svg" alt="Diagram showing how agent policy, resource policy, and attestation policy interact in the attestation flow" >}} +{{< figure src="/img/CoCoMeasurementsAndConfig.svg" alt="Diagram showing how kata agent policy, KBS resource policy, and attestation service policy interact in the attestation flow" >}} -### 1. Agent Policy (Inside the TEE) +{{% alert title="Note" color="info" %}} +The diagram shows example Rego file names. +Those names are arbitrary. +Policies are always supplied by path via command line (e.g. `kbs-client ... set-resource-policy --policy-file `) or config, +and the services use the file *content*, not the filename. +{{% /alert %}} + +### 1. Kata Agent Policy (Inside the TEE) -The agent policy controls what operations the Kata agent can perform inside your TEE. This is your **first line of defense** against malicious or compromised Kubernetes control planes. +The kata agent policy controls what operations the Kata agent can perform inside your TEE. This is your **first line of defense** against malicious or compromised Kubernetes control planes. **Example use cases:** - Prevent `kubectl exec` into production pods - Restrict which container images can be launched - Control which commands can be executed -**Quick example** of a restrictive agent policy: +**Quick example** of a restrictive kata agent policy: ```rego package agent_policy import rego.v1 @@ -117,24 +124,24 @@ CreateContainerRequest if { } ``` -Agent policies get embedded in the Init-Data configuration file. That file provides additional configuration like where to look for Trustee. +Kata agent policies get embedded in the Init-Data configuration file. That file provides additional configuration like where to look for Trustee. **Learn more:** [Agent Policies and Init-Data](../../features/initdata/) -### 2. Resource Policy (At the KBS) +### 2. KBS Resource Policy (At the KBS) -Resource policies control which secrets are released under what conditions. They inspect the attestation token from your workload to make decisions. +KBS resource policies control which secrets are released under what conditions. They inspect the attestation token from your workload to make decisions. **Example use cases:** -- Verify the workload is using a specific agent policy (via Init-Data hash) +- Verify the workload is using a specific kata agent policy (via Init-Data hash) - Only release database credentials to attesting TDX guests - Require specific trust levels (affirming vs contraindicated) - Different secrets for different platforms (TDX vs SNP) **Example: Checking Init-Data hash** -When you provide Init-Data in your pod (with an agent policy), the Attestation Service verifies it and includes the hash in the token. Your resource policy can verify the specific Init-Data hash to ensure the exact agent policy was used: +When you provide Init-Data in your pod (with a kata agent policy), the Attestation Service verifies it and includes the hash in the token. Your KBS resource policy can verify the specific Init-Data hash to ensure the exact kata agent policy was used: ```rego package policy @@ -145,7 +152,7 @@ default allow = false # Only release secrets to workloads with the expected Init-Data hash allow if { input["submods"]["cpu0"]["ear.status"] == "affirming" - # Verify the specific Init-Data hash (includes agent policy + config) + # Verify the specific Init-Data hash (includes kata agent policy + config) input["submods"]["cpu0"]["ear.veraison.annotated-evidence"]["init_data"] == "expected-hash-here" } ``` @@ -158,18 +165,18 @@ a command line you could run: sha384sum initdata.toml ``` -**Learn more:** [Resource Policies](../../attestation/policies/#resource-policies) +**Learn more:** [KBS Resource Policies](../../attestation/policies/#kbs-resource-policies) -### 3. Attestation Policy (At the Attestation Service) +### 3. Attestation Service Policy (At the Attestation Service) -Attestation policies define **how hardware evidence is evaluated** - what measurements are acceptable, which reference values to compare against, and how to calculate trust vectors. +Attestation service policies define **how hardware evidence is evaluated** - what measurements are acceptable, which reference values to compare against, and how to calculate trust vectors. **Example use cases:** - Define acceptable firmware versions - Specify required security levels for different workloads - Map hardware measurements to trust claims -**Learn more:** [Attestation Policies](../../attestation/policies/#attestation-policies) +**Learn more:** [Attestation Service Policies](../../attestation/policies/#attestation-service-policies) {{% alert title="Default Policies" color="success" %}} CoCo ships with sensible default attestation policies for TDX and SNP. For most users, you only need to provide reference values - the policy is already configured appropriately. @@ -185,8 +192,8 @@ Once you've configured the basics, explore these features for enhanced security: Before deploying to production, ensure you've addressed: - [ ] Selected the correct runtime class for your hardware -- [ ] Generated and embedded an agent policy appropriate for your workload -- [ ] Configured resource policies in your KBS +- [ ] Generated and embedded a kata agent policy appropriate for your workload +- [ ] Configured KBS resource policies in your KBS - [ ] Provisioned reference values to the attestation service ## Next Steps diff --git a/static/img/CoCoMeasurementsAndConfig.svg b/static/img/CoCoMeasurementsAndConfig.svg index 5bd1217..d233fa8 100644 --- a/static/img/CoCoMeasurementsAndConfig.svg +++ b/static/img/CoCoMeasurementsAndConfig.svg @@ -1 +1 @@ - \ No newline at end of file +Kata Agentpolicy.regoKBS Resource policy.regoAttestation Service policy.regoinitdata.tomlpod.yamlKBS ConfighashAS Configpath || cliembedembedpath || cli \ No newline at end of file