From 7d28708956d2465ea801f7257d305e4019755699 Mon Sep 17 00:00:00 2001 From: Maddy Underwood <167196745+madeline-underwood@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:15:13 +0000 Subject: [PATCH 1/4] Content development --- .../cca-trustee/_index.md | 77 +++++----- .../cca-trustee/cca-trustee.md | 139 +++++++----------- .../cca-trustee/flow.md | 101 ++++++------- 3 files changed, 132 insertions(+), 185 deletions(-) diff --git a/content/learning-paths/servers-and-cloud-computing/cca-trustee/_index.md b/content/learning-paths/servers-and-cloud-computing/cca-trustee/_index.md index d0afe5fdc3..f110468197 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-trustee/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-trustee/_index.md @@ -1,62 +1,57 @@ --- -title: Run an end-to-end Attestation Flow with Arm CCA and Trustee - -draft: true -cascade: - draft: true - +title: Run an end-to-end attestation flow with Arm CCA and Trustee + minutes_to_complete: 60 -who_is_this_for: This Learning Path is for software developers who want to learn how Trustee services can be used to run an end-to-end attestation flow with Arm's Confidential Computing Architecture (CCA). +who_is_this_for: This Learning Path is for software developers who want to run an end-to-end attestation flow using Arm Confidential Compute Architecture (CCA) and Trustee services. learning_objectives: - - Describe how you can use attestation with Arm's Confidential Computing Architecture (CCA) and Trustee services. - - Deploy a simple workload in a CCA realm on an Armv9-A AEM Base Fixed Virtual Platform (FVP) that has support for RME extensions. - - Connect the workload with Trustee services to create an end-to-end example that uses attestation to unlock the confidential processing of data. + - Describe how you can use attestation with Arm's Confidential Computing Architecture (CCA) and Trustee services + - Launch a CCA realm and run a sample workload on an Armv9-A AEM Base Fixed Virtual Platform (FVP) with Realm Management Extension (RME) support + - Connect the workload with Trustee services to create an end-to-end example that uses attestation to unlock the confidential processing of data prerequisites: - - An AArch64 or x86_64 computer running Linux or MacOS. You can use cloud instances, see this list of [Arm cloud service providers](/learning-paths/servers-and-cloud-computing/csp/). - - Completion of the [Get Started with CCA Attestation and Veraison](/learning-paths/servers-and-cloud-computing/cca-veraison) Learning Path. - - Completion of the [Run an end-to-end Attestation Flow with Arm CCA](/learning-paths/servers-and-cloud-computing/cca-essentials/) Learning Path. + - An AArch64 or x86_64 computer running Linux or macOS. You can use cloud instances; see this list of [Arm cloud service providers](/learning-paths/servers-and-cloud-computing/csp/) + - Completion of the [Get started with CCA attestation and Veraison](/learning-paths/servers-and-cloud-computing/cca-veraison) Learning Path + - Completion of the [Run an end-to-end attestation flow with Arm CCA](/learning-paths/servers-and-cloud-computing/cca-essentials/) Learning Path author: - - Anton Antonov + - Anton Antonov ### Tags skilllevels: Advanced subjects: Performance and Architecture armips: - - Neoverse - - Cortex-A + - Neoverse + - Cortex-A operatingsystems: - - Linux - - MacOS + - Linux + - macOS tools_software_languages: - - FVP - - RME - - CCA - - Docker - - Veraison - - Trustee + - FVP + - RME + - CCA + - Docker + - Veraison + - Trustee further_reading: - - resource: - title: Arm Confidential Compute Architecture - link: https://www.arm.com/architecture/security-features/arm-confidential-compute-architecture - type: website - - resource: - title: Arm Confidential Compute Architecture open source enablement - link: https://www.youtube.com/watch?v=JXrNkYysuXw - type: video - - resource: - title: Learn the architecture - Realm Management Extension - link: https://developer.arm.com/documentation/den0126 - type: documentation - - resource: - title: Realm Management Monitor specification - link: https://developer.arm.com/documentation/den0137/latest/ - type: documentation - + - resource: + title: Arm Confidential Compute Architecture + link: https://www.arm.com/architecture/security-features/arm-confidential-compute-architecture + type: website + - resource: + title: Arm Confidential Compute Architecture open-source enablement + link: https://www.youtube.com/watch?v=JXrNkYysuXw + type: video + - resource: + title: Learn the architecture - Realm Management Extension + link: https://developer.arm.com/documentation/den0126 + type: documentation + - resource: + title: Realm Management Monitor specification + link: https://developer.arm.com/documentation/den0137/latest/ + type: documentation ### FIXED, DO NOT MODIFY # ================================================================================ diff --git a/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md b/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md index 0eded26191..acadfc4f0c 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md @@ -1,6 +1,6 @@ --- # User change -title: "Overview of the Software Architecture" +title: "Overview of the software architecture" weight: 2 # 1 is first, 2 is second, etc. @@ -8,145 +8,106 @@ weight: 2 # 1 is first, 2 is second, etc. layout: "learningpathall" --- -## The role of Attestation -In this Learning Path, you will learn how attestation can control the release -of confidential data into a confidential Linux realm for processing. +## The role of attestation + +In this Learning Path, you will learn how attestation controls the release of confidential data into a confidential Linux realm for processing. The role of attestation is to assess whether the target compute environment offers a provable level of confidential isolation. In this Learning Path, the target compute environment is a Linux realm. The assessment of a provable -level of confidential isolation needs to occur before the realm can be trusted +level of confidential isolation must occur before the realm can be trusted to receive confidential data or algorithms. This use of attestation to judge the trustworthiness of a compute environment, before allowing it to do any processing, is a common practice in confidential computing. -## Understanding the key software components +## Key software components This Learning Path is similar to [Run an end-to-end Attestation Flow with Arm CCA](/learning-paths/servers-and-cloud-computing/cca-essentials/). -The main difference is that instead of KBS from the [Veraison](https://github.com/veraison) project you will use -the components implemented in the [confidential containers (CoCo)](https://github.com/confidential-containers) -to support the [IETF RATS model](https://datatracker.ietf.org/doc/rfc9334/) -(Remote ATtestation procedureS Architecture). The components include the Attestation Service (AS), -Key Broker Service (KBS), Reference Value Provider Service (RVPS), Attestation Agent (AA), and Confidential Data Hub (CDH). +The main difference is that, instead of the KBS from the [Veraison](https://github.com/veraison) project, you will use components implemented in the [Confidential Containers (CoCo)](https://github.com/confidential-containers) to support the [IETF RATS model](https://datatracker.ietf.org/doc/rfc9334/) (Remote ATtestation procedureS). These components include the Attestation Service (AS), Key Broker Service (KBS), Reference Value Provider Service (RVPS), Attestation Agent (AA), and Confidential Data Hub (CDH). The AS, KBS, and RVPS components are part of the [Trustee project](https://github.com/confidential-containers/trustee), whereas the AA and CDH are part of the [Guest Components](https://github.com/confidential-containers/guest-components) project in CoCo. -### RATS key components +## RATS roles -This is a list of components used in this Learning Path: +This Learning Path uses the following RATS roles: -- `Attester` - provides Evidence, which is evaluated and appraised to decide its - trustworthiness (for instance, a test to see whether it’s authorized to perform some action). - Evidence may include configuration data, measurements, telemetry, or inferences. -- `Verifier` - evaluates the validity of the evidence received from the attester - and produces attestation results, which are sent to the Relying party. - Attestation results typically include information regarding the Attester, - while the Verifier vouches for the validity of the results. -- `Relying party` - depends on the validity of information originating from - the attester for reliably applying an action. This information can come - from the verifier or directly through the attester. +- **Attester** – Provides evidence that is evaluated to decide trustworthiness (for example, whether it is authorized to perform an action). Evidence can include configuration data, measurements, telemetry, or inferences. +- **Verifier** – Evaluates the evidence from the Attester and produces attestation results that are sent to the Relying party. The Verifier vouches for the validity of those results. +- **Relying party** – Depends on the validity of information from the Attester (either directly or through the Verifier) to make an access or policy decision. -### Trustee components +## Trustee components -The Trustee project includes components deployed on a trusted side and used to verify -whether the remote workload is running in a trusted execution environment (TEE). -It also verifies that the remote environment uses the expected software and hardware versions. +Trustee components run on the trusted side and verify whether a remote workload is executing in a trusted execution environment (TEE) and using the expected software and hardware versions. -#### Key Broker Service (KBS) +## Key Broker Service (KBS) -The Key Broker Service (KBS) facilitates remote attestation and managing -and delivering secrets. Equating this to the RATS model, the KBS is the -`relying party` entity. The KBS, however, doesn’t validate the attestation evidence. -Instead, it uses the attestation service (AS) to verify the TEE evidence. +The KBS facilitates remote attestation and manages and delivers secrets. In RATS terms, the KBS is the **Relying party**. The KBS does not validate attestation evidence itself; it relies on the Attestation Service (AS) to verify the TEE evidence. -#### Attestation Service (AS) +## Attestation Service (AS) -The Attestation Service (AS) is responsible for validating the TEE evidence. -When mapped to the RATS model, the AS is the equivalent of the `verifier`. -The AS receives attestation evidence and returns an attestation token -containing the results of a two-step verification process. +The Attestation Service (AS) validates TEE evidence. In RATS terms, the AS is the **Verifier**. The AS receives attestation evidence and returns an attestation token containing the results of a two-step verification process. The following diagram shows the AS components: -![attestation-services](attestation-services.png "Attestation Service components") - -The AS runs the following verification process: +![Attestation Service components alt-text#center](attestation-services.png "Attestation Service components") -1. Verify the formatting and the origin of the evidence - for example, checking the signature of the evidence. - This is accomplished by one of the platform-specific Verifier Drivers. -2. Evaluate the claims provided in the evidence - for example, validating that the measurements are what the - client expects. This is done by a Policy Engine with help from the RVPS. +The AS performs this verification flow: -##### Verifier driver +1. **Verify format and origin of evidence** – For example, verify the evidence signature. This is handled by a platform-specific Verifier driver. +2. **Evaluate claims** – For example, validate that measurements match expected values. This is handled by the Policy engine, with RVPS support. -A verifier driver parses the attestation evidence provided by the hardware TEE. It performs the following tasks: +## Verifier driver -1. Verifies the hardware TEE signature of the TEE quote and report provided in the evidence -2. Receives the evidence and organizes the status into a JSON format to be returned +A Verifier driver parses the attestation evidence provided by the hardware TEE and: -In this Learning Path, the AS is configured to use an external CCA verifier. +- Verifies the hardware TEE signature of the quote and report included in the evidence. +- Normalizes the verified evidence into a JSON structure to be returned. -[Linaro](https://www.linaro.org) provides such an attestation verifier for use with pre-silicon Arm CCA platforms. -This verifier is built from the Open-Source [Veraison project](https://github.com/veraison). -You can learn more about Veraison and Linaro attestation verifier service in -[Get Started with CCA Attestation and Veraison](https://learn.arm.com/learning-paths/servers-and-cloud-computing/cca-veraison/) +In this Learning Path, the AS is configured to use an external CCA Verifier. -##### Policy Engine +[Linaro](https://www.linaro.org) provides an attestation Verifier for pre-silicon Arm CCA platforms. It is built from the open-source [Veraison](https://github.com/veraison) project. Learn more in +[Get Started with CCA Attestation and Veraison](https://learn.arm.com/learning-paths/servers-and-cloud-computing/cca-veraison/). -The AS allows users to upload their own policies when performing evidence verification. -When an attestation request is received by the AS, it uses a policy ID in the request -to decide which policies should be evaluated. -The results of all policies evaluated are included in the attestation response. +## Policy engine -In this Learning Path the AS attestation policy includes specific Arm CCA rules. +The AS lets you upload custom policies used during evidence verification. When the AS receives an attestation request, it uses the policy ID in the request to decide which policies to evaluate. The attestation response includes the results of all evaluated policies. -#### Reference Value Provider Service (RVPS) +In this Learning Path, the AS policy includes Arm CCA–specific rules. -The reference value provider service (RVPS) is a component in the AS responsible for verifying, -storing, and providing reference values. RVPS receives and verifies inputs from the software -supply chain, stores the measurement values, and generates reference value claims for the AS. -This operation is performed based on the evidence verified by the AS. +## Reference Value Provider Service (RVPS) +RVPS verifies, stores, and provides reference values. It receives inputs from the software supply chain, stores measurement values, and generates reference value claims for the AS, based on evidence verified by the AS. -### Guest components +## Guest components -The guest components are the services/tools that run inside the realm (TEE). -When mapped to the RATS model, these components are the equivalent of the `Attester`. +Guest components run inside the realm (TEE). In RATS terms, these components act as the **Attester**. For simplicity instead of Attestation Agent (AA) and Confidential Data Hub (CDH) -you will use [KBS Client Tool](https://github.com/confidential-containers/trustee/tree/main/tools/kbs-client) +you will use [KBS Client Tool](https://github.com/confidential-containers/trustee/tree/main/tools/kbs-client). This is a simple client for the KBS that facilitates basic attestation flows. You will run this tool inside of a realm to make requests for an attestation result token (EAR) and a secret. The client tool can also be used to provision the KBS/AS with resources and policies. -KBS Client connects to the KBS in order to perform attestation. To prove the trustworthiness of the environment -KBS Client sends the evidence (claims) from the TEE in the form of a CCA attestation token. -You can learn more about CCA attestation tokens in -[Get Started with CCA Attestation and Veraison](https://learn.arm.com/learning-paths/servers-and-cloud-computing/cca-veraison/) +To prove the environment’s trustworthiness, the KBS Client sends CCA attestation evidence (a CCA attestation token) to the KBS. Learn more about CCA attestation tokens in +[Get Started with CCA Attestation and Veraison](https://learn.arm.com/learning-paths/servers-and-cloud-computing/cca-veraison/). + +For convenience, Trustee services and the client software are packaged in Docker containers, which you can run on any suitable AArch64 or x86_64 development host. Because the client runs in a realm, it uses the Fixed Virtual Platform (FVP) and the reference software stack for Arm CCA. If you are new to running applications in realms with FVP, see +[Run an application in a Realm using the Arm Confidential Computing Architecture (CCA)](/learning-paths/servers-and-cloud-computing/cca-container). -For convenience, Trustee services and the client software are packaged in -docker containers, which you can execute on any suitable AArch64 or x86_64 -development machine. Since the client software runs in a realm, it makes use -of the Fixed Virtual Platform (FVP) and the reference software stack for Arm CCA. -If you have not yet familiarized yourself with running applications in realms using -FVP and the reference software stack, see the -[Run an application in a Realm using the Arm Confidential Computing Architecture (CCA)](/learning-paths/servers-and-cloud-computing/cca-container) -Learning Path. +When the AS receives an attestation token from the realm using the KBS, it: -When the AS receives an attestation token from the realm via KBS: -- it calls an external CCA verifier (the Linaro attestation verifier service) to obtain an attestation result. -- the external CCA verifier checks the token's cryptographic signature, - verifies that it denotes a confidential computing platform and provides an attestation result. -- it also checks the token evidences against its own attestation policies and updates attestation result status and trustworthiness vectors. +- Calls an external CCA Verifier (the Linaro attestation Verifier service) to obtain an attestation result. +- Checks the token’s cryptographic signature and confirms that it represents a confidential computing platform. +- Evaluates evidence in the token against its policies and updates the attestation result and trustworthiness vectors. -When asked for a resource the KBS uses the attestation result to decide whether to release the secrets into the realm for processing. +When a resource is requested, the KBS uses the attestation result to decide whether to release secrets to the realm for processing. -Figure 1 demonstrates the software architecture that you will construct to run the attestation example. +This diagram shows the software architecture you will construct to run the attestation example: -![cca-trustee](trustee.png "Figure 1: Software architecture for running attestation.") +![Software architecture for running attestation alt-text#center](trustee.png "Software architecture for running attestation") -You can now proceed to the next section to run the end-to-end attestation example with the software components and architecture as described here. +Proceed to the next section to run the end-to-end attestation example using the components and architecture described here. diff --git a/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md b/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md index 63c5b033a7..f133736594 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md @@ -8,20 +8,21 @@ weight: 3 # 1 is first, 2 is second, etc. layout: "learningpathall" --- -### Run Trustee Services +## Run Trustee services -#### Prerequisites +### Prerequisites -Install docker. For example, on your Ubuntu 24.04 LTS host machine, first set up Docker's apt repository: -``` bash +Install Docker. On Ubuntu 24.04 LTS, set up Docker’s APT repository: + +```bash # Add Docker's official GPG key: sudo apt-get update -sudo apt-get install ca-certificates curl +sudo apt-get install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc -# Add the repository to Apt sources: +# Add the repository to APT sources: echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \ @@ -29,33 +30,37 @@ echo \ sudo apt-get update ``` -Install git and docker packages: -``` bash -sudo apt-get install git docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +Install Git and Docker packages: +``` +sudo apt-get install -y git docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` -Add your user name to the docker group: +Add your user name to the docker group (open a new shell after this so the change takes effect): ``` bash sudo usermod -aG docker $USER newgrp docker ``` -#### Start Trustee Services docker containers +## Start Trustee services containers Clone the `cca-trustee` repository: ``` bash git clone https://github.com/ArmDeveloperEcosystem/cca-trustee.git ``` -This repository contains configuration files used for running Trustee services docker containers with CCA attestation support as a simple cluster. -The config files are based on the recommended configurations from [KBS Cluster](https://github.com/confidential-containers/trustee/blob/main/kbs/docs/cluster.md) +This repository contains configuration to run Trustee services (KBS, AS, RVPS) with CCA attestation support as a simple cluster. The configuration is based on the recommended settings from [KBS Cluster](https://github.com/confidential-containers/trustee/blob/main/kbs/docs/cluster.md). + +Additional Learning Path–specific changes include: + +- External Linaro CCA verifier in the AS configuration + +- Attestation policy with CCA rules + +- An “affirming” resource policy -In addition to the recommended configuration, the following changes were also made for this Learning Path: -- Included the external Linaro CCA verifier into AS configuration -- Included an attestation policy with CCA rules -- Defined an "affirming" resource policy -- Created a secret demo message. -- Defined a docker network shared by all containers in this demo. +- A demo secret message + +- A shared Docker network for all containers in this demo Go into the `cca-trustee` directory and start the Trustee services docker containers (as detached services): ``` bash { output_lines = "3-9" } @@ -76,13 +81,11 @@ docker compose logs ``` Where `service` is either `as`,`kbs` or `rvps`. -### Launch a CCA Realm with FVP +## Launch a CCA Realm with FVP -With the Trustee Services running in one terminal, -open up a new terminal in which you will run CCA attestations. +With the Trustee Services running in one terminal, open up a new terminal in which you will run CCA attestations. -Pull the docker image with the pre-built FVP, -and then run the container connected to the same docker network: +Pull the docker image with the pre-built FVP, and then run the container connected to the same docker network: ```bash docker pull armswdev/cca-learning-path:cca-simulation-v2 @@ -91,16 +94,15 @@ docker pull armswdev/cca-learning-path:cca-simulation-v2 docker run --rm -it --network cca-trustee armswdev/cca-learning-path:cca-simulation-v2 ``` -Within your running container, -launch the `run-cca-fvp.sh` script to run the Arm CCA pre-built binaries on the FVP: +Within your running container, launch the `run-cca-fvp.sh` script to run the Arm CCA pre-built binaries on the FVP: ```bash ./run-cca-fvp.sh ``` -The `run-cca-fvp.sh` script uses the screen command to connect to the different UARTs in the FVP. +The `run-cca-fvp.sh` script uses the `screen` command to connect to the different UARTs in the FVP. -You should see the host Linux kernel boot on your terminal. You will be prompted to log in to the host. +When the host Linux boots, log in: Enter root as the username: ```output @@ -120,10 +122,7 @@ cd /cca You should see the realm boot. -The `realm` will take some time to boot, please be patient. -After boot up, you will be prompted to log in at the guest Linux prompt. - -Use root again as the username: +After the realm boots, log in, using the root again as the username: ```output @@ -132,12 +131,9 @@ realm login: root (realm) # ``` -### Try to use attestation to request a secret +## Request a secret using attestation -In this step, you will go through the process of using attestation to request -a secret from the KBS. This will not work on the first attempt. -But don't worry. You will learn why that is the case, and how to rectify the problem. -You will have a better understanding of the attestation process as a result. +This first attempt intentionally fails so you can see why and how attestation policy gates secret release. Change directory to `/cca` and use `openssl` to create a realm RSA key: ```bash @@ -147,15 +143,15 @@ openssl genrsa -traditional -out realm.key Run the attestation command and save the EAT Attestation Result (EAR) message in JWT (JSON Web Token) format in a file named `ear.jwt`: ```bash -./kbs-client --url http://kbs:8080 attest --tee-key-file realm.key >ear.jwt +./kbs-client --url http://kbs:8080 attest --tee-key-file realm.key > ear.jwt ``` -Now try to request a secret demo message using the attestation result: -```bash -./kbs-client --url http://kbs:8080 get-resource \ +Request the demo secret with that EAR: +```bash./kbs-client --url http://kbs:8080 get-resource \ --tee-key-file realm.key --attestation-token ear.jwt \ --path "cca-trustee/demo-message/message.txt" -``` +``` + The request will fail with `Access denied by policy` and `Token Verifier` errors: ```output @@ -174,14 +170,9 @@ The request will fail with `Access denied by policy` and `Token Verifier` errors Error: request unauthorized ``` -Proceed to the next step to understand why the KBS did not grant access -to the requested secret, and how to resolve the problem. - -#### Evaluate the Attestation Result +## Evaluate the Attestation Result -In the previous step, the KBS failed to provide the requested secret. -To understand why this happened, you need to learn more about how -the attestation result is used to evaluate the trustworthiness of a CCA realm. +In the previous step, the KBS failed to provide the requested secret. To understand why this happened, you need to learn more about how the attestation result is used to evaluate the trustworthiness of a CCA realm. In this step, you will examine the attestation result more closely. The following command will use the `arc` tool to verify the cryptographic signature on the attestation result and display the result in a human-readable format: @@ -191,7 +182,7 @@ The following command will use the `arc` tool to verify the cryptographic signat ``` {{% notice EAR expiry note %}} -The EAR message produced by Trustee AS in this Learning Path demo is valid for 30 minutes. +The EAR is valid for 30 minutes. If it expires, re-run the attestation command to generate a fresh token. If you spend more time on analyzing the message you will start seeing errors from `arc verify` command: ``` output @@ -207,7 +198,7 @@ The `arc verify` command produces quite a lot of output. However, the main part is the CCA attestation token that is similar to the one you inspected in [Get Started with CCA Attestation and Veraison](/learning-paths/servers-and-cloud-computing/cca-veraison) Learning Path. -The most interesting part of the output is towards the bottom, and should look like this: +Check the trustworthiness vectors near the end of the output. Example: ```output [trustworthiness vectors] @@ -226,7 +217,7 @@ This part of the output shows how the attestation service has compared the attes These comparisons are known as "trustworthiness vectors". It also shows the conclusions that were drawn from that comparison. -Please notice these two trustworthiness vectors in the result: +Note these two trustworthiness vectors in the result: - __Hardware [affirming]__. Evidence in the attestation token shows a good match against the expectations of CCA platform. - __Executables [warning]__. Attestation token does not show a good match against the expectations of a recognized genuine set of approved executables have been loaded during the boot process. @@ -236,13 +227,13 @@ You can also check the status of the EAR: "ear.status": "warning", ``` -The warning status is the reason why the KBS chose not to grant access +The warning status is the reason why the KBS does not grant access to the secret that you requested in the earlier step. It has not concluded that the realm is trustworthy. But this is simply because you have not supplied an expected reference measurement for the realm. You will do this in the next step. -### Endorse Realm Initial Measurement (RIM) +## Endorse Realm Initial Measurement (RIM) For a successful attestation of your CCA real you need to provide the Trustee Reference Values Provider Service (RVPS) with a known good reference value. @@ -271,7 +262,7 @@ In the terminal where you started Trustee services, run `endorse-rim.sh` script Reference Values Updated ``` -### Re-run attestation and request a secret +## Re-run attestation and request a secret In the realm terminal re-run the attestation command: ```bash From 19868c3f213972280b3dbcc6d3d1c911666ea0d3 Mon Sep 17 00:00:00 2001 From: Maddy Underwood <167196745+madeline-underwood@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:35:22 +0000 Subject: [PATCH 2/4] Refining --- .../cca-trustee/cca-trustee.md | 7 +++---- .../servers-and-cloud-computing/cca-trustee/flow.md | 11 ++++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md b/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md index acadfc4f0c..d5dbb27ca0 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md @@ -25,7 +25,7 @@ processing, is a common practice in confidential computing. This Learning Path is similar to [Run an end-to-end Attestation Flow with Arm CCA](/learning-paths/servers-and-cloud-computing/cca-essentials/). -The main difference is that, instead of the KBS from the [Veraison](https://github.com/veraison) project, you will use components implemented in the [Confidential Containers (CoCo)](https://github.com/confidential-containers) to support the [IETF RATS model](https://datatracker.ietf.org/doc/rfc9334/) (Remote ATtestation procedureS). These components include the Attestation Service (AS), Key Broker Service (KBS), Reference Value Provider Service (RVPS), Attestation Agent (AA), and Confidential Data Hub (CDH). +The main difference is that, instead of the KBS from the [Veraison](https://github.com/veraison) project, you will use components implemented in the [Confidential Containers (CoCo) Project](https://github.com/confidential-containers) to support the [IETF RATS model](https://datatracker.ietf.org/doc/rfc9334/) (Remote ATtestation procedureS). These components include the Attestation Service (AS), Key Broker Service (KBS), Reference Value Provider Service (RVPS), Attestation Agent (AA), and Confidential Data Hub (CDH). The AS, KBS, and RVPS components are part of the [Trustee project](https://github.com/confidential-containers/trustee), whereas the AA and CDH are part of the [Guest Components](https://github.com/confidential-containers/guest-components) project in CoCo. @@ -84,11 +84,10 @@ RVPS verifies, stores, and provides reference values. It receives inputs from th Guest components run inside the realm (TEE). In RATS terms, these components act as the **Attester**. -For simplicity instead of Attestation Agent (AA) and Confidential Data Hub (CDH) -you will use [KBS Client Tool](https://github.com/confidential-containers/trustee/tree/main/tools/kbs-client). +For simplicity, instead of Attestation Agent (AA) and Confidential Data Hub (CDH), you will use the [KBS Client Tool](https://github.com/confidential-containers/trustee/tree/main/tools/kbs-client). This is a simple client for the KBS that facilitates basic attestation flows. -You will run this tool inside of a realm to make requests for an attestation result token (EAR) and a secret. +You will run this tool in a realm to make requests for an attestation result token (EAR) and a secret. The client tool can also be used to provision the KBS/AS with resources and policies. diff --git a/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md b/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md index f133736594..bee5e5ed54 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md @@ -7,10 +7,10 @@ weight: 3 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- +## Overview +In this section you’ll run the **Trustee services** (AS, KBS, RVPS), launch a **CCA realm** on **Arm FVP**, generate attestation evidence, and request a secret. You’ll intentionally fail the first request to see how **attestation policy** gates secret release, then **endorse the realm initial measurement (RIM)**, re-attest, and successfully retrieve the secret. -## Run Trustee services - -### Prerequisites +## Install dependencies Install Docker. On Ubuntu 24.04 LTS, set up Docker’s APT repository: @@ -75,7 +75,7 @@ docker compose up -d ✔ Container cca-trustee-kbs-client-1 Started ``` -While running the demo you can also check logs of the Trustee services in this termimal: +While running the demo you can also check logs of the Trustee services in this terminal: ``` bash docker compose logs ``` @@ -147,6 +147,7 @@ Run the attestation command and save the EAT Attestation Result (EAR) message in ``` Request the demo secret with that EAR: + ```bash./kbs-client --url http://kbs:8080 get-resource \ --tee-key-file realm.key --attestation-token ear.jwt \ --path "cca-trustee/demo-message/message.txt" @@ -276,7 +277,7 @@ Verify that the new EAR now contains `affirming` status: "ear.status": "affirming", ``` -and `affirming` result for the `Executables` trustworthness vector: +and `affirming` result for the `Executables` trustworthiness vector: ```bash { output_lines = "2-11" } ./arc verify ear.jwt |grep -A10 "trustworthiness vectors" [trustworthiness vectors] From 0017b221c66a002d3d24e67aa76d533fbe09180f Mon Sep 17 00:00:00 2001 From: Maddy Underwood <167196745+madeline-underwood@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:40:33 +0000 Subject: [PATCH 3/4] Final --- .../servers-and-cloud-computing/cca-trustee/flow.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md b/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md index bee5e5ed54..7b7bb2cb45 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md @@ -171,7 +171,7 @@ The request will fail with `Access denied by policy` and `Token Verifier` errors Error: request unauthorized ``` -## Evaluate the Attestation Result +## Evaluate the Attestation result In the previous step, the KBS failed to provide the requested secret. To understand why this happened, you need to learn more about how the attestation result is used to evaluate the trustworthiness of a CCA realm. In this step, you will examine the attestation result more closely. @@ -190,16 +190,15 @@ If you spend more time on analyzing the message you will start seeing errors fro Using JWK key from JWT header Error: verifying signed EAR from "ear.jwt" using "JWK header" key: failed verifying JWT message: jwt.Parse: failed to parse token: jwt.Validate: validation failed: "exp" not satisfied: token is expired ``` - -Please obtain a new EAR message by re-running the attestation command. {{% /notice %}} The `arc verify` command produces quite a lot of output. + However, the main part is the CCA attestation token that is similar to the one you inspected in [Get Started with CCA Attestation and Veraison](/learning-paths/servers-and-cloud-computing/cca-veraison) Learning Path. -Check the trustworthiness vectors near the end of the output. Example: +Check the trustworthiness vectors near the end of the output: ```output [trustworthiness vectors] @@ -214,9 +213,7 @@ Storage Opaque [none]: no claim being made Sourced Data [none]: no claim being made ``` -This part of the output shows how the attestation service has compared the attestation token against its expectations of a trustworthy system. -These comparisons are known as "trustworthiness vectors". -It also shows the conclusions that were drawn from that comparison. +This part of the output shows how the attestation service has compared the attestation token against its expectations of a trustworthy system. These comparisons are known as *trustworthiness vectors"*. It also shows the conclusions that were drawn from that comparison. Note these two trustworthiness vectors in the result: - __Hardware [affirming]__. Evidence in the attestation token shows a good match against the expectations of CCA platform. From d8f5816601fa0ccccd6de40d1a356a4e955dc5fe Mon Sep 17 00:00:00 2001 From: Maddy Underwood <167196745+madeline-underwood@users.noreply.github.com> Date: Tue, 9 Sep 2025 06:18:06 +0000 Subject: [PATCH 4/4] Final corrections --- .../cca-trustee/_index.md | 4 +-- .../cca-trustee/cca-trustee.md | 30 +++++++------------ .../cca-trustee/flow.md | 15 +++++----- 3 files changed, 21 insertions(+), 28 deletions(-) diff --git a/content/learning-paths/servers-and-cloud-computing/cca-trustee/_index.md b/content/learning-paths/servers-and-cloud-computing/cca-trustee/_index.md index f110468197..2228ac69df 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-trustee/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-trustee/_index.md @@ -7,11 +7,11 @@ who_is_this_for: This Learning Path is for software developers who want to run a learning_objectives: - Describe how you can use attestation with Arm's Confidential Computing Architecture (CCA) and Trustee services - - Launch a CCA realm and run a sample workload on an Armv9-A AEM Base Fixed Virtual Platform (FVP) with Realm Management Extension (RME) support + - Deploy a simple workload in a CCA realm on an Armv9-A AEM Base Fixed Virtual Platform (FVP) that has support for RME extensions - Connect the workload with Trustee services to create an end-to-end example that uses attestation to unlock the confidential processing of data prerequisites: - - An AArch64 or x86_64 computer running Linux or macOS. You can use cloud instances; see this list of [Arm cloud service providers](/learning-paths/servers-and-cloud-computing/csp/) + - An AArch64 or x86_64 computer running Linux or macOS; you can use cloud instances - see the [Arm cloud service providers](/learning-paths/servers-and-cloud-computing/csp/) - Completion of the [Get started with CCA attestation and Veraison](/learning-paths/servers-and-cloud-computing/cca-veraison) Learning Path - Completion of the [Run an end-to-end attestation flow with Arm CCA](/learning-paths/servers-and-cloud-computing/cca-essentials/) Learning Path diff --git a/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md b/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md index d5dbb27ca0..d217544637 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-trustee/cca-trustee.md @@ -1,6 +1,6 @@ --- # User change -title: "Overview of the software architecture" +title: "Architecture overview for Arm CCA Attestation with Trustee" weight: 2 # 1 is first, 2 is second, etc. @@ -10,32 +10,24 @@ layout: "learningpathall" ## The role of attestation -In this Learning Path, you will learn how attestation controls the release of confidential data into a confidential Linux realm for processing. - -The role of attestation is to assess whether the target compute environment -offers a provable level of confidential isolation. In this Learning Path, -the target compute environment is a Linux realm. The assessment of a provable -level of confidential isolation must occur before the realm can be trusted -to receive confidential data or algorithms. This use of attestation to judge -the trustworthiness of a compute environment, before allowing it to do any -processing, is a common practice in confidential computing. +In this Learning Path, you will learn how attestation controls the release of confidential data into a confidential Linux realm for processing. The role of attestation is to assess whether the target compute environment offers a provable level of confidential isolation. In this Learning Path, +the target compute environment is a Linux realm. The assessment of a provable level of confidential isolation must occur before the realm can be trusted to receive confidential data or algorithms. This use of attestation to judge the trustworthiness of a compute environment, before allowing it to do any processing, is a common practice in confidential computing. ## Key software components This Learning Path is similar to -[Run an end-to-end Attestation Flow with Arm CCA](/learning-paths/servers-and-cloud-computing/cca-essentials/). - -The main difference is that, instead of the KBS from the [Veraison](https://github.com/veraison) project, you will use components implemented in the [Confidential Containers (CoCo) Project](https://github.com/confidential-containers) to support the [IETF RATS model](https://datatracker.ietf.org/doc/rfc9334/) (Remote ATtestation procedureS). These components include the Attestation Service (AS), Key Broker Service (KBS), Reference Value Provider Service (RVPS), Attestation Agent (AA), and Confidential Data Hub (CDH). +[Run an end-to-end Attestation Flow with Arm CCA](/learning-paths/servers-and-cloud-computing/cca-essentials/). The main difference is that, instead of the KBS from the [Veraison](https://github.com/veraison) project, you will use components implemented in the [Confidential Containers (CoCo) Project](https://github.com/confidential-containers) to support the [IETF RATS model](https://datatracker.ietf.org/doc/rfc9334/) (Remote ATtestation procedureS). These components include the Attestation Service (AS), Key Broker Service (KBS), Reference Value Provider Service (RVPS), Attestation Agent (AA), and Confidential Data Hub (CDH). The AS, KBS, and RVPS components are part of the [Trustee project](https://github.com/confidential-containers/trustee), whereas the AA and CDH are part of the [Guest Components](https://github.com/confidential-containers/guest-components) project in CoCo. ## RATS roles -This Learning Path uses the following RATS roles: +This Learning Path focuses on the following key concepts: -- **Attester** – Provides evidence that is evaluated to decide trustworthiness (for example, whether it is authorized to perform an action). Evidence can include configuration data, measurements, telemetry, or inferences. -- **Verifier** – Evaluates the evidence from the Attester and produces attestation results that are sent to the Relying party. The Verifier vouches for the validity of those results. -- **Relying party** – Depends on the validity of information from the Attester (either directly or through the Verifier) to make an access or policy decision. +- **Attester** – provides evidence that is evaluated to decide **Trustworthiness** (for example, whether it is authorized to perform an action). +- **Evidence** can include configuration data, measurements, telemetry, or inferences. +- **Verifier** – evaluates the evidence from the Attester and produces attestation results that are sent to the Relying party. The Verifier vouches for the validity of those results. +- **Relying party** – depends on the validity of information from the Attester (either directly or through the Verifier) to make an access or policy decision. ## Trustee components @@ -55,8 +47,8 @@ The following diagram shows the AS components: The AS performs this verification flow: -1. **Verify format and origin of evidence** – For example, verify the evidence signature. This is handled by a platform-specific Verifier driver. -2. **Evaluate claims** – For example, validate that measurements match expected values. This is handled by the Policy engine, with RVPS support. +- **Verify format and origin of evidence** – for example, verify the evidence signature. This is handled by a platform-specific Verifier driver. +- **Evaluate claims** – for example, validate that measurements match expected values. This is handled by the Policy engine, with RVPS support. ## Verifier driver diff --git a/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md b/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md index 7b7bb2cb45..0e314dfefc 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-trustee/flow.md @@ -12,7 +12,7 @@ In this section you’ll run the **Trustee services** (AS, KBS, RVPS), launch a ## Install dependencies -Install Docker. On Ubuntu 24.04 LTS, set up Docker’s APT repository: +Start by installing Docker. On Ubuntu 24.04 LTS, set up Docker’s APT repository: ```bash # Add Docker's official GPG key: @@ -35,7 +35,7 @@ Install Git and Docker packages: sudo apt-get install -y git docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` -Add your user name to the docker group (open a new shell after this so the change takes effect): +Add your user name to the Docker group (open a new shell after this so the change takes effect): ``` bash sudo usermod -aG docker $USER newgrp docker @@ -56,13 +56,13 @@ Additional Learning Path–specific changes include: - Attestation policy with CCA rules -- An “affirming” resource policy +- An *affirming* resource policy - A demo secret message - A shared Docker network for all containers in this demo -Go into the `cca-trustee` directory and start the Trustee services docker containers (as detached services): +Go into the `cca-trustee` directory and start the Trustee services Docker containers (as detached services): ``` bash { output_lines = "3-9" } cd cca-trustee docker compose up -d @@ -85,7 +85,7 @@ Where `service` is either `as`,`kbs` or `rvps`. With the Trustee Services running in one terminal, open up a new terminal in which you will run CCA attestations. -Pull the docker image with the pre-built FVP, and then run the container connected to the same docker network: +Pull the Docker image with the pre-built FVP, and then run the container connected to the same Docker network: ```bash docker pull armswdev/cca-learning-path:cca-simulation-v2 @@ -148,7 +148,8 @@ Run the attestation command and save the EAT Attestation Result (EAR) message in Request the demo secret with that EAR: -```bash./kbs-client --url http://kbs:8080 get-resource \ +```bash + ./kbs-client --url http://kbs:8080 get-resource \ --tee-key-file realm.key --attestation-token ear.jwt \ --path "cca-trustee/demo-message/message.txt" ``` @@ -213,7 +214,7 @@ Storage Opaque [none]: no claim being made Sourced Data [none]: no claim being made ``` -This part of the output shows how the attestation service has compared the attestation token against its expectations of a trustworthy system. These comparisons are known as *trustworthiness vectors"*. It also shows the conclusions that were drawn from that comparison. +This part of the output shows how the attestation service has compared the attestation token against its expectations of a trustworthy system. These comparisons are known as *trustworthiness vectors*. It also shows the conclusions that were drawn from that comparison. Note these two trustworthiness vectors in the result: - __Hardware [affirming]__. Evidence in the attestation token shows a good match against the expectations of CCA platform.