Skip to content

Commit 9ba65de

Browse files
tylerfanellitylerfanelli
committed
123_verifier_evidence_types
1 parent 3821211 commit 9ba65de

File tree

1 file changed

+197
-0
lines changed

1 file changed

+197
-0
lines changed

‎123_verifier_evidence_types.md

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
<!--
2+
**Note:** When your enhancement is complete, all of these comment blocks should be removed.
3+
4+
To get started with this template:
5+
6+
- [ ] **Create an issue in keylime/enhancements**
7+
When filing an enhancement tracking issue, please ensure to complete all
8+
fields in that template. One of the fields asks for a link to the enhancement. You
9+
can leave that blank until this enhancement is made a pull request, and then
10+
go back to the enhancement and add the link.
11+
- [ ] **Make a copy of this template.**
12+
name it `NNNN-short-descriptive-title`, where `NNNN` is the issue number (with no
13+
leading-zero padding) assigned to your enhancement above.
14+
- [ ] **Fill out this file as best you can.**
15+
At minimum, you should fill in the "Summary", and "Motivation" sections.
16+
These should be easy if you've preflighted the idea of the enhancement with the
17+
appropriate SIG(s).
18+
- [ ] **Merge early and iterate.**
19+
Avoid getting hung up on specific details and instead aim to get the goals of
20+
the enhancement clarified and merged quickly. The best way to do this is to just
21+
start with the high-level sections and fill out details incrementally in
22+
subsequent PRs.
23+
-->
24+
# enhancement-x: Verifier Evicende Types
25+
26+
<!-- toc -->
27+
- [Release Signoff Checklist](#release-signoff-checklist)
28+
- [Summary](#summary)
29+
- [Motivation](#motivation)
30+
- [Goals](#goals)
31+
- [Non-Goals](#non-goals)
32+
- [Proposal](#proposal)
33+
- [User Stories)](#user-stories)
34+
- [Story 1](#story-1)
35+
- [Story 2](#story-2)
36+
- [Notes/Constraints/Caveats](#notesconstraintscaveats)
37+
- [Risks and Mitigations](#risks-and-mitigations)
38+
- [Design Details](#design-details)
39+
- [Test Plan](#test-plan)
40+
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
41+
- [Drawbacks](#drawbacks)
42+
- [Alternatives](#alternatives)
43+
<!-- /toc -->
44+
45+
## Release Signoff Checklist
46+
47+
- [ ] Enhancement issue in release milestone, which links to pull request in [keylime/enhancements]
48+
- [ ] Core members have approved the issue with the label `implementable`
49+
- [ ] Design details are appropriately documented
50+
- [ ] Test plan is in place
51+
- [ ] User-facing documentation has been created in [keylime/keylime-docs]
52+
53+
## Summary
54+
55+
This enhancement builds on the [Verification API enhancement](https://github.com/keylime/enhancements/blob/master/121-verification-api.md) to also allow for TEE evidence types to be evaluated with the Verification API. This will allow the Keylime Verifier the ability to attest TEE evidence as well as TPM evidence.
56+
57+
## Motivation
58+
59+
With the desire to allow for Keylime to also attest TEE evidence, there will be a requirement for different evidence types for the Verification API. Under TEE protections, an agent or third-party *could* send one or more of the following example evidence types for evaluation by the Verifier:
60+
61+
- TPM attestation data + CA certificate chain
62+
- SEV-SNP attestation report + CA certificate chain
63+
- Intel TDX attestation report + CA certificate chain
64+
- Confidential device (GPU, hardware RNG, etc) attestation data
65+
- etc...
66+
67+
This essentially will allow the Keylime Verifier to also begin to take on the role of a RATS Verifier (Described in section 7.4 of the [RATS RFC](https://datatracker.ietf.org/doc/rfc9334/)).
68+
69+
### Goals
70+
71+
We want to achieve the following goals:
72+
73+
* Allow TEE evidence to be interpreted by the Verifier alongside TPM evidence.
74+
* Prepare the Keylime Agent and Verifier for the addition of TEE evaluation plugins.
75+
76+
### Non-Goals
77+
78+
The following are not goals for this enhancement:
79+
80+
* Give Keylime full RATS capabilities complete with secret storage, etc. We only intend for Keylime to be able to attest TEE evidence and report results, just as it does with TPM evidence currently.
81+
82+
## Proposal
83+
84+
The Verification API defines the following payload for TPM evidence (at present, the only supported evidence type). This JSON payload will be sent to the `/verify` API:
85+
86+
{
87+
"quote": quote,
88+
"nonce": nonce,
89+
"hash_alg": hash_alg,
90+
"tpm_ek": ek,
91+
"tpm_ak": ak,
92+
"tpm_policy": tpm_policy,
93+
"runtime_policy": runtime_policy,
94+
"mb_policy": mb_policy,
95+
"ima_measurement_list": ima_measurement_list,
96+
"mb_log": mb_log,
97+
}
98+
99+
The payload will take the following data fields:
100+
101+
* quote - a TPM quote (required)
102+
* nonce - a client create nonce (required)
103+
* hash_alg - the hashing algorithm used for the TPM. Must be standard algorithm supported by Keylime (required)
104+
* tpm_ek - The public EK certificate of the TPM (required)
105+
* tpm_ak - The public AK certificate of the TPM (required)
106+
* tpm_policy - A JSON TPM policy in a format supported by Keylime (optional)
107+
* runtime_policy - A JSON Runtime policy in a format supported by Keylime (optional)
108+
* mb_policy - A Measured Boot policy in a format supported by Keylime (optional)
109+
* ima_measurement_list - The ASCII contents of the IMA measurement file (optional)
110+
* mb_log - The contents of the boot log (optional)
111+
112+
This is strictly for TPM evidence, as the Keylime Verifier cannot interpret any other evidence formats at present. This proposal intends to extend this payload to also include TEE evidence types interpreted by the verifier. This can be done by specifying the evidence type as a header, and parsing the payload data accordingly. For this previous example, the TPM evidence format would be specified by the following:
113+
114+
{
115+
"type": "tpm", // TPM evidence type.
116+
"data": {
117+
"quote": quote,
118+
"nonce": nonce,
119+
"hash_alg": hash_alg,
120+
"tpm_ek": ek,
121+
"tpm_ak": ak,
122+
"tpm_policy": tpm_policy,
123+
"runtime_policy": runtime_policy,
124+
"mb_policy": mb_policy,
125+
"ima_measurement_list": ima_measurement_list,
126+
"mb_log": mb_log,
127+
}
128+
}
129+
130+
The verifier would read the `type` parameter to be `tpm` (indicating TPM evidence) and parse the data accordingly. This could be further extended to also include SEV-SNP attestation evidence like so:
131+
132+
{
133+
"type": "sev-snp", // SEV-SNP evidence type.
134+
"data": {
135+
"attestation_report": attestation_report,
136+
"vcek": vcek,
137+
"ca_chain": ca_chain,
138+
}
139+
}
140+
141+
This payload will include the following data fields:
142+
143+
* attestation_report: SEV-SNP attestation report (required)
144+
* vcek: SEV-SNP Versioned Chip Endorsement Key (optional)
145+
* ca_chain: SEV-SNP processor CA chain (optional)
146+
147+
We would also intend for Intel TDX and ARM CCA evidence types as well. We have provided example evidence format for the example.
148+
149+
Users may also like to send *multiple* unique evidences to the Verifier for evaluation at one time. For example, to monitor both the TPM data as well as the SEV-SNP launch environment (for live migration scenarios, etc). To accommodate this, evidence being sent can also be modified to be a *list* of separate evidence formats like so:
150+
151+
[
152+
{
153+
"type": "tpm", // TPM evidence type.
154+
"data": {
155+
"quote": quote,
156+
"nonce": nonce,
157+
"hash_alg": hash_alg,
158+
"tpm_ek": ek,
159+
"tpm_ak": ak,
160+
"tpm_policy": tpm_policy,
161+
"runtime_policy": runtime_policy,
162+
"mb_policy": mb_policy,
163+
"ima_measurement_list": ima_measurement_list,
164+
"mb_log": mb_log,
165+
}
166+
},
167+
{
168+
"type": "sev-snp", // SEV-SNP evidence type.
169+
"data": {
170+
"attestation_report": attestation_report,
171+
"vcek": vcek,
172+
"ca_chain": ca_chain,
173+
}
174+
}
175+
]
176+
177+
### User Stories
178+
179+
#### Story 1
180+
181+
A SEV-SNP encrypted guest requires evidence verification to unlock some vTPM state and begin running its guest OS. The VM's firmware (running SVSM) will send its evidence to the Verification API and get a result back based on evaluation. Upon a successful result, SVSM will present the signed results from the Keylime Verifier to a key broker service (not part of Keylime) and get a secret to unlock its vTPM state.
182+
183+
#### Story 2
184+
185+
A SEV-SNP encrypted guest has already booted and is running the Keylime Agent. To continously monitor/verify its TEE environment in case of live migrations, it will continuously send its TEE attestation evidence alongside its TPM evidence.
186+
187+
### Notes/Constraints/Caveats
188+
189+
* This proposal only defines the subsequent header and message types that will determine the type of format in which to interpret different evidence types. It does not include the Verifier changes to actually perform the validation of TEE evidence. This modification will be a separate proposal to add Verification "plugins" for the actual evaluation of these messages at a later point.
190+
191+
## Design Details
192+
193+
* The Keylime Agent and Verifier will require specific types and {de}serialization methods to parse the specific evidence they send and receive to/from each other.
194+
195+
### Test Plan
196+
197+
* Tests including a combination of TPM and TEE evidence JSON payloads to ensure correct {de}serialization of these evidence types can be added.

0 commit comments

Comments
 (0)