# Intel TDX
Intel **Trust Domain Extensions (TDX)** is a hardware-based TEE technology that
provides confidential computing at the virtual machine level. Mosaik's TDX
support lets nodes running inside a TDX Trust Domain generate attestation
tickets and lets other nodes validate them against expected measurements.
Enable TDX support with the `tdx` feature flag:
```toml
[dependencies]
mosaik = { version = "0.3", features = ["tdx"] }
```
## Network Extension
The `tdx` feature adds a `.tdx()` method to `Network` via the `NetworkTdxExt`
trait:
```rust,ignore
use mosaik::{Network, tdx::NetworkTdxExt};
let network = Network::new("my-network".into()).await?;
// Check if TDX hardware is available
if network.tdx().available() {
// Generate and install an attestation ticket
network.tdx().install_own_ticket()?;
}
```
### Available Methods
| `available()` | Returns `true` if TDX hardware is present and functional |
| `ticket()` | Generates a non-expiring TDX attestation ticket |
| `ticket_with_expiration(exp)` | Generates a ticket with a specific expiration |
| `install_own_ticket()` | Generates a ticket and adds it to the node's discovery entry |
| `measurements()` | Returns all TDX measurements (MR_TD, RTMRs) |
| `mrtd()` | Returns the MR_TD measurement |
| `rtmr0()` / `rtmr1()` / `rtmr2()` / `rtmr3()` | Returns individual RTMR measurements |
## TDX Tickets
A `TdxTicket` wraps a hardware-generated TDX Quote together with mosaik-specific
extra data. The ticket structure:
```text
TdxTicket
├── quote_bytes Raw TDX Quote (hardware-signed attestation)
└── extra
├── peer_id The mosaik PeerId of the attesting node
├── network_id The NetworkId the node belongs to
├── started_at When the node process started
├── quoted_at When the quote was generated
└── expiration Ticket expiration policy
```
The TDX Quote's `report_data` field contains a hash of the extra data, creating
a cryptographic binding between the hardware attestation and the mosaik peer
identity.
### Converting between ticket types
`TdxTicket` converts to and from mosaik's generic `Ticket` type:
```rust,ignore
// Generate a TDX-specific ticket
let generic_ticket: Ticket = network.tdx().ticket()?;
// Parse a generic ticket back into a TdxTicket
let tdx_ticket: TdxTicket = generic_ticket.try_into()?;
// Access TDX-specific fields
println!("Peer: {}", tdx_ticket.peer_id());
println!("MR_TD: {}", tdx_ticket.measurements().mrtd());
println!("Quote verified: {}", tdx_ticket.quote().verify().is_ok());
```
Tickets are compressed with zstd before serialization to reduce gossip overhead.
## Measurements
TDX measurements are 48-byte register values that identify the software running
inside a Trust Domain:
| `MR_TD` | Measurement of the TD build-time configuration and firmware |
| `RTMR0` | Runtime measurement register 0 |
| `RTMR1` | Runtime measurement register 1 |
| `RTMR2` | Runtime measurement register 2 |
| `RTMR3` | Runtime measurement register 3 |
### Creating measurements
```rust,ignore
use mosaik::tdx::Measurement;
// From a hex string (96 characters = 48 bytes)
let m = Measurement::hex("91eb2b44d141d4ece09f0c75c2c53d247a3c68edd7fafe8a3520c942a604a407de03ae6dc5f87f27428b2538873118b7");
// From a byte array
let m = Measurement::new([0u8; 48]);
// Parse from string at runtime
let m: Measurement = "91eb2b44...".parse()?;
```
### Reading local measurements
When running inside a TDX guest, you can read the local machine's measurements
directly without needing a `Network` instance:
```rust,ignore
use mosaik::tdx::Measurements;
let local = Measurements::local()?;
println!("MR_TD: {}", local.mrtd());
println!("RTMR0: {}", local.rtmr0());
println!("RTMR1: {}", local.rtmr1());
println!("RTMR2: {}", local.rtmr2());
println!("RTMR3: {}", local.rtmr3());
```
This is also available through `network.tdx().measurements()`, which delegates
to the same underlying call.
## Tdx
`Tdx` implements the `TicketValidator` trait for TDX attestation. It
validates that a peer's TDX Quote carries valid hardware signatures and that
the measurements match specified criteria.
### Basic usage
```rust,ignore
use mosaik::tdx::Tdx;
// Accept any valid TDX attestation (signatures must verify)
let validator = Tdx::new();
// Require a specific MR_TD value
let validator = Tdx::new()
.require_mrtd("91eb2b44d141d4ece09f0c75c2c53d247a3c68edd7fafe8a3520c942a604a407de03ae6dc5f87f27428b2538873118b7");
// Require specific RTMRs
let validator = Tdx::new()
.require_mrtd("...")
.require_rtmr0("...")
.require_rtmr2("...");
```
### Builder methods
| `new()` / `empty()` | Accept any valid TDX attestation |
| `baseline(criteria)` | Start from a `MeasurementsCriteria` baseline |
| `from_local()` | Require all measurements to match the local machine |
| `require_mrtd(measurement)` | Require a specific MR_TD value |
| `require_rtmr0(measurement)` | Require a specific RTMR0 value |
| `require_rtmr1(measurement)` | Require a specific RTMR1 value |
| `require_rtmr2(measurement)` | Require a specific RTMR2 value |
| `require_rtmr3(measurement)` | Require a specific RTMR3 value |
| `require_own_mrtd()` | Require the same MR_TD as the local machine |
| `require_own_rtmr0()` | Require the same RTMR0 as the local machine |
| `require_own_rtmr1()` | Require the same RTMR1 as the local machine |
| `require_own_rtmr2()` | Require the same RTMR2 as the local machine |
| `require_own_rtmr3()` | Require the same RTMR3 as the local machine |
| `allow_variant(criteria)` | Allow an alternative set of measurement criteria |
The `from_local()` and `require_own_*` methods read measurements from TDX
hardware and return `Result`, so they require `?` or `.expect()` in the builder
chain.
### Validation checks
When validating a peer's ticket, `Tdx` performs these checks in order:
1. Deserializes the ticket data into a `TdxTicket`
2. Parses and verifies the TDX Quote's hardware signature
3. Verifies the quote's `report_data` matches the hash of the extra data
4. Checks the baseline measurement criteria against the quote's measurements
5. If variant criteria are configured, checks that at least one matches
6. Verifies the ticket's peer ID matches the peer entry's ID
7. Verifies the ticket's network ID matches the peer entry's network ID
8. Checks that the ticket has not expired
### Multiple measurement profiles
The `allow_variant` method lets you accept nodes with different software
configurations. The baseline criteria must always be satisfied, and at least one
variant must also match (if any are configured):
```rust,ignore
use mosaik::tdx::{Tdx, MeasurementsCriteria};
let validator = Tdx::new()
// All nodes must have this MR_TD
.require_mrtd("aabb...")
// Accept nodes running firmware version A
.allow_variant(
MeasurementsCriteria::new().require_rtmr0("1111...")
)
// OR firmware version B
.allow_variant(
MeasurementsCriteria::new().require_rtmr0("2222...")
);
```
### Matching local measurements
When every node in a group runs the same binary on the same TDX image, you can
require peers to present measurements identical to the local machine's — without
hardcoding hex strings. The values are read from TDX hardware at construction
time and become part of the validator's signature, so all nodes with the same
measurements will derive the same group identity.
```rust,ignore
use mosaik::tdx::Tdx;
// Require all measurements to match (MR_TD + all RTMRs)
let validator = Tdx::from_local()?;
// Require only specific registers to match
let validator = Tdx::new()
.require_own_mrtd()?
.require_own_rtmr2()?;
// Mix local and explicit measurements
let local = Measurements::local()?;
let validator = Tdx::new()
.require_mrtd(local.mrtd())
.require_rtmr1("abcd...");
```
This is particularly useful for collections and groups where the validator's
signature is part of the group identity — every peer with the same TDX image
will derive matching signatures automatically.
## Using TDX with Streams
```rust,ignore
use mosaik::*;
use mosaik::tdx::Tdx;
// Via the stream! macro
declare::stream!(
pub SecureFeed = PriceUpdate, "secure.prices",
consumer require_ticket: Tdx::new()
.require_mrtd("..."),
);
// Via the builder API
let producer = network.streams()
.producer::<PriceUpdate>()
.require_ticket(Tdx::new().require_mrtd("..."))
.build()?;
let consumer = network.streams()
.consumer::<PriceUpdate>()
.require_ticket(Tdx::new().require_mrtd("..."))
.build();
```
## Using TDX with Groups
```rust,ignore
use mosaik::tdx::Tdx;
use mosaik::groups::GroupKey;
let validator = Tdx::new().require_mrtd("...");
let group = network.groups()
.with_key(GroupKey::from(&validator))
.with_state_machine(MyStateMachine::default())
.require_ticket(validator)
.join();
```
## Using TDX with Collections
```rust,ignore
use mosaik::*;
use mosaik::tdx::Tdx;
// Via the collection! macro with a hardcoded measurement
declare::collection!(
pub SecureStore = mosaik::collections::Map<String, String>,
"secure.store",
require_ticket: Tdx::new().require_mrtd("..."),
);
// Via the collection! macro with local measurement matching
declare::collection!(
pub SecureStore = mosaik::collections::Map<String, String>,
"secure.store",
require_ticket: Tdx::new()
.require_own_mrtd()
.expect("TDX must be available")
.require_own_rtmr2()
.expect("TDX must be available"),
);
// Via CollectionConfig
let config = CollectionConfig::default()
.require_ticket(Tdx::from_local()?);
let writer = mosaik::collections::Map::<String, String>::writer_with_config(
&network, store_id, config,
);
```
## TDX Image Builder
Mosaik includes a build-time tool for creating TDX guest images from Rust
crates. Two builder variants are available:
| **Alpine** | `x86_64-unknown-linux-musl` | Alpine minirootfs (~5 MB) | Static (musl) | `tdx-builder-alpine` |
| **Ubuntu** | `x86_64-unknown-linux-gnu` | Ubuntu base (~25 MB) | Dynamic (glibc) | `tdx-builder-ubuntu` |
Both builders cross-compile your binary, package it with a kernel and OVMF
firmware into a CPIO initramfs, pre-compute TDX measurements, and generate a
self-extracting QEMU launch script. Use `tdx-builder-all` to enable both.
### When to use which
- **Alpine** — smaller images, faster boot, ideal for lightweight services
that don't need glibc or the Ubuntu package ecosystem.
- **Ubuntu** — full glibc environment with standard Ubuntu packages
(`kmod`, `iproute2`, etc.) pre-installed. Better compatibility with
libraries that require glibc or dynamically linked C dependencies.
### Enable in build-dependencies
```toml
[build-dependencies]
# Alpine only
mosaik = { version = "0.3", features = ["tdx-builder-alpine"] }
# Ubuntu only
mosaik = { version = "0.3", features = ["tdx-builder-ubuntu"] }
# Both
mosaik = { version = "0.3", features = ["tdx-builder-all"] }
```
### Usage in build.rs
```rust,ignore
fn main() {
// Alpine builder
let output = mosaik::tdx::build::alpine().build();
// Ubuntu builder
let output = mosaik::tdx::build::ubuntu().build();
}
```
You can also select the builder at build time via an environment variable:
```rust,ignore
fn main() {
let output = match std::env::var("BUILD_TYPE").as_deref() {
Err(_) | Ok("alpine") => {
mosaik::tee::tdx::build::alpine().build()
}
Ok("ubuntu") => {
mosaik::tee::tdx::build::ubuntu().build()
}
_ => panic!("Unknown BUILD_TYPE"),
};
}
```
```bash
# Build with Alpine (default)
cargo build -p my-crate
# Build with Ubuntu
BUILD_TYPE=ubuntu cargo build -p my-crate
```
### Build steps
Both builders follow the same pipeline:
1. Cross-compile the current crate for the target triple
2. Download the base root filesystem (Alpine minirootfs or Ubuntu base)
3. Download a TDX-enabled kernel and OVMF firmware
4. Bundle everything into a gzipped CPIO initramfs
5. Pre-compute `MR_TD`, `RTMR[1]`, and `RTMR[2]` measurements
6. Generate a self-extracting QEMU launch script
The pre-computed `MR_TD` can be used directly in `Tdx::require_mrtd()`
for compile-time attestation binding — the binary that builds the image knows
exactly what measurement to expect from the resulting TDX guest.
### Builder options
Both `AlpineBuilder` and `UbuntuBuilder` share a common fluent API:
| `with_custom_vmlinuz(bytes)` | Provide a kernel binary in-memory (skips download) |
| `with_custom_ovmf(bytes)` | Provide OVMF firmware in-memory (skips download) |
| `with_ssh_key(pubkey)` | Add an SSH public key for guest access |
| `with_ssh_forward(host, guest)` | Configure SSH port forwarding |
| `with_default_cpu_count(n)` | Set default vCPU count (default: 4) |
| `with_default_memory_size(size)` | Set default memory size (default: `"4G"`) |
| `with_bundle_runner()` | Include the mosaik bundle runner (default) |
| `without_bundle_runner()` | Exclude the mosaik bundle runner |
| `with_extra_file(host, guest)` | Bundle additional files into the image |
| `with_kernel_module(path)` | Include a `.ko` kernel module file |
| `with_kernel_modules_dir(path)` | Auto-discover TDX kernel modules from a directory |
| `with_kernel_version(v)` | Set kernel version for download (e.g. `"6.8.0-55"`) |
| `with_kernel_abi(abi)` | Set kernel ABI for download (e.g. `"57"`) |
| `with_ovmf_version(v)` | Set OVMF version for download |
| `with_artifacts_output_path(p)` | Custom output directory for build artifacts |
| `with_arg(arg)` | Append a command-line argument to the guest binary |
| `with_args(args)` | Append multiple command-line arguments at once |
| `with_env(key, value)` | Set an environment variable for the guest binary |
**Alpine-specific:**
| `with_major_version(v)` | Alpine major version (default: `"3.21"`) |
| `with_minor_version(v)` | Alpine patch release (default: `"0"`) |
| `with_custom_minirootfs(bytes)` | Provide Alpine minirootfs tarball in-memory |
**Ubuntu-specific:**
| `with_ubuntu_version(v)` | Ubuntu version (default: `"24.04.4"`) |
| `with_custom_rootfs(bytes)` | Provide Ubuntu base rootfs tarball in-memory |
### Environment variable overrides
Both builders respect environment variables for CI or scripted builds:
| `TDX_IMAGE_SKIP=1` | Skip the entire TDX image build |
| `TDX_IMAGE_ALPINE_VERSION` | Alpine major version (Alpine builder) |
| `TDX_IMAGE_ALPINE_MINOR` | Alpine patch release (Alpine builder) |
| `TDX_IMAGE_UBUNTU_VERSION` | Ubuntu version (Ubuntu builder) |
| `TDX_IMAGE_KERNEL` | Path to a custom kernel binary |
| `TDX_IMAGE_KERNEL_VERSION` | Ubuntu kernel version for download |
| `TDX_IMAGE_KERNEL_ABI` | Ubuntu kernel ABI for download |
| `TDX_IMAGE_OVMF` | Path to a custom OVMF firmware file |
| `TDX_IMAGE_OVMF_VERSION` | OVMF version for download |
| `TDX_IMAGE_EXTRA_FILES` | Colon-separated `host:guest` file pairs |
| `TDX_IMAGE_KERNEL_MODULES` | Colon-separated `.ko` module paths |
| `TDX_IMAGE_KERNEL_MODULES_DIR` | Kernel modules auto-discovery directory |
### Build artifacts
Both builders produce the same set of artifacts under
`<target_dir>/<profile>/tdx-artifacts/<crate_name>/<distro>/`:
| `<crate>-initramfs.cpio.gz` | Gzipped initramfs |
| `<crate>-vmlinuz` | Kernel binary |
| `<crate>-ovmf.fd` | OVMF firmware |
| `<crate>-run-qemu.sh` | Self-extracting QEMU launch script |
| `<crate>-launch-tdx.sh` | Simple launch wrapper |
| `<crate>-mrtd.hex` | Pre-computed MR_TD measurement |
| `<crate>-rtmr1.hex` | Pre-computed RTMR[1] measurement |
| `<crate>-rtmr2.hex` | Pre-computed RTMR[2] measurement |