Skip to content

Commit d1812e7

Browse files
pareenavermapareenaverma
authored
Merge pull request #1397 from annietllnd/cca-veraison
Draft CCA attestation Learning Path
2 parents fe8694a + c057577 commit d1812e7

File tree

9 files changed

+461
-0
lines changed

9 files changed

+461
-0
lines changed

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

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Introduction to CCA Attestation with Veraison
3+
4+
minutes_to_complete: 30
5+
6+
7+
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.
8+
9+
learning_objectives:
10+
- Describe the importance of attestation for confidential computing
11+
- Understand what a CCA attestation token is, and describe its format
12+
- Inspect the contents of a CCA attestation token using command-line tools
13+
- Use an attestation verification service to evaluate a CCA attestation token
14+
- Understand the purpose of the open source Veraison project
15+
16+
17+
prerequisites:
18+
- An Arm-based or x86 computer running Ubuntu. You can use a server instance from the cloud service provider of your choice.
19+
20+
21+
author_primary: Paul Howard
22+
23+
### Tags
24+
skilllevels: Introductory
25+
subjects: Performance and Architecture
26+
armips:
27+
- Cortex-A
28+
operatingsystems:
29+
- Linux
30+
tools_software_languages:
31+
- CCA
32+
33+
34+
35+
### FIXED, DO NOT MODIFY
36+
# ================================================================================
37+
weight: 1 # _index.md always has weight of 1 to order correctly
38+
layout: "learningpathall" # All files under learning paths have this same wrapper
39+
learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
40+
---

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
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.
3+
4+
recommended_path: "/learning-paths/servers-and-cloud-computing/cca-essentials"
5+
6+
7+
further_reading:
8+
- resource:
9+
title: RATS architecture (RFC 9334)
10+
link: https://datatracker.ietf.org/doc/rfc9334/
11+
type: documentation
12+
- resource:
13+
title: The Realm Management Monitor Specification
14+
link: https://developer.arm.com/documentation/den0137/latest/
15+
type: documentation
16+
- resource:
17+
title: The Attestation Results for Secure Interactions (AR4SI)
18+
link: https://datatracker.ietf.org/doc/draft-ietf-rats-ar4si/
19+
type: documentation
20+
21+
22+
# ================================================================================
23+
# FIXED, DO NOT MODIFY
24+
# ================================================================================
25+
weight: 21 # set to always be larger than the content in this path, and one more than 'review'
26+
title: "Next Steps" # Always the same
27+
layout: "learningpathall" # All files under learning paths have this same wrapper
28+
---

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
# ================================================================================
3+
# Edit
4+
# ================================================================================
5+
6+
# Always 3 questions. Should try to test the reader's knowledge, and reinforce the key points you want them to remember.
7+
# question: A one sentence question
8+
# answers: The correct answers (from 2-4 answer options only). Should be surrounded by quotes.
9+
# correct_answer: An integer indicating what answer is correct (index starts from 0)
10+
# explanation: A short (1-3 sentence) explanation of why the correct answer is correct. Can add additional context if desired
11+
12+
13+
review:
14+
- questions:
15+
question: >
16+
A secure boundary is sufficient for confidential computing.
17+
answers:
18+
- "True"
19+
- "False"
20+
correct_answer: 2
21+
explanation: >
22+
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.
23+
- questions:
24+
question: >
25+
The CCA attestation token is divided at the top level into two sub-tokens.
26+
answers:
27+
- "True"
28+
- "False"
29+
correct_answer: 1
30+
explanation: >
31+
The CCA attestation token is divided at the top-level into the platform token and the realm token.
32+
# ================================================================================
33+
# FIXED, DO NOT MODIFY
34+
# ================================================================================
35+
title: "Review" # Always the same title
36+
weight: 20 # Set to always be larger than the content in this path
37+
layout: "learningpathall" # All files under learning paths have this same wrapper
38+
---

‎content/learning-paths/servers-and-cloud-computing/cca-veraison/attestation-role.png‎

102 KB
Loading

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

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: Download and inspect the attestation token
3+
weight: 4
4+
5+
### FIXED, DO NOT MODIFY
6+
layout: learningpathall
7+
---
8+
9+
In this section, you will obtain an example CCA attestation token.
10+
11+
## Install Go
12+
13+
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
14+
15+
```bash
16+
rm -rf /usr/local/go
17+
18+
wget https://go.dev/dl/go1.23.3.linux-$(dpkg --print-architecture).tar.gz
19+
tar -C /usr/local -xzf go1.23.3.linux-$(dpkg --print-architecture).tar.gz
20+
```
21+
22+
Export the installation path and add it to your $PATH environment variable.
23+
24+
```bash
25+
export PATH=$PATH:/usr/local/go/bin
26+
```
27+
Verify the installation by checking that the command outputs the installed version.
28+
29+
```bash
30+
go version
31+
```
32+
33+
## Install Git
34+
35+
Verify that `git` is installed using the command below. It should output the version available on your computer.
36+
37+
```bash
38+
git --version
39+
```
40+
41+
## Install jq
42+
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:
43+
44+
```bash
45+
sudo apt install jq
46+
```
47+
48+
## Download the Example CCA Attestation Token
49+
50+
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)
51+
52+
Use GitHub’s download button, located on the right of the upper toolbar, to download the token as a *raw* (binary) file.
53+
54+
![download_raw.png](./download_raw.png)
55+
56+
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.
57+
58+
{{% notice Note %}}
59+
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/).
60+
{{% /notice %}}
61+
62+
## Build the EVCLI Tool
63+
64+
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).
65+
66+
The `evcli` tool is part of the Veraison open-source project, which was covered in the previous section.
67+
68+
Clone the source code using git as follows:
69+
70+
```bash
71+
cd $HOME
72+
git clone https://github.com/veraison/evcli.git
73+
```
74+
Change the directory and build the tool:
75+
76+
```bash
77+
cd evcli
78+
go build
79+
```
80+
81+
The tool is quite small, so this should not take long. Once it has built, you can progress to the next step.
82+
83+
## Inspect the CCA Example Attestation Token
84+
85+
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.
86+
87+
Run the following command:
88+
89+
```bash
90+
./evcli cca print --token $HOME/cca_example_token.cbor
91+
```
92+
93+
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.
94+
95+
```output
96+
{
97+
"cca-platform-token": {
98+
"cca-platform-profile": "tag:arm.com,2023:cca_platform#1.0.0",
99+
"cca-platform-challenge": "tZc8touqn8VVWHhrfsZ/aeQN9bpaqSHNDCf0BYegEeo=",
100+
"cca-platform-implementation-id": "f0VMRgIBAQAAAAAAAAAAAAMAPgABAAAAUFgAAAAAAAA=",
101+
"cca-platform-instance-id": "AQcGBQQDAgEADw4NDAsKCQgXFhUUExIREB8eHRwbGhkY",
102+
"cca-platform-config": "z8/Pzw==",
103+
"cca-platform-lifecycle": 12291,
104+
"cca-platform-sw-components": [
105+
{
106+
"measurement-type": "RSE_BL1_2",
107+
"measurement-value": "micfKpFrC27mzsskJvCzIG7wdFeL5V2byU9vP+Orhqo=",
108+
"signer-id": "U3h5YwdTXfPsjYsVouLcVkFBnD0wYM/jIjjA+pc/eqM=",
109+
"measurement-description": "sha-256"
110+
},
111+
(...)
112+
{
113+
"measurement-type": "SOC_FW_CONFIG",
114+
"measurement-value": "5sIejSYP5xiC3r2zOdJAKiynZIUpvCMD9IZJvOA4ABc=",
115+
"signer-id": "U3h5YwdTXfPsjYsVouLcVkFBnD0wYM/jIjjA+pc/eqM=",
116+
"measurement-description": "sha-256"
117+
}
118+
],
119+
"cca-platform-service-indicator": "https://veraison.example/.well-known/veraison/verification",
120+
"cca-platform-hash-algo-id": "sha-256"
121+
},
122+
"cca-realm-delegated-token": {
123+
"cca-realm-profile": "tag:arm.com,2023:realm#1.0.0"
124+
"cca-realm-challenge": "bobW2XzHE7xt1D285JGmtAMRwCeov4WjnaY+nORMEyqKEZ0pb65qaZnpvz5EcbDOASRdiJQkwx6JeTs7HWsVBA==",
125+
"cca-realm-personalization-value": "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIDEzIGxhenkgZG9ncy5UaGUgcXVpY2sgYnJvd24gZm94IA==",
126+
"cca-realm-initial-measurement": "MRMUq3NiA1DPdYg0rlxl2ejC3H/r5ufZZUu+hk4wDUk=",
127+
"cca-realm-extensible-measurements": [
128+
"JNWwopbMBcvYBoxQZ8W9Rzt3Ddpq4IL+O6MKvj+aarE=",
129+
"eI/AkL/GuO2QMVK6hBTnPa9bjHux55rVAqsGmbZZ7RY=",
130+
"2sRqWEFdw6ANenQYUgCOnK5k9S0DufdtdvSzZE/vxBY=",
131+
"MsavxiflVYXAMVU1nzMaDiJfaEDblH3Zbvq4G+JnGTk="
132+
],
133+
"cca-realm-hash-algo-id": "sha-256",
134+
"cca-realm-public-key": "BHb5iAkb5YXtQYAa7Pq4WFSMYwV+FrDmdhILvQ0vnCngVsXUGgEw65whUXiZ3CMUayjhsGK9PqSzFf0hnxy7Uoy250ykm+Fnc3NPYaHKYQMbK789kY8vlP/EIo5QkZVErg==",
135+
"cca-realm-public-key-hash-algo-id": "sha-256"
136+
}
137+
}
138+
```
139+
140+
It is not important to understand every detail of the attestation token right now, but here are some of the most important highlights:
141+
142+
- 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.
143+
- Specific variants of the EAT format are known as profiles, so this token is adopting the Arm CCA profile of the EAT specification.
144+
- 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.
145+
- 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.
146+
- 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.
147+
- 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.
148+
- The claims of the platform token are labelled with the prefix `cca-platform-*`
149+
- The claims of the realm token are labelled with the prefix `cca-realm-*`
150+
- 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.
151+
152+
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.
153+
154+
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.
155+
156+
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‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Use the verification service
3+
weight: 5
4+
5+
### FIXED, DO NOT MODIFY
6+
layout: learningpathall
7+
---
8+
9+
## Attestation Verification Service for Pre-Silicon CCA Platforms
10+
[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.
11+
12+
Linaro’s verification service is implemented using components from the open source [Veraison](https://github.com/veraison) project.
13+
14+
The URL for reaching this experimental verifier service is http://veraison.test.linaro.org:8080
15+
16+
To check that you can reach the Linaro attestation verifier service, run the following command:
17+
18+
```bash
19+
curl http://veraison.test.linaro.org:8080/.well-known/veraison/verification
20+
```
21+
22+
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:
23+
24+
```output
25+
{
26+
"ear-verification-key": {
27+
"alg": "ES256",
28+
"crv": "P-256",
29+
"kty": "EC",
30+
"x": "usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8",
31+
"y": "IBOL-C3BttVivg-lSreASjpkttcsz-1rb7btKLv8EX4"
32+
},
33+
"media-types": [
34+
"application/vnd.parallaxsecond.key-attestation.tpm",
35+
"application/eat-cwt; profile=\http://arm.com/psa/2.0.0\",
36+
"application/eat+cwt; eat_profile=\"tag:psacertified.org,2023:psa#tfm\"",
37+
"application/eat-collection; profile=\http://arm.com/CCA-SSD/1.0.0\",
38+
"application/eat+cwt; eat_profile=\"tag:psacertified.org,2019:psa#legacy\"",
39+
"application/vnd.enacttrust.tpm-evidence",
40+
"application/vnd.parallaxsecond.key-attestation.cca",
41+
"application/psa-attestation-token",
42+
"application/pem-certificate-chain"
43+
],
44+
"version": "commit-2063e7e",
45+
"service-state": "READY",
46+
"api-endpoints": {
47+
"newChallengeResponseSession": "/challenge-response/v1/newSession"
48+
}
49+
}
50+
```
51+
52+
This JSON response contains all the information that you need to use the verification service. Review the different JSON properties.
53+
54+
- The `ear-verification-key` is the cryptographic key that you will use later to verify the results that are returned by the service.
55+
56+
- 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.
57+
58+
- 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.
59+
60+
If you can reach the verification service, you are now ready to use it to evaluate the CCA example token.
61+
62+
## Save the Public Key of the Verification Service
63+
64+
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.
65+
66+
The easiest way to do this is to use the `jq` utility.
67+
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`:
68+
69+
```bash
70+
curl -s -N http://veraison.test.linaro.org:8080/.well-known/veraison/verification | jq '."ear-verification-key"' > $HOME/pkey.json
71+
```
72+
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.
73+
74+
## Submit the CCA Example Token to the Verification Service
75+
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:
76+
77+
```bash
78+
export API_SERVER=http://veraison.test.linaro.org:8080/challenge-response/v1/newSession
79+
```
80+
81+
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`:
82+
83+
```bash
84+
./evcli cca verify-as relying-party --token $HOME/cca_example_token.cbor | tr -d \" > $HOME/attestation_result.jwt
85+
```
86+
87+
{{% notice Note%}}
88+
The `| tr -d \"` is used to remove the double quotes in capturing the output from the `evcli` command.
89+
{{% /notice %}}
90+
91+
The verification service has now evaluated the token and returned a result, which you have saved.
92+
The last two steps in this learning path will be about understanding the result data that came back from the verification service.

0 commit comments

Comments
 (0)