CDS Bootstrapping & Verification

The Certificate Distribution Service (CDS) is the trust root of a c8s cluster. In one process it verifies TEE attestation evidence, issues short-lived attestation-bound tokens, manages an in-memory mesh CA, signs leaf certificates, and — optionally — hands its CA off to peer replicas. There is no internal RA-TLS hop to an external signer, so the CA private key never leaves CDS memory.

Mesh CA bootstrap

At startup the CDS generates a fresh ECDSA P-384 mesh CA entirely in memory:

• The private key is in-process only and is never written to disk.
• Validity defaults to 8760h (one year), configurable with --ca-cert-validity.
• The public CA bundle is published so peers and clients can chain to it; the CA fingerprint is logged at startup.

Because the key lives only in memory, any CDS restart generates a new CA and invalidates previously issued leaves. That is acceptable for the chart-managed default; the production direction keeps the CA in attested CVM memory and replicates it via handoff.

Token signing and JWKS rotation

The attestation-bound token is a JWT, signed with ES256 (ECDSA P-256), that the CDS mints (via /attest-key) after a successful attestation. It is the cluster's attestation-bound bearer credential: a caller presents the token to authorize a CA handoff. (Certificate issuance does not use this token — /attest verifies evidence and returns the signed leaf in one step. Allowlist writes use an operator token, not an EAR.) Key claims:

The signing key rotates with overlap so verification never breaks mid-rotation:

• --token-signer-rotation-interval (default 720h) — how often a new P-256 key becomes active.
• --token-signer-overlap (default 25h) — how long a retired key stays published in the JWKS.
• --token-signer-rotation-jitter (default 0.1) — jitter on the first tick.

Each key's kid is its RFC 7638 JWK thumbprint. The current JWKS (active + non-expired retiring keys) is served at GET /.well-known/jwks.json.

The attestation flow

The CDS uses a nonce-challenge model so attestation evidence is cryptographically bound to a CSR's public key, preventing evidence replay or substitution.

   Workload                 CDS                    attestation-api
   [get-cert]               [host]                 [host]
      │                       │                       │
      │  POST /authenticate   │                       │
      │──────────────────────►│                       │
      │                       │                       │
      │  nonce                │                       │
      │  one-time challenge   │                       │
      │◄ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│                       │
      │                       │                       │
  ┌───┴────────────────────────────────────┐         │
  │ report_data =                           │         │
  │   SHA-384(CSR pubkey ‖ nonce)           │         │
  └───┬────────────────────────────────────┘         │
      │                       │                       │
      │  POST /attest         │                       │
      │  challenge + evidence + CSR                   │
      │──────────────────────►│                       │
      │                       │  verify(evidence,     │
      │                       │         report_data)  │
      │                       │──────────────────────►│
      │                       │                       │
      │                       │  valid · launch_digest│
      │                       │◄ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│
      │                       │                       │
      │              ┌────────┴─────────────────────┐ │
      │              │ check measurement ·          │ │
      │              │ validate CSR · sign (mesh CA)│ │
      │              └────────┬─────────────────────┘ │
      │                       │                       │
      │  leaf certificate + CA chain                  │
      │◄ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│                       │
      │                       │                       │

Step by step, on POST /attest the CDS:

1. consumes the one-time challenge (decoded from base64);
2. parses the CSR and verifies its self-signature;
3. computes the expected report_data = SHA-384(CSR_public_key ‖ challenge) (first 48 bytes);
4. calls the attestation-api /verify with the evidence and that expected report data;
5. requires signature_valid == true and report_data_match == true;
6. if --measurements is set, requires the evidence launch_digest to be in that allowlist;
7. validates the CSR's DNS/IP SANs and CN against policy (--dns-san-pattern, --san-validation, --allowed-cn-pattern);
8. signs the CSR with the mesh CA and returns the PEM chain.

The image allowlist

The CDS also owns and serves the image allowlist — the digests of the container images permitted to run (a SQLite store at --allowlist-db, served at /allowlist). Updating it always goes through the CDS; there is no side channel.

Who may update it is decided by the operator at CDS bootstrap: the install-time value cds.operatorKeys (--operator-keys, set by c8s install --operator-keys) pins the operator EC public key(s) authorized to write; empty rejects every write while reads keep serving. For each write, the c8s allowlist CLI signs a short-lived token with the operator's private key, bound to the exact method, path, and request body; the CDS verifies the signature against its pinned keys and re-checks each binding before committing. The pinned bundle is public material (served back at GET /operator-keys so c8s cds verify can report it), but it is host-supplied config — not part of the CDS's launch measurement.

See The Allowlist for the data model, the full write flow, seeding, and enforcement.

CA handoff

The in-memory-only CA is exactly what makes high availability tricky. Because the private key never touches disk (see Mesh CA bootstrap), the usual HA tactics don't apply: a cold-standby replica or a simple pod restart each comes up generating a fresh CA, which signs a different chain and invalidates every leaf already issued. There is no shared key on a PersistentVolume to fail over to — that's the whole point of keeping it in memory.

Handoff resolves this by moving the live CA from one attested CDS to another, in memory, over an attested channel — never through disk or a third party:

1. A successor replica starts, generates an ephemeral X25519 keypair, attests itself, and calls POST /handoff on the active CDS, presenting its attestation-bound token and that ephemeral public key.
2. The active CDS verifies the token's signature and checks the recipient's launch_digest against --handoff-measurements — so the CA only ever leaves for another CDS whose exact launch measurement you have pinned.
3. It returns the CA payload (cert and private key) AES-GCM-wrapped to the recipient's X25519 key. The key crosses the wire only as ciphertext that one attested enclave can open, and it is written to disk on neither side.

The successor now holds the same CA, so every certificate the cluster has already issued stays valid across the changeover — a rolling upgrade or a failover happens with no trust-on-first-use gap and no mass re-issuance. The CA key spends its entire life inside attested CVM memory, replicated enclave-to-enclave.

Handoff is opt-in (cds.handoff.enabled=true) and gated on --handoff-measurements; with no measurements listed, POST /handoff refuses every request. Pair it with the CA's validity window (--ca-cert-validity) and the /readyz gate — which starts failing once remaining validity drops below --min-ca-validity — so a successor is brought up and handed the CA well before the active one's certificate expires.

Verifying the CDS itself (RA-TLS)

Clients verify the CDS before trusting anything it returns. The CDS serves its API over RA-TLS: its serving certificate carries hardware evidence (SEV-SNP or TDX) in an X.509 extension. A client (for example get-cert --cds-measurements <sha384-csv>) verifies that evidence through its local attestation-api and checks the CDS launch digest against the supplied allowlist before completing the handshake. With no measurements supplied the client falls back to trust-on-first-use and logs a warning — pin --cds-measurements in production (the CDS's own launch digest; see Obtaining launch measurements).

To check the CDS on demand — after install, or from CI — rather than as part of a client handshake, use c8s cds verify. It pulls the CDS's RA-TLS evidence and re-verifies it with the cluster's own attestation engine. Start by inspecting what the CDS reports (-o json gives the structured form):

# c8s-cds is a headless Service; dial the pod IP directly (the kata guest policy blocks
# kubectl port-forward/exec), from somewhere with cluster-network reach (a node, or a VPN):
CDS_IP=$(kubectl get endpoints c8s-cds -n c8s-system -o jsonpath='{.subsets[0].addresses[0].ip}')

c8s cds verify "https://$CDS_IP:8443" -o json

{
  "verified": true,
  "backend": "attestation-go",
  "source": "RA-TLS serving certificate at 10.42.0.153:8443",
  "fresh": false,
  "binding": "REPORTDATA binds the certificate public key (no per-request nonce — not a freshness proof)",
  "platform": "snp",
  "measurement": "f894e79d20ab98ba8fc878425739d1b5900999835fe3f94c90fa8603e0636325c131192eb0005f5d3b8134e363d434a3",
  "current_tcb": "bootloader=12 tee=0 snp=28 microcode=28",
  "cert_sha256": "0109d41e0907ab4ecd5823b5d08c3a6b5d69751322338e28c78f8378c56f92f9",
  "measurement_pinned": false
}

Reading that report field by field:

Once you've confirmed the reported measurement is the CDS's expected launch digest, pin it so a wrong image is rejected (exit code 2) instead of silently accepted:

c8s cds verify "https://$CDS_IP:8443" \
  --measurements f894e79d20ab98ba8fc878425739d1b5900999835fe3f94c90fa8603e0636325c131192eb0005f5d3b8134e363d434a3

measurement_pinned now reports true, and verification fails closed if the CDS ever presents a digest you didn't pin. See operator & service verification for the load-balancer and workload variants, the CI exit-code/JSON contract, and how to independently recompute the digest with sev-snp-measure.

Obtaining launch measurements

A measurement is the SHA-384 launch digest of a confidential VM — a hash the TEE hardware (AMD SEV-SNP or Intel TDX) computes over the exact launch state (firmware, guest kernel, and the kernel command line, which embeds the dm-verity root hash of the rootfs). Every *measurements flag in c8s takes one or more of these hex strings. Because a reproducible image always yields the same digest, pinning it means "accept only this exact, audited image — nothing else."

There are three ways to get the value, best first:

# illustrative — see the sev-snp-measure docs for the exact flags for your image
sev-snp-measure --mode snp --vcpus 1 \
  --ovmf OVMF.fd --kernel vmlinuz \
  --append "<kernel cmdline, including root_hash=...>" \
  --output-format hex

Each flag wants the digest of a different party:

Endpoint summary

See the CLI Reference for every CDS flag.