Skip to content

Commit 9a132cb

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 9a132cb

File tree

1 file changed

+142
-0
lines changed

1 file changed

+142
-0
lines changed

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

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Specification for Attestation Agent Event Log
2+
3+
## Introduction
4+
5+
The Attestation Agent Eventlog ([AAEL](https://github.com/confidential-containers/guest-components/issues/495)) are introduced to address limitations in existing logging frameworks such as [Confidential Computing Eventlog (CCEL)](https://uefi.org/specs/UEFI/2.10/38_Confidential_Computing.html), which primarily focus on capturing events during OS boot-up. Unlike CCEL, AAEL provides a comprehensive format for logging events that occur within Confidential VMs (CVMs) after the operating system has started. These VMs provide a highly secure and isolated environment crucial for protecting sensitive operations. The AAEL standard ensures that these post-OS events, which can include memory operations, network transactions, filesystem operations and container-related activities, etc, are coherently bound to hardware dynamic measurement registers, tying activities within the Confidential VMs to their secure hardware roots. This enables high integrity and verifiability for operations, greatly enhancing the ability to audit, troubleshoot, and respond to security incidents in confidential computing scenarios occurring post OS startup.
6+
7+
## Architecture
8+
9+
The architecture supporting AAEL seamlessly integrates with existing confidential computing systems,
10+
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 dynamic measurement registers.
11+
12+
It receives logging requests from system components.
13+
14+
These callers record events following the spec-defined AAEL Event, ensuring consistency and reliability in log data.
15+
16+
The [Attestation Service (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.
17+
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 effectiveness and security of the VM.
18+
19+
```
20+
21+
┌─────────────────────────────────────┐
22+
│ │
23+
│ ┌────────────────┐ │
24+
│ │System Component│ │
25+
│ └───────┬────────┘ │
26+
│ │ │
27+
│ │ │
28+
│ │ │
29+
│ ┌──────────▼──────────┐ │ ┌─────────────────────┐
30+
│ │ │ │ │ │
31+
│ │ Attestation Agent ├───────┼─────►│ Attestation Service │
32+
│ │ │ │ │ │
33+
│ └───┬─────────┬───────┘ │ └─────────────────────┘
34+
│ │ │ │
35+
│ │ ▼ │
36+
│ Extend │ ┌──────┐ │
37+
│ │ │ AAEL │ │
38+
│ │ └──────┘ │
39+
│ ┌─────▼───────────────────┐ │
40+
│ │ Runtime Measurements/PCR│ │
41+
│ └─────────────────────────┘ │
42+
│ │
43+
│ Confidential VM │
44+
└─────────────────────────────────────┘
45+
```
46+
47+
In this specification, we provide detailed information on the Attestation Agent Event Log (AAEL) format in confidential computing scenarios.
48+
49+
Currently, as the kernel does not offer a unified interface for maintaining Eventlogs [1], we have decided to temporarily use the AAEL.
50+
51+
Once the kernel releases a unified Eventlog format, we will update the next version of the specification to ensure that the existing AAEL Event Entries are compatible with the new Kernel Eventlog format. We will also strive to minimize any impact on the user experience for existing users.
52+
53+
## Specifications
54+
55+
AAEL is a standard for event logging over guest kernel level.
56+
57+
### Attestation Agent Event Log (AAEL)
58+
59+
1. Binding of AAEL with Dynamic Measurement Registers
60+
61+
Entries recorded by AAEL are bound to a specific PCR register value. With each new event added, an extend operation is
62+
performed on the designated PCR register. When the platform provides a (v)TPM interface, the PCR register corresponds
63+
to the (v)TPM's PCR register. On a platform that is solely TEE, PCR is mapped to a specific [Confidential Computing event log Measurement Register (CCMR)](https://uefi.org/specs/UEFI/2.10/38_Confidential_Computing.html#virtual-platform-cc-event-log)
64+
according to platform-specific rules. This mapping ensures AAEL has applicability even outside TEE scenarios.
65+
66+
2. AAEL Log Entry Format
67+
68+
AAEL log entries consist of two types: Event Entry and INIT Entry.
69+
70+
__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
71+
72+
```
73+
INIT/<hash-algorithm> <hex-digest>
74+
```
75+
Where,
76+
- `<hash-algorithm>`: may be `sha256`, `sha384`, or `sha512`.
77+
- `<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.
78+
79+
__Event Entry__ records specific events in the format
80+
```
81+
<Domain> <Operation> <Content>
82+
```
83+
84+
Where,
85+
- `Domain`: the event domain, RECOMMENDED to be a URI.
86+
- `Operation`: the specific operation within the domain.
87+
- `Content`: detailed context of the operation.
88+
89+
The three fields are separated by spaces. Each field MUST not contain spaces or delimiters and MUST be composed of [printable character](https://www.ascii-code.com/characters/printable-characters).
90+
The three fields are defined by the specific application that calls AA to record events.
91+
92+
### Confidential Containers Event Spec
93+
94+
The Confidential Containers Event Spec (CoCo Event Spec) builds upon the AAEL framework, specifying event types pertinent to the unique context of Confidential Containers.
95+
96+
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.
97+
98+
```
99+
100+
┌─────────────────────────────────────┐
101+
│ │
102+
│ ┌────────────────────┐ │
103+
│ │ Kata-Agent/ASR/CDH │ │
104+
│ └──────────┬─────────┘ │
105+
│ │ │
106+
│ │ │
107+
│ │ │
108+
│ ┌──────────▼──────────┐ │ ┌─────────────────────┐
109+
│ │ │ │ │ │
110+
│ │ Attestation Agent ├───────┼─────►│ Attestation Service │
111+
│ │ │ │ │ │
112+
│ └───┬─────────┬───────┘ │ └─────────────────────┘
113+
│ │ │ │
114+
│ │ ▼ │
115+
│ Extend │ ┌──────┐ │
116+
│ │ │ AAEL │ │
117+
│ │ └──────┘ │
118+
│ ┌─────▼───────────────────┐ │
119+
│ │ Runtime Measurements/PCR│ │
120+
│ └─────────────────────────┘ │
121+
│ │
122+
│ Confidential VM │
123+
└─────────────────────────────────────┘
124+
```
125+
126+
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.
127+
The CoCo Event Spec is a concrete `Domain`, `Operation`, `Content` definition based on the AAEL specification.
128+
129+
CoCo events MUST have a `domain` set as `github.com/confidential-containers`.
130+
131+
Content fields MUST be in JSON format, without spaces or delimiters.
132+
133+
Concrete supported `Operation`s and `Content`s are defined in the following table:
134+
| Operation | Content | Description | Content Example |
135+
| --- | --- | --- | --- |
136+
| `PullImage` | `{"image":"<image-reference>","digest":"<digest>:<hex>"}` | An image pulling event with image reference and manifest digest | `{"image":"alpine","digest":"sha256:0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0"}` |
137+
138+
It's welcomed to add more events by making PRs.
139+
140+
## References
141+
142+
[1] https://lore.kernel.org/linux-coco/[email protected]/T/#m086550ee8ca4d0127657ca8a467bf7cf170bfb74

0 commit comments

Comments
 (0)