CCA Veraison_AP approved

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:

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"
 

content/learning-paths/servers-and-cloud-computing/cca-veraison/_review.md

@@ -15,17 +15,17 @@ 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.
     - questions:
         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.

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,51 +19,54 @@ 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
 ```
 
 ## 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
 ```
 
 ## 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-*`

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

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.