Skip to content
Calimero — Mero TEECalimero — Mero TEEMero TEE

System Overview

Mero TEE is the confidential-computing layer for Calimero. Its job is narrow and concrete: prove what code a node is running on genuine Trusted Execution Environment (TEE) hardware, and hand out secrets — storage keys, group membership — only to nodes that pass that proof. It is the operational home of the attestation ideas described in the Calimero Core TEE Attestation & Fleet Admission chapter; read that first for the protocol, then this track for how the pieces are built, deployed, and verified.

Everything here rests on Intel TDX (Trust Domain Extensions): each merod node and the KMS run inside a confidential VM whose memory the hypervisor cannot read, and whose software identity the CPU measures and signs into an attestation quote. See the glossary for the vocabulary.

The three components

Section titled “The three components”
Component Repo path What it is
mero-kms mero-kms/, mero-tee/playbook-kms.yml A Rust/Axum HTTP service that validates a node’s TDX attestation and releases a deterministic storage encryption key, HKDF’d from a root that exists only in the memory of its cluster. Runs as a frozen, dm-verity-sealed GCP TDX image, one 5-replica cluster per release.
Image builds mero-tee/ An mkosi build that bakes merod 1.0 into a GCP TDX Confidential VM image, in three security profiles, from Ansible roles — and, from the same build, the KMS image.
attestation-verifier attestation-verifier/ A React single-page app plus Vercel serverless API that lets anyone independently verify a KMS or a node quote through Intel Trust Authority (ITA).

The components reference maps each of these in detail.

Two trust flows, not one

Section titled “Two trust flows, not one”

The most important thing to understand is that Mero TEE carries two distinct attestation flows that are easy to conflate. They use different mechanisms and solve different problems.

1. Storage-key release (node ⇄ KMS)

Section titled “1. Storage-key release (node ⇄ KMS)”

When a merod node boots inside a TDX VM, it needs the key that decrypts its on-disk storage. It gets that key from the KMS, but only after a challenge–response exchange in which the node proves — with a hardware quote — that it is an approved image. The KMS in turn exposes a self-attestation endpoint so the node (or anyone) can verify the KMS is itself genuine before trusting it. This is the flow the trust model and key release pages describe.

merod (TDX VM)                         mero-kms (GCP TDX cluster, one URL)
     │  POST /challenge { peerId }              │
     │ ───────────────────────────────────────▶│  issue single-use nonce
     │  { challengeId, nonceB64, expiresAt }    │
     │ ◀───────────────────────────────────────│
     │  quote over (nonce ‖ SHA-256(peerId))    │
     │  + signature by the peer key             │
     │  POST /get-key { challengeId, quoteB64,  │
     │     peerId, peerPublicKeyB64, sigB64 }   │
     │ ───────────────────────────────────────▶│  verify sig → verify quote →
     │                                          │  enforce MRTD/RTMR/TCB policy →
     │  { sealed key }                          │  HKDF from the cluster root
     │ ◀───────────────────────────────────────│

2. Fleet admission (node ⇄ namespace, via Core)

Section titled “2. Fleet admission (node ⇄ namespace, via Core)”

Separately, the nodes of a cluster trust each other the way clients trust a node: in Calimero Core 1.0 each node verifies a peer’s TDX quote against the signed mero-tee release the peer names before any Raft traffic, and adds a cluster secret derived from the storage key. Each app instance is its own Raft group across the cluster’s nodes, and cluster membership lives in the cluster’s system group. That lives in Core, not in this repo; see Calimero Core → TEE attestation. (v1’s namespace admission of ReadOnlyTee/RelayTee fleet members, and the fleet HA sidecar that drove it, are gone.)

What binds identity to hardware

Section titled “What binds identity to hardware”

Both flows lean on the same TDX primitives:

  • MRTD — a SHA-384 measurement of the initial VM image. Any change to the image changes it.
  • RTMR0–3 — four extend-only runtime registers. In this system, RTMR3 carries the profile/role separation: at boot, the KMS image’s kms-init and the node image’s calimero-init each extend it with the image’s role + profile + a root-content hash. Because the registers are hardware-measured and can only be extended, a debug image cannot present a production RTMR3.
  • report_data — 64 caller-supplied bytes baked into the quote, split as nonce ‖ binding, that tie a quote to a specific fresh request and identity.

The KMS’s admission decisions are governed by an attestation policy — an allowlist of MRTD, RTMR0–3, and TCB-status values — baked into the KMS image at build time, from the node release it ships with. Nodes, in turn, pin the KMS by its measurements from the release’s signed kms-attestation-policy.json. See policy management and the config reference.

Where to go next

Section titled “Where to go next”