From e9a7bfec423b1b20bbd897c35cb1dbb21262f44b Mon Sep 17 00:00:00 2001 From: Changyuan Lyu Date: Fri, 13 Mar 2026 15:29:12 -0700 Subject: [PATCH] docs: add instructions for Intel-TDX Signed-off-by: Changyuan Lyu --- README.md | 2 +- alioth/src/hv/hv.rs | 1 - docs/coco.md | 88 ++++++++++++++++++++++++++++----------------- 3 files changed, 57 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 491acce1..ff8b2d2a 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ For instructions on booting a cloud image, see [Booting Cloud Images](docs/cloud - **Cross-Platform:** Runs on `x86_64` (Linux) and `aarch64` (Linux & macOS). - **Confidential Computing:** Supports confidential VMs using AMD SEV, SEV-ES, - and SEV-SNP. See [coco.md](docs/coco.md) for more details. + and SEV-SNP or Intel TDX. See [coco.md](docs/coco.md) for more details. - **VirtIO Devices:** - `net`: Backed by a TAP device on Linux and [vmnet framework](https://developer.apple.com/documentation/vmnet) on macOS. diff --git a/alioth/src/hv/hv.rs b/alioth/src/hv/hv.rs index c2a1501e..fb336188 100644 --- a/alioth/src/hv/hv.rs +++ b/alioth/src/hv/hv.rs @@ -338,7 +338,6 @@ pub enum Coco { /// Enable Intel TDX. #[cfg(target_arch = "x86_64")] #[serde(alias = "tdx")] - #[serde_aco(hide)] IntelTdx { /// TD attribute, /// Intel TDX Module ABI Spec, Sec.3.4.1, Table 3.22. diff --git a/docs/coco.md b/docs/coco.md index d4e94c8b..c0a68429 100644 --- a/docs/coco.md +++ b/docs/coco.md @@ -1,54 +1,78 @@ -# Confidential Compute (coco) +# Confidential Compute (CoCo) -Alioth supports booting confidential guests on the following platforms, +Alioth supports booting confidential guests on the following platforms: -- AMD-SEV [^sev] +- AMD SEV [^sev] +- Intel TDX [^tdx] - The implementation takes QEMU [^qemu] as a reference. +The implementation of both takes QEMU [^qemu-sev]^[qemu-tdx] as a reference. > [!IMPORTANT] > > Alioth confidential VMs should be used in testing environments only since the > code base has not gone through any serious security reviews. -## AMD-SEV guest with Oak/stage0 firmware +## Confidential Guest with Oak/stage0 Firmware -To launch an SEV guest, +[Project Oak](https://github.com/project-oak/oak) provides a minimal firmware +(called `stage0`) for confidential computing. To use it with Alioth: -1. build the stage0 firmware from Project Oak[^stage0], +1. Clone the Project Oak repository and build the `stage0` firmware: -2. prepare the guest Linux kernel and the initramfs, + ```bash + # In the Project Oak source tree + # for AMD-SEV + bazel build //stage0_bin:stage0_bin + # for Intel-TDX + bazel build //stage0_bin_tdx:stage0_bin_tdx + ``` -3. launch the guest by + The resulting firmware for SEV and TDX are at + `bazel-bin/stage0_bin/stage0_bin` and + `bazel-bin/stage0_bin_tdx/stage0_bin_tdx` respectively. - ```bash - ./alioth run -f /path/to/oak_stage0.bin \ - --hypervisor kvm,dev_sev=/dev/sev \ - --memory size=1G \ - --num-cpu 2 \ - --kernel /path/to/vmlinuz \ - --cmdline "console=ttyS0" \ - --initramfs /path/to/initramfs \ - --coco sev,policy=$POLICY - ``` +2. Prepare the guest Linux kernel and the initramfs. -4. for SEV guests, `POLICY=0x1`, for SEV-ES guests, `POLICY=0x5`, +3. Use the appropriate firmware and the following values for flag `--coco` to + start a confidential VM: -5. for SEV-SNP guests, pass `--coco snp,policy=0x30000` instead. + Type | Flag values + ------- | --------------------- + SEV | `sev,policy=0x01` + SEV-ES | `sev,policy=0x05` + SEV-SNP | `snp,policy=0x30000` + TDX | `tdx,attr=0x10000000` -Note: + For example, to launch an AMD-SNP guest: + + ```bash + ./alioth boot \ + --memory size=1G \ + --cpu count=2 \ + --kernel /path/to/vmlinuz \ + --cmdline "console=ttyS0" \ + --initramfs /path/to/initramfs \ + --coco snp,policy=0x30000 \ + --firmware /path/to/stage0_bin + ``` -- An SEV-SNP guest requires host Linux kernel 6.11. +Note: -- Stage0 appends `-- --oak-dice=0x17000` to the guest kernel command line. Make - sure the init process in the initramfs accepts or ignores this flag. If the - init process fails to parse this flag and exits, the guest kernel would panic. +- An SEV-SNP guest requires host Linux kernel 6.11 or above. +- An Intel-TDX guest requires host Linux kernel 6.16 or above. +- It is recommended to use the latest stable host kernel for the best + compatibility and security. +- The `stage0` firmware appends extra arguments (`-- --oak-dice=... + --oak-event-log=... --oak-dice-length=...`) to the guest kernel command + line. The init process in your initramfs must be able to handle these + arguments, or it may fail and cause a kernel panic. -[^sev]: - [AMD Secure Encrypted Virtualization (SEV)](https://www.amd.com/en/developer/sev.html) +## Confidential Guest with UEFI-compatible Firmware -[^stage0]: - [Oak/stage0 firmware](https://github.com/project-oak/oak/tree/main/stage0_bin) +Work in progress. -[^qemu]: - [QEMU's doc on SEV](https://www.qemu.org/docs/master/system/i386/amd-memory-encryption.html) +[^sev]: [AMD Secure Encrypted Virtualization (SEV)](https://www.amd.com/en/developer/sev.html) +[^tdx]: [Intel Trusted Execution Technology (TDX)](https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html) +[^stage0]: [Oak/stage0 firmware](https://github.com/project-oak/oak/tree/main/stage0_bin) +[^qemu-sev]: [QEMU's doc on SEV](https://www.qemu.org/docs/master/system/i386/amd-memory-encryption.html) +[^qemu-tdx]: [QEMU's doc on TDX](https://www.qemu.org/docs/master/system/i386/tdx.html)