diff --git a/content/learning-paths/servers-and-cloud-computing/cca-veraison/_index.md b/content/learning-paths/servers-and-cloud-computing/cca-veraison/_index.md index 7f8c99028a..5f7f30a4bc 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-veraison/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-veraison/_index.md @@ -1,17 +1,17 @@ --- -title: Introduction to CCA Attestation with Veraison +title: Get Started with CCA Attestation and Veraison minutes_to_complete: 30 -who_is_this_for: This learning path is aimed at developers who wish to understand attestation in the context of confidential computing, using Arm’s Confidential Computing Architecture (CCA). It will provide you with some practical, hands-on experience with the data formats and workflows associated with attestation, which will help to provide you with a joined-up understanding of the many separate documents and specifications that exist on this topic. +who_is_this_for: This Learning Path is for developers who would like to learn about attestation in confidential computing, using Arm’s Confidential Computing Architecture (CCA). learning_objectives: - - Describe the importance of attestation for confidential computing - - Understand what a CCA attestation token is, and describe its format - - Inspect the contents of a CCA attestation token using command-line tools - - Use an attestation verification service to evaluate a CCA attestation token - - Understand the purpose of the open source Veraison project + - Describe the importance of attestation for confidential computing. + - Understand what a CCA attestation token is, and describe its format. + - Inspect the contents of a CCA attestation token using command-line tools. + - Use an attestation verification service to evaluate a CCA attestation token. + - Understand the purpose of the Open source Veraison project. prerequisites: diff --git a/content/learning-paths/servers-and-cloud-computing/cca-veraison/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/cca-veraison/_next-steps.md index 7956d8c74b..4960c6be7e 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-veraison/_next-steps.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-veraison/_next-steps.md @@ -1,5 +1,5 @@ --- -next_step_guidance: Now that you have gained some hands-on experience with the data formats and workflows associated with attestation for confidential computing, you may wish to explore some additional resources and specifications, which go into greater detail on some of the individual aspects. +next_step_guidance: Now that you have gained some hands-on experience with the data formats and workflows associated with attestation for confidential computing, you can explore some additional resources and specifications, which go into greater detail on some of the individual aspects. recommended_path: "/learning-paths/servers-and-cloud-computing/cca-essentials" diff --git a/content/learning-paths/servers-and-cloud-computing/cca-veraison/_review.md b/content/learning-paths/servers-and-cloud-computing/cca-veraison/_review.md index 50dc9f18d5..8a9fa46098 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-veraison/_review.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-veraison/_review.md @@ -15,8 +15,8 @@ review: question: > A secure boundary is sufficient for confidential computing. answers: - - "True" - - "False" + - "True." + - "False." correct_answer: 2 explanation: > A secure boundary is necessary for confidential computing, but it is not sufficient. There must also be a way to establish trust with the target compute environment that the boundary is protecting (the TEE). Trust needs to be built by a process that is both explicit and transparent. This process is known as attestation. @@ -24,8 +24,8 @@ review: question: > The CCA attestation token is divided at the top level into two sub-tokens. answers: - - "True" - - "False" + - "True." + - "False." correct_answer: 1 explanation: > The CCA attestation token is divided at the top-level into the platform token and the realm token. diff --git a/content/learning-paths/servers-and-cloud-computing/cca-veraison/attestation-token.md b/content/learning-paths/servers-and-cloud-computing/cca-veraison/attestation-token.md index 862450165a..95b336670a 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-veraison/attestation-token.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-veraison/attestation-token.md @@ -1,16 +1,16 @@ --- title: Download and inspect the attestation token -weight: 4 +weight: 5 ### FIXED, DO NOT MODIFY layout: learningpathall --- -In this section, you will obtain an example CCA attestation token. +In this section, you will obtain an example CCA attestation token. To set up the tools that you need for attestation, you need to install the Go language on your system. ## Install Go -In order to run the tools used for attestation, start by installing the Go language on your system. First, you will remove any existing Go installation. After that, you obtain the install files and +First, start by removing any existing Go installation. Next, obtain the install files and run the following command: ```bash rm -rf /usr/local/go @@ -19,12 +19,12 @@ wget https://go.dev/dl/go1.23.3.linux-$(dpkg --print-architecture).tar.gz tar -C /usr/local -xzf go1.23.3.linux-$(dpkg --print-architecture).tar.gz ``` -Export the installation path and add it to your $PATH environment variable. +Export the installation path and add it to your `$PATH environment` variable. ```bash export PATH=$PATH:/usr/local/go/bin ``` -Verify the installation by checking that the command outputs the installed version. +Verify the installation by running the following command to check the version of the installation: ```bash go version @@ -32,14 +32,17 @@ go version ## Install Git -Verify that `git` is installed using the command below. It should output the version available on your computer. +Verify that `git` is installed by using the command below. It should produce an output that lists the version available on your computer: ```bash git --version ``` ## Install jq -The jq utility, is a popular command-line tool that can be used to parse and manipulate JSON data. You can install it using your local package manager, for instance: + +The jq utility is a popular command-line tool that you can use to parse and manipulate JSON data. + +To install it, you can use your local package manager, for instance: ```bash sudo apt install jq @@ -47,23 +50,23 @@ sudo apt install jq ## Download the Example CCA Attestation Token -Using your preferred web browser, navigate to the [token in the TrustedFirmware-M tools repository](https://github.com/TrustedFirmware-M/tf-m-tools/blob/main/iat-verifier/tests/data/cca_example_token.cbor) +Using your preferred web browser, navigate to the [token in the TrustedFirmware-M tools repository](https://github.com/TrustedFirmware-M/tf-m-tools/blob/main/iat-verifier/tests/data/cca_example_token.cbor). -Use GitHub’s download button, located on the right of the upper toolbar, to download the token as a *raw* (binary) file. +Use GitHub’s download button, located on the right of the upper toolbar, to download the token as a `raw` binary file. ![download_raw.png](./download_raw.png) -Place this file in the `$HOME` folder, while keeping the file name the same. The rest of this learning path will use the notation `$HOME/cca_example_token.cbor` as the file path. +Place this file in the `$HOME` folder, while retaining the file name. The rest of this Learning Path uses the notation `$HOME/cca_example_token.cbor` as the file path. {{% notice Note %}} -You will notice that the filename extension on the example token is `.cbor`, which also denotes the format of the data. CBOR is the Concise Binary Object Representation. You are likely to already be familiar with JSON (the JavaScript Object Notation). JSON provides a standard way to convey nested structures of key-value pairs. CBOR is conceptually the same as JSON. The difference is that CBOR is a binary format, rather than a text-based format like JSON. CBOR is designed for compactness and ease of machine-readability, but at the expense of human-readability. You can learn more about CBOR [here](https://cbor.io/). +You will notice that the filename extension on the example token is `.cbor`, which also denotes the format of the data. CBOR is an acronym for Concise Binary Object Representation. You might already be familiar with JSON (the JavaScript Object Notation). JSON provides a standard way of conveying the nested structures of key-value pairs. CBOR is conceptually the same as JSON. The difference is that CBOR is a binary format, rather than a text-based format like JSON. CBOR is designed for compactness and machine-readability, but at the expense of human-readability. You can learn more about CBOR [here](https://cbor.io/). {{% /notice %}} ## Build the EVCLI Tool -Now that you have downloaded the example CCA attestation token, the next step is to look inside the token and learn about the data that it contains. Because the token is a binary file, you will need to use a tool to parse the file and display its contents. The tool that you will use is a command-line tool called `evcli` (which is short for the EVidence Command Line Interface – remember that attestation tokens are used to convey evidence about realms and the platforms on which they are hosted). +Now that you have downloaded the example CCA attestation token, the next step is to look inside the token and learn about the data that it contains. As the token is a binary file, you will need to use a tool to parse the file and display its contents. The tool that you will use is a command-line tool called `evcli`. Evcli is an acronym for EVidence Command Line Interface, linking with the idea that attestation tokens are used to convey evidence about realms and the platforms on which they are hosted. -The `evcli` tool is part of the Veraison open-source project, which was covered in the previous section. +The `evcli` tool is part of the Veraison Open-Source project, which was covered in the previous section. Clone the source code using git as follows: @@ -137,12 +140,12 @@ The contents of the token are displayed as JSON. Check that the output matches t } ``` -It is not important to understand every detail of the attestation token right now, but here are some of the most important highlights: +It is not important to understand every detail of the attestation token, but here are some of the highlights: -- The CCA attestation token is a variant of a more general-purpose attestation data format known as the Entity Attestation Token (EAT). The EAT specification has been established to create more alignment across the industry with respect to attestation data, so that common tools and libraries can be used to process it. +- The CCA attestation token is a variant of a more general-purpose attestation data format known as the Entity Attestation Token (EAT). The EAT specification has been established to create better alignment across the industry with respect to attestation data, so that common tools and libraries can be used to process it. - Specific variants of the EAT format are known as profiles, so this token is adopting the Arm CCA profile of the EAT specification. - The CCA attestation token is divided at the top level into two sub-tokens. These are known individually as the platform token and the realm token. -- The platform token contains the evidence about the Arm CCA platform on which the realm is running, which includes details about the state of the hardware and firmware that compose the platform. You can think of the platform as being like a single server or self-contained computing device. A single platform could host many realms, which could be executing as virtual machines or containers. Therefore, many realms might produce the same platform token. +- The platform token contains the evidence about the Arm CCA platform on which the realm is running, which includes details about the state of the hardware and firmware that compose the platform. You can think of the platform as a single server or self-contained computing device. A single platform can host many realms, which can be executing as virtual machines or containers. Therefore, many realms might produce the same platform token. - The realm token contains the evidence about the realm itself, which is running on the platform. It is the more dynamic part of the token. It includes information about the realm’s initial memory contents and boot state. - The top-level data items in each sub-token are known as claims. A claim is an individual evidence fragment that describes a specific property of the system. - The claims of the platform token are labelled with the prefix `cca-platform-*` diff --git a/content/learning-paths/servers-and-cloud-computing/cca-veraison/attestation-verification.md b/content/learning-paths/servers-and-cloud-computing/cca-veraison/attestation-verification.md index 076791c45c..3b33f116bd 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-veraison/attestation-verification.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-veraison/attestation-verification.md @@ -1,6 +1,6 @@ --- title: Use the verification service -weight: 5 +weight: 6 ### FIXED, DO NOT MODIFY layout: learningpathall diff --git a/content/learning-paths/servers-and-cloud-computing/cca-veraison/cca-attestation.md b/content/learning-paths/servers-and-cloud-computing/cca-veraison/cca-attestation.md index a8823a4ddc..f949a3fd66 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-veraison/cca-attestation.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-veraison/cca-attestation.md @@ -1,31 +1,24 @@ --- -title: CCA Attestation and Veraison -weight: 2 +title: CCA and Attestation +weight: 3 ### FIXED, DO NOT MODIFY layout: learningpathall --- - -All confidential computing architectures provide attestation as a means of building trust. This learning path will help you to understand the common concepts in attestation, while also guiding you through code examples that focuses on how attestation is performed with CCA. This section contains an overview of the topic, building a common understanding before diving into the practical part. - ## Overview -Confidential computing is about protecting data in use. This protection comes from the creation of a security boundary around the computation being performed. This security boundary creates what is normally called a Trusted Execution Environment (TEE). The data and code that executes within the TEE is protected from the outside world. Different technologies exist for creating this secure boundary. In the case of Arm CCA, the secure boundary is provided by the Realm Management Extensions (RME), which are part of the Arm Architecture v9 for A-profile CPUs. +Confidential computing is about protecting data in use. This protection comes from the creation of a security boundary around the computation being performed. This security boundary creates what is called a Trusted Execution Environment (TEE). The data and code that executes within the TEE is protected from the outside world. Different technologies exist for creating this secure boundary. In the case of Arm CCA, the Realm Management Extension (RME), which is part of the Armv9 Architecture for A-profile CPUs, provides the secure boundary. -A secure boundary is necessary for confidential computing, but it is not sufficient. There must also be a way to establish trust with the target compute environment that the boundary is protecting (the TEE). Trusting the environment implicitly does not meet the strict definition of confidential computing. Instead, trust needs to be built by a process that is both explicit and transparent. This process is known as attestation. The role of attestation is described in the figure below. +A secure boundary is necessary for confidential computing, but it is not sufficient alone. There must also be a way to establish trust with the TEE, the target compute environment, that the boundary is protecting. Trusting the environment implicitly does not meet the strict definition of confidential computing. Instead, trust needs to be built by a process that is both explicit and transparent. This process is known as attestation. The role of attestation is described in the Figure 1. -![Attestation role](./attestation-role.png) +![Attestation role alt-text#center](./attestation-role.png "Figure 1: The Role of Attestation") At the heart of the CCA attestation process is a small, self-contained packet of data known as a CCA attestation token. CCA attestation tokens are produced by realms. They contain evidence about the booted state of the realm. They also contain evidence about the state of the CCA host platform on which the realm is running, including details about the hardware and firmware. You will learn more about this evidence later in the learning path. -CCA attestation tokens have two very important properties. The first is that they are cryptographically signed using a private key that is strongly protected by the platform where the realm is running. The second is that they can be evaluated remotely using an attestation verification service. The verification service acts as a trust authority. It can verify the token’s cryptographic signature, which ensures that the evidence is authentic. It can also compare the evidence against the expectations of a trustworthy platform. These two properties combine to allow a user of the realm to decide whether the realm will provide an adequate trusted environment for confidential computing. - -## Veraison - -The tools and services that you will use in this learning path come from an open-source project called [Veraison](https://github.com/veraison). Veraison (pronounced “ver-ayy-sjon”) is a project that was founded within Arm but has since been donated to the [Confidential Computing Consortium](https://confidentialcomputing.io/) as an ongoing community project with a growing number of contributors from other organizations. Veraison focuses on the verification aspect of attestation. It provides reusable tools and components that can be used to construct verification services or libraries. +CCA attestation tokens have two very important properties: -Confidential computing is a new and fast-growing industry. There are many stakeholders including hardware manufacturers, firmware vendors, service providers, application developers, end users and regulators. Attestation is an end-to-end process that has the potential to impact all of them. Good alignment and interoperability are essential. The Veraison project is being developed in parallel with several standardization efforts across various industry bodies. Veraison demonstrates the effectiveness of these standards in practice, facilitates their ongoing development within open communities, and makes it possible to build functioning software from them. +* Firstly, they are cryptographically-signed using a private key that is strongly protected by the platform where the realm is running. +* Secondly, they can be evaluated remotely using an attestation verification service. -In this learning path, you will use some of the command-line tools that Veraison provides. You will also make use of an attestation verifier service that is built entirely from Veraison components. +The verification service acts as a trust authority. It can verify the token’s cryptographic signature, which ensures that the evidence is authentic. It can also compare the evidence against the expectations of a trustworthy platform. In combination, these two properties allow a user of the realm to decide whether the realm will provide an adequate trusted environment for confidential computing. -Now that you have some background, move on to the next section where you will download a file that contains an example of a CCA attestation token. You will then use command-line tools to inspect the contents of the token, and you will see how to use an attestation verifier service to verify and evaluate the token. diff --git a/content/learning-paths/servers-and-cloud-computing/cca-veraison/evaluate-result.md b/content/learning-paths/servers-and-cloud-computing/cca-veraison/evaluate-result.md index 7956d5a103..ce1e2586fb 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-veraison/evaluate-result.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-veraison/evaluate-result.md @@ -1,6 +1,6 @@ --- title: Evaluate results -weight: 6 +weight: 7 ### FIXED, DO NOT MODIFY layout: learningpathall @@ -8,7 +8,9 @@ layout: learningpathall ## Build the ARC Tool -You are already familiar with the evcli tool, which can be used to process attestation tokens. There is a very similar tool called `arc`, which can be used to process attestation results. The arc tool is also part of the Veraison project. Clone its repository as follows: +You are already familiar with the evcli tool, which you can use to process attestation tokens. There is a very similar tool called `arc`, which you can use to process attestation results. The arc tool is also part of the Veraison project. + +Clone its repository as follows: ```bash cd $HOME @@ -22,12 +24,12 @@ cd ear/arc go build ``` -You are now ready to proceed to the final step in this learning path, where you will use the arc tool to inspect the attestation result. +You are now ready to proceed to the final step in this Learning Path, where you will use the arc tool to inspect the attestation result. ## Evaluate the Attestation Result You have now submitted the example CCA attestation token to the Veraison verification service hosted by Linaro and saved the result to the file `attestation_result.jwt`. In this step, you will examine the result and see how it can be used to evaluate the trustworthiness of a CCA realm. -The attestation result is a JWT file, which stands for JSON Web Token. This means that the result has been cryptographically signed by the Veraison verification service. In a previous step, you saved the public key that will be used to verify the signature. +The attestation result is a JWT file, which stands for JSON Web Token. This means that the result has been cryptographically-signed by the Veraison verification service. In a previous step, you saved the public key that will be used to verify the signature. The following command will use the `arc` tool, which you built in the previous step, to verify the cryptographic signature on the attestation result, and display the result in a human-readable format: @@ -60,17 +62,19 @@ Storage Opaque [affirming]: encrypted secrets with HW-backed keys Sourced Data [none]: no claim being made ``` -This part of the output shows how the verification service has compared the attestation token against its expectations of a trustworthy system. It also shows what conclusions were drawn from that comparison. +This part of the output shows how the verification service has compared the attestation token against its expectations of a trustworthy system. It also shows the conclusions that were drawn from that comparison. -It is important to understand that an attestation result is not a simple yes/no answer to the question of whether the system is trustworthy. Instead, it is a set of data points (known as _trustworthiness vectors_). Each data point shows how a particular aspect of the system compares against the expectations set by the verification service. Each point of comparison can lead to one of the following results: +It is important to understand that an attestation result is not a simple "yes" or "no" answer to the question of whether the system is trustworthy. Instead, it is a set of data points, known as _trustworthiness vectors_. Each data point shows how a particular aspect of the system compares against the expectations set by the verification service. Each point of comparison can lead to one of the following results: - __Affirming__. This is the most favourable result. It is given when the evidence in the attestation token shows a good match against the expectations of a trustworthy system. - __Warning__. This is a less favourable result. It is given when the attestation token does not show a good match against the expectations of a trustworthy system. - __None__. This is an unfavourable result, meaning that no comparison was possible, either because data was missing from the evidence in the attestation token, or because the verification service does not have any expectations to compare the evidence against, and is therefore unable to draw any conclusion. - __Contraindicated__. This is the least favourable result. It is given when the evidence in the attestation token specifically contradicts the expectations of a trustworthy system. -You will also notice that the result is grouped into two sections (known as submodules, and indicated with the `submod()` notation). Recall from the earlier steps that the CCA attestation token is grouped into two parts: the _realm_ token and the _platform_ token. This same grouping is therefore also reflected in the attestation result. There are separate results for each. +You will also notice that the result is grouped into two sections known as submodules, and indicated with the `submod()` notation. Recall from the earlier steps that the CCA attestation token is grouped into two parts: the _realm_ token and the _platform_ token. This same grouping is therefore also reflected in the attestation result. There are separate results for each. + +How is all this data used to make a single "yes" or "no" decision about whether this realm is trustworthy for a confidential computation to take place? After all, making such a decision is the whole purpose of the attestation process. -How is all this data used to make a single yes/no decision about whether this realm is trustworthy for a confidential computation to take place? After all, making such a decision is the whole purpose of the attestation process. +The next Learning Path in this series on Arm CCA answers this question by taking you through the steps needed to deploy an example workload that depends on attestation to release some secret data into a running realm. -The next learning path in this series on Arm CCA will answer this question by taking you through the steps needed to deploy an example workload that depends on attestation to release some secret data into a running realm. You will learn how to use policies to govern the strictness of the attestation process. You will also see how the workflow steps and data that you have just been using can be orchestrated together to form the common programming patterns of confidential computing. \ No newline at end of file +You will learn how to use policies to govern the strictness of the attestation process. You will also see how the workflow steps and data that you have just been using can be orchestrated together to form the common programming patterns of confidential computing. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/cca-veraison/how-to-use.md b/content/learning-paths/servers-and-cloud-computing/cca-veraison/how-to-use.md new file mode 100644 index 0000000000..fc76620f42 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/cca-veraison/how-to-use.md @@ -0,0 +1,17 @@ +--- +title: Using this Learning Path +weight: 2 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Highlights + +Some highlights of using this Learning Path are the following: + +* Practical, hands-on experience with the data formats and workflows associated with attestation, which in turn will help to provide you with a joined-up understanding of the many separate documents and specifications that exist on this topic. + +* An opportunity to learn about the common concepts in attestation, supported by code examples as a demonstration. + +* In advance of the practical sections, a chance to read theoretical overviews of both CCA Attestation and Veraison to help you grasp the basic concepts before progressing to the practical sections. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/cca-veraison/veraison.md b/content/learning-paths/servers-and-cloud-computing/cca-veraison/veraison.md new file mode 100644 index 0000000000..3490c8c1c6 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/cca-veraison/veraison.md @@ -0,0 +1,28 @@ +--- +title: Veraison +weight: 4 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Veraison + +The tools and services that you will use in this Learning Path derive from an Open-Source project called [Veraison](https://github.com/veraison). Veraison is a project that was founded within Arm but has since been donated to the [Confidential Computing Consortium](https://confidentialcomputing.io/) as an ongoing community project with a growing number of contributors from other organizations. Veraison addresses the verification aspect of attestation. It provides reusable tools and components that can be deployed in the construction of verification services or libraries. + +Confidential computing is a new, and fast-growing industry. There are many stakeholders, including: + +* Hardware manufacturers. +* Firmware vendors. +* Service providers. +* Application developers. +* End users. +* Regulators. + +Attestation is an end-to-end process that has the potential to impact all of these stakeholders. Good alignment and interoperability are both essential. The Veraison project is being developed in parallel with several standardization efforts across various industry bodies. + +Veraison demonstrates the effectiveness of these standards in practice, facilitating their ongoing development within open communities, and makes it possible to build functioning software from them. + +In this Learning Path, you will use some of the command-line tools that Veraison provides. You will also make use of an attestation verifier service that is built entirely from Veraison components. + +Now that you have some background information, you can move on to the next section where you will download a file that contains an example of a CCA attestation token. You will then use command-line tools to inspect the contents of the token, and you will see how to use an attestation verifier service to verify and evaluate the token.