Skip to content

Commit 300623b

Browse files
Xynnn007Xynnn007
committed
Spec: spec for AAEL and CoCo Event Types
AAEL event log is what we are using in Attestation Agent and Attestation Services, which leverages the TEE runtime measurement ability (like TDX) to record events. Beyond CoCo, AAEL could also provide ability to record events in post-OS stage. To make the event format more public, we put this RFC in CoCo. Signed-off-by: Xynnn007 <[email protected]> Signed-off-by: Yunge Zhu <[email protected]>
1 parent 8565e7f commit 300623b

File tree

1 file changed

+174
-0
lines changed

1 file changed

+174
-0
lines changed

‎kbs/docs/confidential-containers-eventlog.md

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# Specification for Attestation Agent Event Log
2+
3+
## Introduction
4+
5+
The [Confidential Computing Eventlog (CCEL)](https://uefi.org/specs/UEFI/2.11/38_Confidential_Computing.html) framework plays a crucial role in establishing trust during the OS boot-up phase, ensuring that foundational system components are verified for integrity and security. It's based on `EFI_TCG2_EVENT_LOG_FORMAT_TCG_2` format (a.k.a `Crypto Agile Log Entry Format`) specified by [TCG EFI Protocol Specification (Section 5.2)](https://trustedcomputinggroup.org/wp-content/uploads/EFI-Protocol-Specification-rev13-160330final.pdf) and [TCG PC Client Platform Firmware Profile Specification (Section 9.2.2)](https://trustedcomputinggroup.org/wp-content/uploads/TCG_PCClient_PFP_r1p05_05_3feb20.pdf). It provides detailed event types covering pre-OS events. To further extend this trust beyond the boot process, the Attestation Agent Eventlog (AAEL) format is introduced to provide comprehensive measurement capabilities for the post-OS phase. The AAEL framework is designed with scalability in mind, allowing broad support for numerous types of measurement events, including memory operations, network transactions, filesystem activities, and container-related processes.
6+
7+
AAEL can be seamlessly integrate into `EFI_TCG2_EVENT_LOG_FORMAT_TCG_2`, enriching the existing event logging framework and providing a holistic approach to security and integrity in computing environments. Ideally, AAEL would be embedded into the Kernel-maintained Eventlog, allowing for a unified logging system. However, the Kernel community has not yet provided clear guidance on whether future versions will support Eventlog and what format they might adopt, whether it be TCG2 or another format[1]. Given this uncertainty, we are currently presenting the AAEL format independently. Decisions regarding how it will be stored within the underlying Eventlog will be addressed during implementation as more information becomes available. Because of these reasons, parts of this specification are subject to change or to be removed.
8+
9+
## Architecture
10+
11+
The architecture supporting AAEL seamlessly integrates with existing confidential computing systems,
12+
providing a robust event logging and verification framework above the kernel level within CVMs. The [Attestation Agent (AA)](https://github.com/confidential-containers/guest-components/tree/main/attestation-agent) is integral to this process, recording events within the AAEL framework and securely binding logs to hardware runtime measurement registers.
13+
14+
It receives logging requests from system components.
15+
16+
These callers record events following the spec-defined AAEL Event, ensuring consistency and reliability in log data.
17+
18+
Trustee [CoCo Attestation Service (CoCo AS)](https://github.com/confidential-containers/trustee/tree/main/attestation-service) offers a flexible platform for processing AAEL logs in a generalized manner, ensuring compatibility with various confidential computing environments for diverse event verification.
19+
Furthermore, AS can conduct detailed analysis and enforce policies for AAEL events, utilizing the AAEL Event Spec for precise validation and scrutiny. This capability supports the development and execution of advanced security policies, enhancing the appraisal of the VM state.
20+
21+
```
22+
23+
┌─────────────────────────────────────┐
24+
│ │
25+
│ ┌────────────────┐ │
26+
│ │System Component│ │
27+
│ └───────┬────────┘ │
28+
│ │ │
29+
│ │ │
30+
│ │ │
31+
│ ┌──────────▼──────────┐ │ ┌─────────────────────┐
32+
│ │ │ │ │ │
33+
│ │ Attestation Agent ├───────┼─────►│ Attestation Service │
34+
│ │ │ │ │ │
35+
│ └───┬─────────┬───────┘ │ └─────────────────────┘
36+
│ │ │ │
37+
│ │ ▼ │
38+
│ Extend │ ┌──────┐ │
39+
│ │ │ AAEL │ │
40+
│ │ └──────┘ │
41+
│ ┌─────▼───────────────────┐ │
42+
│ │ Runtime Measurements/PCR│ │
43+
│ └─────────────────────────┘ │
44+
│ │
45+
│ Confidential VM │
46+
└─────────────────────────────────────┘
47+
```
48+
49+
In this specification, we provide detailed information on the Attestation Agent Event Log (AAEL) format in confidential computing scenarios.
50+
51+
## Specifications
52+
53+
AAEL is a specification for event logging over guest kernel level.
54+
55+
### Attestation Agent Event Log (AAEL)
56+
57+
1. Binding of AAEL with Dynamic Measurement Registers
58+
59+
Entries recorded by AAEL are bound to a specific register value that ensures the integrity of logged events. When AAEL is integrated into an established Eventlog framework, such as the `EFI_TCG2_EVENT_LOG_FORMAT_TCG_2`, updates to the underlying registers follow the guidelines of the Eventlog's specifications, typically using the `EVENT` field to store AAEL entry.
60+
61+
With each new event added, an extend operation is performed on the designated register. When the platform supports a (v)TPM interface, this register corresponds to the (v)TPM's PCR register. On platforms exclusively utilizing TEE, the PCR is mapped to a specific [confidential computing measurement register](https://uefi.org/specs/UEFI/2.11/38_Confidential_Computing.html#virtual-platform-cc-event-log) according to platform-specific rules. This mapping ensures AAEL's applicability in both TEE and non-TEE environments.
62+
63+
For scenarios where AAEL is directly stored in a RAW format, the digest of the AAEL entry is directly used to extend the designated register.
64+
65+
2. AAEL Log Entry Format
66+
67+
AAEL log entries consist of two types: Event Entry and INIT Entry.
68+
69+
__INIT Entry__ is recorded only once at the beginning of AAEL when AA first initializes, capturing the current value of a specific PCR, formatted as
70+
71+
```
72+
INIT/<hash-algorithm> <hex-digest>
73+
```
74+
Where,
75+
- `<hash-algorithm>`: may be `sha256`, `sha384`, or `sha512`.
76+
- `<hex-digest>` is the base16-encoded PCR register value. The length MUST be aligned with the `<hash-algorithm>`. Padding with zeros or truncation **MUST** be applied if necessary to align with the digest length.
77+
78+
__Event Entry__ records specific events in the format
79+
```
80+
<Domain> <Operation> <Content>
81+
```
82+
83+
Where,
84+
- `Domain`: **Required**. The event domain, **RECOMMENDED** to be a URI.
85+
- `Operation`: **Required**. The specific operation within the domain.
86+
- `Content`: **Required**. Detailed context of the operation.
87+
88+
Event Format Requirements
89+
90+
- Both the `Domain` and `Operation` fields **MUST NOT** contain any [white space characters](https://www.ascii-code.com/characters/white-space-characters)
91+
- All three fields **MUST** consist solely of [printable characters](https://www.ascii-code.com/characters/printable-characters).
92+
- The `Domain` and `Operation` fields are separated by a single Space (ASCII code `0x20`).
93+
- The `Operation` and `Content` fields are separated by a single Space (ASCII code `0x20`).
94+
- The `Content` field **MUST NOT** have any line feed character (LF, `\n`, ASCII code `0x0A`).
95+
- Each line in the AAEL **MUST** terminate with a line feed character (LF, `\n`, ASCII code `0x0A`) and **MUST NOT** include any additional carriage return characters (CR, `\r`, ASCII code `0x0D`).
96+
97+
The semantic meaning of the three fields is defined by the specific component that calls AA to record events.
98+
99+
3. Measurement API
100+
101+
The Attestation Agent must provide an API to support AAEL recording, enabling integration with existing event logging frameworks.
102+
103+
```proto
104+
// Extend the dynamic/runtime measurement with given materials. This would change the state
105+
// of current TEE's status, e.g. TDX's RTMR, (v)TPM's PCR, by adding a record in eventlog.
106+
message ExtendRuntimeMeasurementRequest {
107+
// The domain to which this event entry belongs. This domain is used to distinguish the semantics of log entries in different contexts.
108+
string Domain = 1;
109+
110+
// Concrete operation type that this event entry records.
111+
string Operation = 2;
112+
113+
// Detailed content of the operation that this event entry records.
114+
string Content = 3;
115+
116+
// Which PCR will be extended with the hash of this entry.
117+
optional uint64 RegisterIndex = 4;
118+
}
119+
```
120+
121+
By default, the `RegisterIndex` is set to `17` due to its role in supporting the dynamic root of trust for measurement. Notably, PCR `17` is not registered in [Linux TPM PCR Registry](https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/). Additionally, [TCG TRUSTED BOOT CHAIN IN EDK II](https://tianocore-docs.github.io/edk2-TrustedBootChain/release-1.00/3_TCG_Trusted_Boot_Chain_in_EDKII.html) specifies that __PCRs [17-22] represent the platform's dynamic root of trust for measurement (DRTM).__
122+
123+
### Confidential Containers Event Spec
124+
125+
The Confidential Containers Event Spec (CoCo Event Spec) builds upon the AAEL framework, specifying event types pertinent to the unique context of Confidential Containers.
126+
127+
This specification encompasses events closely tied to the lifecycle of Confidential Containers in guest. By focusing on these lifecycle events, the CoCo Event Spec ensures comprehensive monitoring and verification of critical container operations within secure computing environments.
128+
129+
```
130+
131+
┌─────────────────────────────────────┐
132+
│ │
133+
│ ┌────────────────────┐ │
134+
│ │ Kata-Agent/ASR/CDH │ │
135+
│ └──────────┬─────────┘ │
136+
│ │ │
137+
│ │ │
138+
│ │ │
139+
│ ┌──────────▼──────────┐ │ ┌─────────────────────┐
140+
│ │ │ │ │ │
141+
│ │ Attestation Agent ├───────┼─────►│ Attestation Service │
142+
│ │ │ │ │ │
143+
│ └───┬─────────┬───────┘ │ └─────────────────────┘
144+
│ │ │ │
145+
│ │ ▼ │
146+
│ Extend │ ┌──────┐ │
147+
│ │ │ AAEL │ │
148+
│ │ └──────┘ │
149+
│ ┌─────▼───────────────────┐ │
150+
│ │ Runtime Measurements/PCR│ │
151+
│ └─────────────────────────┘ │
152+
│ │
153+
│ Confidential VM │
154+
└─────────────────────────────────────┘
155+
```
156+
157+
It is designed to be a flexible and extensible format that can be used to represent a variety of events in a Confidential Container environment.
158+
The CoCo Event Spec is a concrete `Domain`, `Operation`, `Content` definition based on the AAEL specification.
159+
160+
CoCo events **MUST** have a `domain` set as `github.com/confidential-containers`.
161+
162+
The `Content` field **MUST** be a JSON.
163+
The `Content` JSON **MUST** be minified; it **MUST NOT** contain any [white space characters](https://www.ascii-code.com/characters/white-space-characters) that is not part of JSON field values.
164+
165+
Concrete supported `Operation`s and `Content`s are defined in the following table:
166+
| Operation | Content | Description | Content Example |
167+
| --- | --- | --- | --- |
168+
| `PullImage` | `{"image":"<image-reference>","digest":"<digest>:<hex>"}` | An image pulling event with image reference and manifest digest | `{"image":"alpine","digest":"sha256:0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0"}` |
169+
170+
It's welcomed to add more events by making PRs.
171+
172+
## References
173+
174+
[1] https://lore.kernel.org/linux-coco/[email protected]/T/#m086550ee8ca4d0127657ca8a467bf7cf170bfb74

0 commit comments

Comments
 (0)