Skip to content
This repository was archived by the owner on Apr 15, 2022. It is now read-only.

Commit 16d039f

Browse files
Connor Kuehlnpmccallum
Connor Kuehl
authored and
npmccallum
committed
Port documentation from enarx/enarx repo
Closes #17. The only modifications here are to fix links and remove the section stubs for Intel SGX and IBM PEF. Signed-off-by: Connor Kuehl <[email protected]>
1 parent 047cd07 commit 16d039f

7 files changed

+372
-0
lines changed

‎docs/attestation/README.md

+239
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# Attestation
2+
3+
Please note that attestation is a deeply technical process and readers
4+
should be familiar with some [prerequisite concepts](./prerequisites.md)
5+
before reading this document.
6+
7+
### Colors
8+
9+
In process diagrams, colors mean the following:
10+
11+
* Green: Implicitly Trusted
12+
* Red: Untrusted
13+
* Yellow: Trusted via a Cryptographic Root of Trust
14+
* Orange: Trusted via Cryptographic Measurement
15+
16+
In certificate chain diagrams, colors mean the following:
17+
18+
* Blue: The private key is accessable only by hardware.
19+
20+
The AMD SEV attestation process is a series of cryptographic transactions between a tenant (entity that wants a
21+
secure virtual machine) and a host (the entity that provides the virtual machine on their infrastructure).
22+
This attestation process establishes the following:
23+
24+
* A guarantee that the tenant's secure virtual machine (the guest) is running on an authentic AMD processor which
25+
correctly implements AMD's Secure Encrypted Virtualization (SEV) technology in microcode. This demonstrates
26+
that the host's processor is capable of supporting an SEV-enabled guest and the guest can be assured it is
27+
receiving the protections advertised by the SEV featureset once attestation is complete.
28+
* A guarantee that the platform that tenant's virtual machine will be running on is actually owned by the host.
29+
* The host-provided virtual machine image matches exactly what the tenant is expecting. That is, both the tenant
30+
and the host calculate the same measurement of the image.
31+
* A secure channel to inject a secret (or secrets) into the encrypted guest so that its workload is entirely
32+
private and known only to the guest itself.
33+
34+
AMD SEV seeks to provide these guarantees even with the presence of a potentially hostile or compromised host.
35+
36+
#### Establishing Trust
37+
38+
The public-key cryptography employed in the attestation for AMD SEV forms a tree-like structure that can be traced
39+
all the way back to two roots of trust (an authoritative, completely trusted entity):
40+
41+
![amd sev cert chain](./certchain.dot.png)
42+
43+
The above diagram illustrates the two roots of trust from which two chains of trust are established, each terminating
44+
at the Platform Diffie-Hellman (PDH) node at the bottom. This relationship is important because it shows how trust
45+
is traced back to what is known as a "root of trust", or in other words: a completely trusted, authoritative entity.
46+
For AMD SEV, the roots of trust are Advanced Micro Devices (AMD) and the owner of the platform (the entity providing
47+
the host or a group of hosts). A chain of trust is formed when a trusted entity uses its key to sign another entity's
48+
key. When an entity's key is signed by a trusted entity, then the newly-signed key is also trusted.
49+
50+
Let's step through the two chains of trust shown in the above diagram:
51+
52+
The first root of trust is the **Owner Certificate Authority (OCA) signing key**. The OCA is exclusively owned
53+
by the owner of the platform (the entity that provides the host). It is used to sign the Platform Endorsement Key
54+
(PEK) to indicate that the owner controls the platform. The only exception to this is if the platform is considered
55+
"self-owned". In this case, the SEV firmware will generate both the public and private OCA keys and store them. The
56+
"self-owned" state is the default state.
57+
58+
The second root of trust is the **AMD Root Key (ARK)**. The ARK is used to sign the AMD SEV Signing Key (ASK) to mark
59+
it as an authentic AMD key in the chain of trust. The ARK is an offline key, carefully protected and controlled by
60+
AMD. This key is used to sign the AMD Signing Key (ASK), which is online.
61+
62+
The **AMD SEV Signing Key (ASK)** is signed by the ARK and is therefore branded as an authentic and trusted AMD key.
63+
This key is used to sign the Chip Endorsement Key (CEK).
64+
65+
The **Chip Endorsement Key (CEK)** is a unique key stored within the fuses of the chip itself. This key is signed by
66+
the ASK to officially associate the processor with the AMD chain of trust. The ASK's signature indicates that the chip
67+
is an authentic AMD processor. This key is signed during provisioning, a process by which a platform owner takes
68+
control over the platform. The platform owner exports this key, submits a POST request to an online service, and
69+
AMD returns the key with an ASK signature on it.
70+
71+
The two chains of trust intersect at the **Platform Endorsement Key (PEK)** which is signed by both the OCA and the
72+
CEK. This means that the PEK derives trust from both roots of trust: AMD and the platform owner. Any key signed by
73+
the PEK is considered to be trusted by both the platform owner and AMD. This key is generated by the SEV firmware
74+
(the software that controls the Platform Secure Processor).
75+
76+
Finally, the chain of trust terminates at the aforementioned **Platform Diffie-Hellman (PDH)** key. This key is used
77+
to enable a key exchange between the PSP firmware and the tenant to create a master key.
78+
79+
#### Attestation Overview
80+
81+
1. **Validation:** Tenant will validate the certificate chain (described above) provided by the host.
82+
83+
1. **Secure Channel Establishment:** Tenant and Platform Secure Processor (PSP) will negotiate an encrypted channel.
84+
85+
1. **Measurement:** Tenant will validate the measurement of the VM provided by the PSP.
86+
87+
1. **Launch:** Attestation is successful. The tenant will inject secrets into the guest and the guest is launched.
88+
89+
#### Performing Attestation
90+
91+
Now let's examine how the keys are used in practice to perform attestation and safely establish the guarantees that
92+
were described earlier in the document with a tenant.
93+
94+
First, have a quick look at the following diagram, then we'll unpack it:
95+
96+
![amd sev process](./process.msc.png)
97+
98+
##### Validation
99+
100+
1. To begin, the tenant will ask the host for the certificate chain. The host will route this request to the PSP which
101+
will export the certificate chain. The certificate chain is the chain of trust that can be traced all the way to
102+
the two roots of trust described above. The PSP's response contains the certificate chain and the firmware version
103+
that drives the PSP. The host will relay this response to the tenant.
104+
105+
1. The tenant will verify the certificate chain. The components of the AMD signing keys can be obtained individually
106+
to confirm the authenticity of the signatures on the certificate. Similarly, the owner's signature on the PEK
107+
derived from the OCA can be used to verify that the expected owner is in control of the platform.
108+
109+
1. The tenant will verify the firmware version advertised by the PSP. Some SEV features are only available in certain
110+
firmware revisions.
111+
112+
1. The tenant will build an execution policy. The execution policy contains configuration information. For example:
113+
requiring SEV-ES support, disabling the ability to transmit the guest to another platform, or a minimum firmware
114+
version. This policy will be delivered to the PSP in a secure channel, which will be established next.
115+
116+
##### Secure Channel Establishment
117+
118+
1. The tenant will create a trusted channel between itself and the PSP to facilitate attestation:
119+
120+
1. The tenant generates a random Transport Integrity Key ("tik") and random Transport Encryption Key ("tek").
121+
122+
1. The tenant already has the host's Platform Diffie-Hellman (PDH) key from the certificate chain it requested.
123+
124+
1. The tenant generates its own random Elliptic Curve Diffie-Hellman (ECDH) key pair.
125+
126+
1. The tenant derives a shared secret ("Z") from its own PDH and the host's PDH.
127+
128+
1. The tenant generates a random nonce ("N").
129+
130+
1. The tenant generates a random initialization vector ("IV").
131+
132+
1. The tenant derives the master key ("M") from the shared secret ("Z") and the nonce ("N") and from the string
133+
"sev-master-secret".
134+
135+
1. The tenant derives a Key Encryption Key ("kek") from the master key and the string "sev-kek".
136+
137+
1. The tenant derives a Key Integrity Key ("kik") from the master key and the string "sev-kik".
138+
139+
1. The tenant concatenates the Transport Encryption Key ("tek") and the Transport Integrity Key ("tik") and wraps
140+
the result with the Key Encryption Key ("kek"), which is then wrapped by the Key Integrity Key ("kik").
141+
142+
1. The Key Integrity Key ("kik") is used to hash and sign the wrapped data with HMAC-SHA256, seeded from the
143+
initialization vector ("IV").
144+
145+
1. The Transport Integrity Key ("tik") is used to hash and sign (HMAC-SHA256) the guest's execution policy that
146+
was crafted above.
147+
148+
1. Finally, the tenant has prepared everything that is required to establish a secure channel between itself
149+
and the PSP. The tenant will transmit the following to the host (which will relay it to the PSP): the
150+
tenant's PDH public key, the TIK-protected policy, KIK-protected KEK (TEK, TIK), the nonce ("N"), the
151+
initialization vector ("IV"). This is everything the PSP needs to securely derive its own understanding
152+
of the shared secret and decrypt the buffers. This initiates attestation and foreshadows a virtual machine
153+
launch.
154+
155+
| transmitted as | component |
156+
| --------------: | - |
157+
| plaintext | N, IV, tenant's PDH (public key) |
158+
| ciphertext | (KEK: TEK\|TIK) |
159+
| integrity-protected | (TIK: guest policy), (KIK: KEK) |
160+
161+
1. The PSP will receive the tenant's request for a secure channel and decrypt it.
162+
163+
1. The PSP will use the nonce ("N"), its PDH and the tenant's PDH to derive the shared secret ("Z") that the
164+
tenant had derived.
165+
166+
1. The PSP will derive the master secret ("M") using the shared secret it had just derived.
167+
168+
1. The PSP will derive the Key Encryption Key ("kek") and the Key Integrity Key ("kik") from the master
169+
key ("M").
170+
171+
1. The PSP will decrypt the KIK-protected buffer sent by the tenant which contains the KEK (which itself wraps
172+
around the concatenated TEK and TIK data).
173+
174+
1. The PSP will decrypt the KEK-wrapped buffer to reveal the TEK/TIK concatenated buffer.
175+
176+
##### Measurement
177+
178+
1. The PSP will create an SEV context for the tenant's virtual machine (guest) and begin bootstrapping an encrypted
179+
environment for the it.
180+
181+
1. The PSP will use the TIK to decrypt the policy and associate the policy with the guest for the entirety
182+
of its lifetime.
183+
184+
1. The PSP will create a cryptographic measurement of the pages provided by the host.
185+
186+
1. The PSP will encrypt the guest's pages.
187+
188+
1. The PSP will use the TIK to hash and sign the measurement it took of the pages prior to encryption and
189+
send this reply to the host which then routes it to the tenant.
190+
191+
| transmitted as | component |
192+
| --------------: | - |
193+
| integrity-protected | (TIK: measurement) |
194+
195+
1. The tenant will digest the response from the PSP containing the measurement of the virtual machine image.
196+
197+
1. The tenant will perform its own measurement of the pages. If it calculates the same measurement, then the image is
198+
exactly what the tenant was expecting. If not, attestation has failed, and the tenant should assume the image has
199+
been tampered with.
200+
201+
##### Launch
202+
203+
1. If the tenant agrees with the PSP's measurement of the pages, the guest is now ready to securely receive any
204+
secret metadata.
205+
206+
1. The tenant will generate a new initialization vector ("IV") to seed AES-128 encryption used to protect
207+
the transmission of the secret.
208+
209+
1. The secret will be encrypted with AES 128 using the TEK to calculate the ciphertext.
210+
211+
1. The secret ciphertext will be hashed and signed by the TIK with HMAC-SHA256.
212+
213+
1. The tenant will send the encrypted metadata (secret) to the host which will then relay it to the PSP.
214+
215+
| transmitted as | component |
216+
| --------------: | - |
217+
| ciphertext | (TEK: secret metadata) |
218+
| integrity-protected | (TIK: TEK) |
219+
220+
1. The PSP will decrypt the ciphertext containing the secret and place it into the guest's memory.
221+
222+
1. Finally, attestation has successfully concluded and the virtual machine's launch is complete. The virtual
223+
machine is now ready to run under the protection of AMD SEV.
224+
225+
Please note that attestation for SEV-ES and SEV-SNP will be documented at a later date.
226+
227+
#### Protections
228+
229+
After attestation completes successfully, a guest is assured to receive [a number of protections](
230+
./protections.md).
231+
232+
#### References
233+
234+
This document relies on a number of resources to accurately summarize the deeply technical process of attestation.
235+
Please note that **this document will defer to AMD's official documentation if any component here is found to be in
236+
disagreement with the AMD SEV's documentation.** If a discrepency is found, please reach out to file an issue and/or
237+
open a pull request to notify the Enarx team. Your assistance is sincerely appreciated.
238+
239+
* [AMD Secure Encrypted Virtualization (SEV) API, revision 0.22](https://developer.amd.com/wp-content/resources/55766.PDF)

‎docs/attestation/certchain.dot

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Commits which modify this file MUST generate the new .png!
2+
digraph G {
3+
node [style=filled];
4+
5+
node [fillcolor=blue, fontcolor=white];
6+
CEK;
7+
8+
node [fillcolor=none, fontcolor=black];
9+
ARK -> ASK;
10+
ASK -> CEK;
11+
CEK -> PEK;
12+
PEK -> PDH;
13+
OCA -> PEK;
14+
}

‎docs/attestation/certchain.dot.png

20.3 KB
Loading

‎docs/attestation/prerequisites.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Prerequisites
2+
3+
Attestation is built on a number of technical concepts. Readers should familiarize
4+
themselves with the following topics:
5+
6+
* [Public-key Cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography)

‎docs/attestation/process.msc

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Commits which modify this file MUST generate the new .png!
2+
msc {
3+
tenant [textbgcolor="green"],
4+
host [textbgcolor="red"],
5+
bios [textbgcolor="orange"],
6+
bootloader [textbgcolor="orange"],
7+
kernel [textbgcolor="orange"],
8+
psp [textbgcolor="yellow"];
9+
10+
tenant=>host [label="cert chain request"];
11+
host=>psp [label="cert chain request"];
12+
psp=>host [label="cert chain reply\n(w/ firmware version)"];
13+
host=>tenant [label="cert chain reply\n(w/ firmware version)"];
14+
15+
...;
16+
17+
tenant box tenant [label="validate cert chain"];
18+
tenant box tenant [label="validate fw version"];
19+
tenant box tenant [label="craft exec policy"];
20+
tenant box tenant [label="random cdh keypair"];
21+
tenant box tenant [label="random tek/tik"];
22+
23+
24+
tenant box tenant [label="DH(cdh, pdh) => z"];
25+
tenant box tenant [label="KDF(z) => master"];
26+
tenant box tenant [label="KDF(master) => kek"];
27+
tenant box tenant [label="KDF(master) => kik"];
28+
29+
tenant => host [label="CDH, MAC(tik, policy),\nMAC(kik, ENC(kek, tek||tik))"];
30+
host => psp [label="CDH, MAC(tik, policy),\nMAC(kik, ENC(kek, tek||tik))"];
31+
32+
psp box psp [label="DH(cdh, pdh) => z"];
33+
psp box psp [label="KDF(z) => master"];
34+
psp box psp [label="KDF(master) => kek"];
35+
psp box psp [label="KDF(master) => kik"];
36+
37+
psp box psp [label="check MAC(kik, ...)"];
38+
psp box psp [label="DEC(kek, tek||tik)"];
39+
40+
host => psp [label="guest pages"];
41+
psp box psp [label="measure guest pages"];
42+
43+
psp => host [label="MAC(tik, measurement)"];
44+
host => tenant [label="MAC(tik, measurement)"];
45+
46+
tenant box tenant [label="validate measure"];
47+
tenant box tenant [label="prepare metadata"];
48+
tenant => host [label="enc = ENC(tek, metadata)\nMAC(tik, enc)"];
49+
host => psp [label="enc = ENC(tek, metadata)\nMAC(tik, enc)"];
50+
51+
psp => bios [label="decrypt metadata into guest memory"];
52+
53+
--- [label="VM START"];
54+
55+
bios => bootloader [label="metadata"];
56+
bootloader => kernel [label="metadata"];
57+
kernel box kernel [label="unlock volume"];
58+
59+
--- [label="BOOT COMPLETE"];
60+
}

‎docs/attestation/process.msc.png

74.9 KB
Loading

‎docs/attestation/protections.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Protections
2+
3+
An SEV-enabled guest will be protected from a number of potential threats.
4+
5+
These threats are broadly categorized like so:
6+
7+
**Confidentiality**: Anything that could disclose and/or read the contents of the virtual machine without
8+
its explicit permission is a threat to the virtual machine's confidentiality.
9+
10+
**Integrity**: The virtual machine must always see the data that it last wrote. If this invariant is broken,
11+
then the integrity of the virtual machine is compromised.
12+
13+
**Physical Access Attacks**: An attacker with a substantial level of access to the physical hardware may use
14+
this access to conduct attacks on the system and virtual machines running on it.
15+
16+
**Miscellaneous**: An attack which doesn't fit in as nicely to any of the other above categories.
17+
18+
Table legend:
19+
20+
* :heavy\_check\_mark:: indicates that this attack is thwarted by an SEV feature.
21+
22+
* :star2:: indicates that this mitigation may be optionally enabled.
23+
24+
* : an empty cell indicates that the attack is *not* mitigated by that technology.
25+
26+
| **Confidentiality** | **SEV** | **SEV-ES** | **SEV-SNP** |
27+
| ------------------: | :-----: | :--------: | :---------: |
28+
| VM Memory (*ex: Hypervisor reads private VM memory*) | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: |
29+
| VM Register State (*ex: Hypervisor attempts to read VM register context*) | | :heavy\_check\_mark: | :heavy\_check\_mark: |
30+
| DMA Protection (*ex: Device attempts to read VM memory*) | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: |
31+
| **Integrity** | **SEV** | **SEV-ES** | **SEV-SNP** |
32+
| Replay Protection (*ex: VM memory is replaced with an old copy*) | | | :heavy\_check\_mark: |
33+
| Data Corruption (*ex: VM memory is replaced with junk data*) | | | :heavy\_check\_mark: |
34+
| Memory Aliasing (*ex: Hypervisor maps two guest pages to same DRAM page*) | | | :heavy\_check\_mark: |
35+
| Memory Re-mapping (*ex: Hypervisor switches DRAM page mapped to a guest page*) | | | :heavy\_check\_mark: |
36+
| **Availability** | **SEV** | **SEV-ES** | **SEV-SNP** |
37+
| Guest to Host Denial of Service (*ex: Guest refuses to yield/exit*) | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: |
38+
| Host to Guest Denial of Service (*ex: Host refuses to run guest*) | | | |
39+
| **Physical Access Attacks** | **SEV** | **SEV-ES** | **SEV-SNP** |
40+
| Offline DRAM analysis (*ex: Cold boot*) | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: |
41+
| Active DRAM corruption (*ex: Manipulate DDR bus while VM is running*) | | | |
42+
| **Miscellaneous Attacks** | **SEV** | **SEV-ES** | **SEV-SNP** |
43+
| TCB Rollback (*ex: AMD-SP firmware is reverted to older version*) | | | :heavy\_check\_mark: |
44+
| Malicious Interrupt/Exception Injection (*ex: interrupt injected while RFLAGS.IF=0*) | | | :star2: |
45+
| Indirect Branch Predictor Poisoning (*ex: Poison BTB from hypervisor*) | | | :star2: |
46+
| Secure Hardware Debug Registers (*ex: Breakpoints changed during debugging*) | | | :star2: |
47+
| Trusted CPUID Information (*ex: Hypervisor lies about platform capabilities*) | | | :star2: |
48+
| Architectural Side Channels (*ex: PRIME+PROBE to track VM accesses*) | | | |
49+
| Page-level Side Channels (*ex: Track VM access patterns through page tables*) | | | |
50+
| Performance Counter Tracking (*ex: Fingerprint VM workloads by performance data*) | | | |
51+
52+
*The table above was taken directly from the [AMD SEV-SNP Whitepaper (Table 1: Threat Model)](
53+
https://www.amd.com/system/files/TechDocs/SEV-SNP-strengthening-vm-isolation-with-integrity-protection-and-more.pdf).*

0 commit comments

Comments
 (0)