Merge pull request #1397 from annietllnd/cca-veraison

Draft CCA attestation Learning Path

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

@@ -0,0 +1,40 @@
+---
+title: Introduction to CCA Attestation with 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.
+
+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
+
+
+prerequisites:
+    - An Arm-based or x86 computer running Ubuntu. You can use a server instance from the cloud service provider of your choice.
+
+
+author_primary: Paul Howard
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+armips:
+    - Cortex-A
+operatingsystems:
+    - Linux
+tools_software_languages:
+    - CCA
+
+
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

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

@@ -0,0 +1,28 @@
+---
+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.
+
+recommended_path: "/learning-paths/servers-and-cloud-computing/cca-essentials"
+
+
+further_reading:
+    - resource:
+        title: RATS architecture (RFC 9334) 
+        link: https://datatracker.ietf.org/doc/rfc9334/
+        type: documentation
+    - resource:
+        title: The Realm Management Monitor Specification
+        link: https://developer.arm.com/documentation/den0137/latest/
+        type: documentation
+    - resource:
+        title: The Attestation Results for Secure Interactions (AR4SI) 
+        link: https://datatracker.ietf.org/doc/draft-ietf-rats-ar4si/
+        type: documentation
+
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 21                  # set to always be larger than the content in this path, and one more than 'review'
+title: "Next Steps"         # Always the same
+layout: "learningpathall"   # All files under learning paths have this same wrapper
+---

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

@@ -0,0 +1,38 @@
+---
+# ================================================================================
+#       Edit
+# ================================================================================
+
+# Always 3 questions. Should try to test the reader's knowledge, and reinforce the key points you want them to remember.
+    # question:         A one sentence question
+    # answers:          The correct answers (from 2-4 answer options only). Should be surrounded by quotes.
+    # correct_answer:   An integer indicating what answer is correct (index starts from 0)
+    # explanation:      A short (1-3 sentence) explanation of why the correct answer is correct. Can add additional context if desired
+
+
+review:
+    - questions:
+        question: >
+            A secure boundary is sufficient for confidential computing.
+        answers:
+            - "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"
+        correct_answer: 1
+        explanation: >
+            The CCA attestation token is divided at the top-level into the platform token and the realm token.
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+title: "Review"                 # Always the same title
+weight: 20                      # Set to always be larger than the content in this path
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+---

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

@@ -0,0 +1,156 @@
+---
+title: Download and inspect the attestation token
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+In this section, you will obtain an example CCA attestation token.
+
+## 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
+
+```bash
+rm -rf /usr/local/go
+
+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.
+
+```bash
+export PATH=$PATH:/usr/local/go/bin
+```
+Verify the installation by checking that the command outputs the installed version.
+
+```bash
+go version
+```
+
+## Install Git
+
+Verify that `git` is installed using the command below. It should output 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:
+
+```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)
+
+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.
+
+{{% 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/).
+{{% /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).
+
+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:
+
+```bash
+cd $HOME
+git clone https://github.com/veraison/evcli.git
+```
+Change the directory and build the tool:
+
+```bash
+cd evcli
+go build
+```
+
+The tool is quite small, so this should not take long. Once it has built, you can progress to the next step.
+
+## Inspect the CCA Example Attestation Token
+
+Now that you have built the `evcli` command-line tool, you can use it to inspect the contents of the example CCA attestation token that you downloaded earlier.
+
+Run the following command:
+
+```bash
+./evcli cca print --token $HOME/cca_example_token.cbor
+```
+
+The contents of the token are displayed as JSON. Check that the output matches the below. Some of the output has been removed for better readability.
+
+```output
+{
+  "cca-platform-token": {
+    "cca-platform-profile": "tag:arm.com,2023:cca_platform#1.0.0",
+    "cca-platform-challenge": "tZc8touqn8VVWHhrfsZ/aeQN9bpaqSHNDCf0BYegEeo=",
+    "cca-platform-implementation-id": "f0VMRgIBAQAAAAAAAAAAAAMAPgABAAAAUFgAAAAAAAA=",
+    "cca-platform-instance-id": "AQcGBQQDAgEADw4NDAsKCQgXFhUUExIREB8eHRwbGhkY",
+    "cca-platform-config": "z8/Pzw==",
+    "cca-platform-lifecycle": 12291,
+    "cca-platform-sw-components": [
+      {
+        "measurement-type": "RSE_BL1_2",
+        "measurement-value": "micfKpFrC27mzsskJvCzIG7wdFeL5V2byU9vP+Orhqo=",
+        "signer-id": "U3h5YwdTXfPsjYsVouLcVkFBnD0wYM/jIjjA+pc/eqM=",
+        "measurement-description": "sha-256"
+      },
+      (...)
+      {
+        "measurement-type": "SOC_FW_CONFIG",
+        "measurement-value": "5sIejSYP5xiC3r2zOdJAKiynZIUpvCMD9IZJvOA4ABc=",
+        "signer-id": "U3h5YwdTXfPsjYsVouLcVkFBnD0wYM/jIjjA+pc/eqM=",
+        "measurement-description": "sha-256"
+      }
+    ],
+    "cca-platform-service-indicator": "https://veraison.example/.well-known/veraison/verification",
+    "cca-platform-hash-algo-id": "sha-256"
+  },
+  "cca-realm-delegated-token": {
+    "cca-realm-profile": "tag:arm.com,2023:realm#1.0.0"
+    "cca-realm-challenge": "bobW2XzHE7xt1D285JGmtAMRwCeov4WjnaY+nORMEyqKEZ0pb65qaZnpvz5EcbDOASRdiJQkwx6JeTs7HWsVBA==",
+    "cca-realm-personalization-value": "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIDEzIGxhenkgZG9ncy5UaGUgcXVpY2sgYnJvd24gZm94IA==",
+    "cca-realm-initial-measurement": "MRMUq3NiA1DPdYg0rlxl2ejC3H/r5ufZZUu+hk4wDUk=",
+    "cca-realm-extensible-measurements": [
+      "JNWwopbMBcvYBoxQZ8W9Rzt3Ddpq4IL+O6MKvj+aarE=",
+      "eI/AkL/GuO2QMVK6hBTnPa9bjHux55rVAqsGmbZZ7RY=",
+      "2sRqWEFdw6ANenQYUgCOnK5k9S0DufdtdvSzZE/vxBY=",
+      "MsavxiflVYXAMVU1nzMaDiJfaEDblH3Zbvq4G+JnGTk="
+    ],
+    "cca-realm-hash-algo-id": "sha-256",
+    "cca-realm-public-key": "BHb5iAkb5YXtQYAa7Pq4WFSMYwV+FrDmdhILvQ0vnCngVsXUGgEw65whUXiZ3CMUayjhsGK9PqSzFf0hnxy7Uoy250ykm+Fnc3NPYaHKYQMbK789kY8vlP/EIo5QkZVErg==",
+    "cca-realm-public-key-hash-algo-id": "sha-256"
+  }
+}
+```
+
+It is not important to understand every detail of the attestation token right now, but here are some of the most important 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.
+- 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 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-*`
+- The claims of the realm token are labelled with the prefix `cca-realm-*`
+- Many of the claims take the form of _measurements_. A measurement is a hash (checksum) that is computed from one of the firmware or software components that are running within the realm or within the platform. Checking these measurements against known-good values is an essential step for evaluating the trustworthiness of the realm. Any mismatch could mean that the system is running some software or firmware that has been tampered with, or is at the wrong patch or version level.
+
+You might find it instructive to view the token in a formatting tool such as https://jsonviewer.stack.hu, where you can interactively expand and collapse different parts of the object tree to gain a better feel for the structure. Doing this may help you to digest the bullet points above.
+
+To test out the formatting tool, see if you can find the measurement of the Realm Management Monitor (RMM). The RMM is part of the firmware for a CCA platform.
+
+Next, you will see the steps involved in verifying and evaluating a CCA attestation token.

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

@@ -0,0 +1,92 @@
+---
+title: Use the verification service
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Attestation Verification Service for Pre-Silicon CCA Platforms
+[Linaro](https://www.linaro.org/) provides an attestation verifier service for pre-silicon CCA platforms, such as the Fixed Virtual Platform (FVP). This service is available publicly and is hosted on Linaro infrastructure. This verification service can be used to verify CCA attestation tokens that come from emulated Arm platforms, including the example token that you have been using in this exercise.
+
+Linaro’s verification service is implemented using components from the open source [Veraison](https://github.com/veraison) project.
+
+The URL for reaching this experimental verifier service is http://veraison.test.linaro.org:8080
+
+To check that you can reach the Linaro attestation verifier service, run the following command:
+
+```bash
+curl http://veraison.test.linaro.org:8080/.well-known/veraison/verification
+```
+
+This is a simple call to query the well-known characteristics of the verification service. If it succeeds, it will return a JSON response that looks something like this:
+
+```output
+{
+  "ear-verification-key": {
+    "alg": "ES256",
+    "crv": "P-256",
+    "kty": "EC",
+    "x": "usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8",
+    "y": "IBOL-C3BttVivg-lSreASjpkttcsz-1rb7btKLv8EX4"
+  },
+  "media-types": [
+    "application/vnd.parallaxsecond.key-attestation.tpm",
+    "application/eat-cwt; profile=\http://arm.com/psa/2.0.0\",
+    "application/eat+cwt; eat_profile=\"tag:psacertified.org,2023:psa#tfm\"",
+    "application/eat-collection; profile=\http://arm.com/CCA-SSD/1.0.0\",
+    "application/eat+cwt; eat_profile=\"tag:psacertified.org,2019:psa#legacy\"",
+    "application/vnd.enacttrust.tpm-evidence",
+    "application/vnd.parallaxsecond.key-attestation.cca",
+    "application/psa-attestation-token",
+    "application/pem-certificate-chain"
+  ],
+  "version": "commit-2063e7e",
+  "service-state": "READY",
+  "api-endpoints": {
+    "newChallengeResponseSession": "/challenge-response/v1/newSession"
+  }
+}
+```
+
+This JSON response contains all the information that you need to use the verification service. Review the different JSON properties.
+
+- The `ear-verification-key` is the cryptographic key that you will use later to verify the results that are returned by the service.
+
+- The `media-types` entry provides the list of the different attestation data formats that the verification service supports. If you look down this list, you will find an entry for the CCA profile of the EAT format. It is the fourth entry in the list. This tells us that the service is capable of processing Arm CCA attestation tokens.
+
+- The `api-endpoints` entry describes the set of RESTful APIs that are supported by the service. When verifying an attestation token, you will use the challenge-response API.
+
+If you can reach the verification service, you are now ready to use it to evaluate the CCA example token.
+
+## Save the Public Key of the Verification Service
+
+One of the properties that was returned in the previous step was the public key of the verification service. This key will be needed later to check the signature on the attestation results. All that is needed in this step is to copy the contents of the `ear-verification-key` field from the previous step and save it to a separate JSON file.
+
+The easiest way to do this is to use the `jq` utility. 
+You can save the public key by repeating the curl command from the previous step and use `jq` to filter the response down to just the public key part. Save it into a file called `pkey.json`:
+
+```bash
+curl -s -N http://veraison.test.linaro.org:8080/.well-known/veraison/verification | jq '."ear-verification-key"' > $HOME/pkey.json
+```
+You have now saved the public key of the verification service. You are now ready to submit the CCA example attestation token to the service and get an attestation result.
+
+## Submit the CCA Example Token to the Verification Service
+To submit the example CCA attestation token to the verification service, you will need to use the `evcli` tool once again. First, configure the correct API endpoint for the Linaro verifier service:
+
+```bash
+export API_SERVER=http://veraison.test.linaro.org:8080/challenge-response/v1/newSession
+```
+
+Now submit the token using the following command. The output of this command is an attestation result, which will be saved in a file called `attestation_result.jwt`:
+
+```bash
+./evcli cca verify-as relying-party --token $HOME/cca_example_token.cbor | tr -d \" > $HOME/attestation_result.jwt
+```
+
+{{% notice Note%}}
+The `| tr -d \"` is used to remove the double quotes in capturing the output from the `evcli` command.
+{{% /notice %}}
+
+The verification service has now evaluated the token and returned a result, which you have saved.
+The last two steps in this learning path will be about understanding the result data that came back from the verification service.