Getting Started

This page gets you from a fresh checkout to a running local KMS and the attestation-verifier web app, then walks one challenge → get-key cycle against your local instance. It is the fastest way to see the moving parts before you read the flows in depth.

The production KMS only releases keys to nodes running inside a real Intel TDX confidential VM, with quotes signed by the hardware and keys derived from a cluster root that exists only inside TDX replicas. None of that exists on a laptop, so the KMS ships a dev-only mock path (a Cargo feature, off by default) that lets you run a single replica and exercise the HTTP surface and most of the verification pipeline without TDX hardware.

Caution

Everything on this page uses the mock-attestation build and mock acceptance. That code is compiled out of the production binary and must never be used to release real keys. See the trust model for why.

Prerequisites

• Rust 1.88+ (rustup, cargo) — the KMS is a Cargo workspace.
• Node.js 18+ and npm — for the attestation-verifier web app.
• curl and (optionally) jq — to drive the endpoints by hand.

Build the KMS

The workspace has a single member, mero-kms. From the repository root:

# Debug build of the whole workspace
cargo build

# Or an optimized build
cargo build --release

This produces the production binary — it contains no mock-attestation code. To run locally you want the dev build described next.

Run the KMS in dev mode

Two independent things stand between a fresh start and a working /get-key locally, and you have to satisfy both:

1. Mock attestation — accept mock TDX quotes instead of requiring real hardware-signed ones. This is gated behind the default-off mock-attestation Cargo feature, and only then is the ACCEPT_MOCK_ATTESTATION env var read.
2. A cluster root — /challenge and /get-key are fail-closed. Until the replica holds a root it returns 503 policy_not_ready. Locally, make your single replica the bootstrap one with MERO_KMS_BOOTSTRAP=true, so it generates a root at startup instead of trying to join peers.

Build with the feature and set both knobs:

cd mero-kms
ACCEPT_MOCK_ATTESTATION=true \
MERO_KMS_BOOTSTRAP=true \
  cargo run --features mock-attestation

In mock mode the replica’s own quote is a mock too, so the debug-TD and RTMR3 startup checks that a real replica enforces are skipped.

Caution

The mero-kms README shows ACCEPT_MOCK_ATTESTATION=true cargo run. Without --features mock-attestation the flag is silently ignored — the mock path is not compiled in — and mock quotes are rejected as unparseable. Always pass --features mock-attestation for local dev.

On startup the service logs its resolved configuration. Expect to see the mock warning, the bootstrap flag, the locked-read-only profile, and the new root:

INFO Starting mero-kms
INFO Listen address: 0.0.0.0:8080
INFO Cluster: bootstrap=true peers=[]
INFO KMS profile cohort: locked-read-only
WARN WARNING: Mock attestation acceptance is enabled. This should NEVER be used in production!
INFO Generated a new cluster root; this replica bootstraps the cluster
INFO Server listening on 0.0.0.0:8080

Note

With mock acceptance on, the startup policy check is short-circuited, so the replica starts even with empty ALLOWED_* allowlists — mock quotes skip the measurement-policy comparison anyway. In a real image those lists are baked in from the node release. If you want to exercise real measurement checks, set the allowlists: ALLOWED_TCB_STATUSES (default uptodate) and ALLOWED_MRTD, ALLOWED_RTMR0…ALLOWED_RTMR3 (each a 96-hex-char TDX register value). See the configuration reference for every variable and its default.

Change the listen address (optional)

The HTTP listener defaults to 0.0.0.0:8080. Override with LISTEN_ADDR if 8080 is taken:

LISTEN_ADDR=127.0.0.1:9090 \
ACCEPT_MOCK_ATTESTATION=true \
MERO_KMS_BOOTSTRAP=true \
  cargo run --features mock-attestation

Confirm it is up

/health is a liveness probe — it answers 200 whether or not the replica holds a root, and says which:

curl -s http://localhost:8080/health
# {"status":"alive","service":"mero-kms","clusterRootReady":true}

Walk one challenge → get-key cycle

Key release is a two-round challenge-response. Round 1 (/challenge) is fully self-contained and works locally; round 2 (/get-key) runs the whole verification pipeline and is where the local/hardware boundary shows up. Both routes are documented in full in Key Release.

Round 1 — get a challenge

Send any base58btc peer ID. The KMS returns a stateless challenge ID (112 hex characters: 16 random bytes, the expiry and a tag) plus the base64 nonce, an HMAC of the ID and the peer ID under a root-derived key, and its expiry:

curl -s -X POST http://localhost:8080/challenge \
  -H 'content-type: application/json' \
  -d '{"peerId":"12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp"}'

{
  "challengeId": "<112 hex chars>",
  "nonceB64": "aGVsbG8td29ybGQtZXhhbXBsZS0zMi1ieXRlcy1ub25jZQ==",
  "expiresAt": 1753104000
}

The challenge is valid for CHALLENGE_TTL_SECS (default 60) and a replica redeems it at most once.

Round 2 — redeem it at /get-key

/get-key takes the challenge ID plus a TDX quote, the peer’s public key, and a signature binding all of it to the peer identity:

curl -s -X POST http://localhost:8080/get-key \
  -H 'content-type: application/json' \
  -d '{
    "challengeId": "<112 hex chars from round 1>",
    "quoteB64":    "<base64 raw TDX quote with the nonce in report_data>",
    "peerId":      "12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp",
    "peerPublicKeyB64": "<base64 protobuf libp2p public key>",
    "signatureB64":     "<base64 signature over the canonical payload>",
    "sealToB64":        "<base64 one-time X25519 public key>"
  }'

The KMS then, in order: validates the shapes, redeems the challenge (so a replay to the same replica always fails on the second try), verifies the peer signature and public-key ownership, verifies the quote (mock quotes are accepted here in dev), enforces the measurement policy (skipped for accepted mocks), and finally derives the key by HKDF from the root and seals it to sealToB64. On success it returns:

{ "sealedKeyB64": "<sealed storage key>", "sealNonceB64": "<12-byte nonce>" }

Note

What actually completes locally. /challenge succeeds outright, and key derivation needs no hardware now that it comes from the in-memory root. Producing a valid mock quoteB64 and the matching peer signature is still the job of a real merod node (or the mock helpers in calimero-tee-attestation), not a hand-written curl body — so treat round 2 as a structural walkthrough unless you have a node in the loop.

You can still observe the fail-closed behavior directly. Send a /get-key request with placeholder credentials and watch the gates reject it, and watch the challenge get redeemed even on failure:

# Second identical request returns invalid_challenge — the first attempt
# already redeemed the single-use challenge, regardless of why it failed.

Every error is a machine-readable tag with an HTTP status; the full catalog is in Error handling.

Run the attestation verifier

The verifier is a separate React/Vite app with a serverless /api/verify backend. Run it locally:

cd attestation-verifier
npm install
npm run dev

Vite serves it at http://localhost:5173. The two routes are /kms (verify a pasted mero-kms /attest response; KMS replicas listen only inside their VPC) and /mero-tee (verify a merod node by URL); the landing page redirects to /kms.

Note

The live verification path calls Intel Trust Authority and needs an ITA_API_KEY in the environment — without it /api/verify returns 503 ITA_API_KEY not configured. The dev server also does not run the serverless functions the way the production host does, so end-to-end verification is best exercised against the deployed verifier. See Verify a release for the full UI walkthrough, and Verification for what the checks mean.

Next steps

• Verify a release — check release assets and use the public verifier UI.
• Attestation flow — where quotes come from and the 64-byte report_data layout.
• Key release — the full challenge → get-key protocol and every field it checks.
• Configuration reference — every environment variable and default.
• Calimero Core: TEE Attestation — the protocol-level view of the same primitive.