Docs

Verify an instance

Check an instance's hardware quote against its signed image and your own keys, then pin its SSH host keys.

The API is never the root of trust. It reports what it did, and it never says whether an instance can be trusted. The CPU does: each instance can produce a quote, a report signed by keys rooted in Intel or AMD, that states which image booted, which keys it was launched with, and data the guest chose to bind into it.

Verify an instance before you send it anything secret, and again whenever boot.count changes.

What a quote proves

CheckProvesCompare against
Signature chain and TCBThe quote came from genuine, up-to-date Intel TDX or AMD SEV-SNP hardwareIntel's or AMD's certificates, through your verifier
Image measurementsThe guest booted exactly the image you expectThe signed reference manifest in attestation.referenceManifest
Launch bindingThe guest was launched with your keys and no one else'sYour own copy of the keys you sent
Report dataThe quote is fresh and covers the SSH host keys it came withYour nonce and the returned host keys

The platform adds no key of its own, and the images have no operator login.

Before you start

You need:

  • the instance's id and the SSH public keys you created it with;
  • attestation-cli from confidential-dot-ai/attestation-rs, a verifier for TDX and SEV-SNP quotes. On Linux x86-64:
curl -fsSLo attestation-cli https://github.com/confidential-dot-ai/attestation-rs/releases/download/v0.5.0/attestation-cli
echo "36b46497cf335e79d1d304e44f0b4ee5b9b0c77c545df0859f70432f03485421  attestation-cli" | sha256sum --check
chmod +x attestation-cli
sudo apt-get install -y tpm2-tools   # provides the TSS libraries it links

Any verifier you trust works; the steps below are the same.

Step 1: Get the reference manifest

attestation.referenceManifest names the image's reference manifest by digest and URI. It is published in the image builder's container registry:

uri=$(jq -r .attestation.referenceManifest.uri instance.json)
repo=${uri#https://ghcr.io/v2/}; repo=${repo%%/blobs/*}
token=$(curl -s "https://ghcr.io/token?scope=repository:$repo:pull" | jq -r .token)
curl -sL -H "Authorization: Bearer $token" "$uri" -o manifest.json
sha256sum manifest.json   # must equal attestation.referenceManifest.digest

For TDX the expected measurements are tdx.mrtd, tdx.rtmr1 and tdx.rtmr2. For SEV-SNP, pick the entry of snp_variants whose smp equals the instance's compute.vcpus, and use its measurement.snp_launch_digest.

Step 2: Rebuild your launch binding

The platform writes your SSH keys to a file named pubkey on a launch disk that the image measures before it reads it: each key on its own line, each line ending in a line feed. attestation.launchBinding returns the file's SHA-256 and SHA-384 so you can compare them with your own:

A GPU instance whose gpuMetrics is true has one more line at the end, # confos-gpu-metrics/v1, which lets the guest serve its GPUs' metrics to the platform. sshd reads it as a comment, and because it is measured, the quote shows whether this boot's GPU metrics leave the guest.

cat ~/.ssh/id_ed25519.pub > pubkey          # exactly the keys, in the order you sent them
echo '# confos-gpu-metrics/v1' >> pubkey    # only if the instance's gpuMetrics is true
sha384sum pubkey                            # must equal attestation.launchBinding.sha384

The quote binds the same file:

  • TDX: RTMR[3] is SHA-384 over 48 zero bytes followed by the file's SHA-384.
  • SEV-SNP: HOST_DATA (the verifier's "init data") is the file's SHA-256.

Instances launched from the same image with the same keys measure the same, so one could answer in another's place. To tell instances apart, give each its own key list: a different comment on one key is enough, because the comment is part of the measured file.

Step 3: Ask for a fresh quote

Send 32 random bytes of your own, base64-encoded, to the endpoint named attest:

nonce=$(head -c 32 /dev/urandom | base64 -w0)
curl -s -X POST "http://<attest host>:<attest port>/attest" \
  -H "Content-Type: application/json" \
  -d "{\"nonce\": \"$nonce\"}" -o answer.json

The answer carries the quote, the instance's SSH host keys and a version:

{
  "version": "confos/ssh-host-keys/v1",
  "ssh_host_keys": [
    "ecdsa-sha2-nistp256 AAAAE2VjZHNh…",
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINDb2X…",
    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB…"
  ],
  "attestation": { "…": "the quote and its evidence" }
}

An answer without version confos/ssh-host-keys/v1 comes from an image that does not quote its host keys: send no secret over SSH to that instance.

The endpoint builds the report data itself and refuses a request that carries any, so no one who reaches it, the platform's hosts included, can get a quote over a key of their own. New connections to attest endpoints are limited to one a second per source address, with bursts of five: fetch a quote when you need one, not in a loop.

Step 4: Compute the expected report data

The first 48 bytes of the quote's 64-byte report data are:

SHA-384( LP("confos/ssh-host-keys/v1") || LP(nonce) || LP(key_1) || … || LP(key_n) )

and the last 16 bytes are zero. LP(x) is the length of x as a 4-byte big-endian integer followed by x; nonce is your 32 raw bytes; each key is the base64 part of a host key, decoded, in the order listed.

Step 5: Verify the quote

# TDX
attestation-cli verify -e evidence.json \
  --expected-report-data "$report_data" \
  --expected-mrtd "$mrtd" --expected-rtmr1 "$rtmr1" --expected-rtmr2 "$rtmr2" \
  --expected-rtmr3 "$rtmr3"

# SEV-SNP
attestation-cli verify -e evidence.json \
  --expected-report-data "$report_data" \
  --expected-launch-digest "$launch_digest" \
  --expected-init-data "$(sha256sum pubkey | cut -d' ' -f1)"

where evidence.json is the attestation object of the answer. Accept the instance only if the command exits 0 and its JSON output shows:

  • TDX: signature_valid, collateral_verified, report_data_match, mrtd_match, rtmr1_match, rtmr2_match and rtmr3_match all true, tcb_status.tcb_status UpToDate, and claims.platform_data.td_attributes_parsed.debug false.
  • SEV-SNP: signature_valid, report_data_match, launch_digest_match and init_data_match all true, claims.platform_data.policy.debug_allowed and migrate_ma false, and vmpl 0.

The verifier fetches certificates from Intel's and AMD's key services. AMD's service rate-limits requests; if verification fails with an HTTP 429, wait half a minute and try again with a new nonce.

Step 6: Pin the host keys

Write each host key the quote covered as a line <instance id> <type> <base64> in a known-hosts file of the instance's own, and connect with nothing else:

ssh -p <ssh port> \
  -o UserKnownHostsFile=i-9pj5dy9i6cbu.known_hosts \
  -o HostKeyAlias=i-9pj5dy9i6cbu \
  -o StrictHostKeyChecking=yes \
  root@<ssh host>

The platform's hosts carry the traffic to every endpoint, so only a pinned key shows that your session reached the instance you verified. The instance makes new host keys at every boot: when boot.count moves, verify again and pin the new keys in place of the old.

The whole check as one script

This script runs every step above against a live instance, and writes <instance id>.known_hosts only when every check passes. It needs Python 3.9 or later and attestation-cli on your PATH.

CC_API_KEY=cc_... python3 verify_instance.py i-9pj5dy9i6cbu ~/.ssh/id_ed25519.pub
verify_instance.py
#!/usr/bin/env python3
"""Verify a Confidential Cloud instance and pin its SSH host keys.

Usage:
  CC_API_KEY=cc_... python3 verify_instance.py i-9pj5dy9i6cbu ~/.ssh/id_ed25519.pub

Needs Python 3.9+ and attestation-cli on PATH. Writes <instance id>.known_hosts
only if every check passes.
"""
import base64
import hashlib
import json
import os
import struct
import subprocess
import sys
import urllib.request

API = "https://api.cloud.confidential.ai"
VERSION = "confos/ssh-host-keys/v1"


def fetch(url, data=None, headers=None):
    request = urllib.request.Request(url, data=data, headers=headers or {})
    with urllib.request.urlopen(request, timeout=30) as response:
        return response.read()


def lp(value):
    return struct.pack(">I", len(value)) + value


def main(instance_id, public_keys_path):
    api_headers = {"Authorization": "Bearer " + os.environ["CC_API_KEY"], "Api-Version": "2026-10-15"}
    instance = json.loads(fetch(f"{API}/v1/instances/{instance_id}", headers=api_headers))
    tee = instance["tee"]

    # 1. The reference manifest: fetch it, and check it is the one the API names.
    manifest_ref = instance["attestation"]["referenceManifest"]
    repository = manifest_ref["uri"].split("/v2/")[1].split("/blobs/")[0]
    token = json.loads(fetch(f"https://ghcr.io/token?scope=repository:{repository}:pull"))["token"]
    raw = fetch(manifest_ref["uri"], headers={"Authorization": "Bearer " + token})
    if "sha256:" + hashlib.sha256(raw).hexdigest() != manifest_ref["digest"]:
        sys.exit("reference manifest does not match its digest")
    manifest = json.loads(raw)

    # 2. The launch binding: the pubkey file is your keys, one per line, then
    #    the line that lets the guest serve its GPUs' metrics while they are on.
    keys = [line.strip() for line in open(public_keys_path) if line.strip()]
    lines = keys + (["# confos-gpu-metrics/v1"] if instance.get("gpuMetrics") else [])
    pubkey = "".join(line + "\n" for line in lines).encode()
    binding = instance["attestation"]["launchBinding"]
    if hashlib.sha384(pubkey).hexdigest() != binding["sha384"]:
        sys.exit("the instance was launched with other keys than yours")

    # 3. A fresh quote over your own nonce, with the SSH host keys.
    attest = next(e for e in instance["endpoints"] if e["name"] == instance["attestation"]["endpoint"])
    nonce = os.urandom(32)
    body = json.dumps({"nonce": base64.b64encode(nonce).decode()}).encode()
    answer = json.loads(fetch(f"http://{attest['host']}:{attest['port']}/attest", data=body,
                              headers={"Content-Type": "application/json"}))
    if answer.get("version") != VERSION:
        sys.exit("this image does not quote its SSH host keys; send it no secret over SSH")
    host_keys = answer["ssh_host_keys"]
    blobs = [base64.b64decode(key.split()[1], validate=True) for key in host_keys]
    report_data = hashlib.sha384(lp(VERSION.encode()) + lp(nonce) + b"".join(lp(b) for b in blobs)).hexdigest()

    # 4. Check the quote: signature chain, TCB, image measurements, your keys, the nonce and host keys.
    command = ["attestation-cli", "verify", "--expected-report-data", report_data]
    if tee == "tdx":
        reference = manifest["tdx"]
        rtmr3 = hashlib.sha384(bytes(48) + hashlib.sha384(pubkey).digest()).hexdigest()
        command += ["--expected-mrtd", reference["mrtd"], "--expected-rtmr1", reference["rtmr1"],
                    "--expected-rtmr2", reference["rtmr2"], "--expected-rtmr3", rtmr3]
    else:
        vcpus = instance["compute"]["vcpus"]
        variant = next(v for v in manifest["snp_variants"] if v["smp"] == vcpus)
        command += ["--expected-launch-digest", variant["measurement"]["snp_launch_digest"],
                    "--expected-init-data", hashlib.sha256(pubkey).hexdigest()]
    result = subprocess.run(command, input=json.dumps(answer["attestation"]), text=True, capture_output=True)
    if result.returncode != 0:
        sys.exit("verification failed:\n" + result.stderr)
    claims = json.loads(result.stdout)
    if tee == "tdx":
        checks = ["signature_valid", "collateral_verified", "report_data_match",
                  "mrtd_match", "rtmr1_match", "rtmr2_match", "rtmr3_match"]
        debug = claims["claims"]["platform_data"]["td_attributes_parsed"]["debug"]
        current = claims["tcb_status"]["tcb_status"] == "UpToDate"
    else:
        checks = ["signature_valid", "report_data_match", "launch_digest_match", "init_data_match"]
        platform = claims["claims"]["platform_data"]
        debug = platform["policy"]["debug_allowed"] or platform["policy"]["migrate_ma"] or platform["vmpl"] != 0
        current = True
    failed = [name for name in checks if claims.get(name) is not True]
    if failed or debug or not current:
        sys.exit(f"verification failed: {failed or ('debug guest' if debug else 'TCB not up to date')}")

    # 5. Pin the host keys for this instance alone.
    with open(f"{instance_id}.known_hosts", "w") as known_hosts:
        for key in host_keys:
            known_hosts.write(f"{instance_id} {key}\n")
    ssh = next(e for e in instance["endpoints"] if e["name"] == "ssh")
    print(f"Verified {instance_id} ({tee}, boot {instance['boot']['count']}). Connect with:")
    print(f"  ssh -p {ssh['port']} -o UserKnownHostsFile={instance_id}.known_hosts "
          f"-o HostKeyAlias={instance_id} -o StrictHostKeyChecking=yes root@{ssh['host']}")


if __name__ == "__main__":
    main(*sys.argv[1:3])

Images that take a launch key

Images whose launch contract has access: launchKey, such as c8s-node, bind your launch key instead of SSH keys: the pubkey file holds your PEM public key exactly as you sent it, and the same RTMR[3] or HOST_DATA rule applies. When the image's attestationPublic is false it has no attest endpoint; its own service answers on a port you open, such as a c8s node's credential release on 8443, which hands the kubeconfig only to a client that verifies the node over RA-TLS and holds its launch key.

A c8s-pod instance binds its launch key the same way, with one difference on TDX: its RTMR[3] starts at the value above and is then extended with the image digest of each container the pod admits, in the order it admits them, before the container starts. A pod's RTMR[3] equals the launch-key value alone only until its first container is admitted. c8s pod-attest fetches the measured digest list from the pod's 8443 and checks that replaying it from the launch-key value gives the RTMR[3] in a fresh quote. SEV-SNP has no such register: HOST_DATA binds the launch key as for a node, and the digests are not in the quote.

Images that take a measured configuration

For access: launchFile, the pubkey file holds the exact decoded trust.initData.document bytes. The same RTMR[3] and HOST_DATA rules apply to the SHA-384 and SHA-256 returned in attestation.launchBinding. Recompute those hashes from your original file; the API does not return its contents. A c8s-cds/1 guest serves CDS on private port 8443, so open an explicit ingress and use the CDS verifier with the image-and-configuration pin generated by c8s cds config new. A Pod's image or launch key alone cannot authenticate this separate CDS VM.

On this page