Skip to main content

TEE Attestation

KnowledgeFlowDB runs on GCP Confidential VMs with AMD SEV-SNP hardware-encrypted memory. The attestation system allows third parties to verify that the database is running on genuine TEE hardware with the expected code.

How It Works​

TEE (Trusted Execution Environment) attestation provides cryptographic proof of three properties:

  1. Platform authenticity -- The server runs on AMD SEV-SNP hardware with encrypted memory
  2. Code integrity -- The running container image matches a known digest
  3. Freshness -- Attestation data is bound to a client-provided nonce (prevents replay)

Attestation Data Sources​

SourceOriginWhat It Proves
TEE_PLATFORMKubernetes node labels (downward API)Hardware type (e.g., GCE_AMD_SEV)
IMAGE_DIGESTDeployment metadata (env var)Container image hash
GCP Identity TokenGCP metadata serverRunning on authentic GCP infrastructure
Ed25519 SignatureDerived from encryption master keyServer possesses signing key

API Endpoints​

GET /api/v1/attestation​

Returns the current attestation state. This endpoint is public (no authentication required) to enable third-party verification.

curl -s https://tee.knowledgedataflow.org/api/v1/attestation | jq .

Response (TEE environment):

{
  "attestation_available": true,
  "image_digest": "sha256:a1b2c3d4e5f6...",
  "platform": "GCE_AMD_SEV",
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "timestamp": "2026-03-24T12:00:00.000Z"
}

Response (non-TEE environment):

{
  "attestation_available": false,
  "image_digest": null,
  "platform": null,
  "token": null,
  "timestamp": "2026-03-24T12:00:00.000Z"
}

POST /api/v1/attestation/challenge​

Challenge-response attestation with Ed25519 signing. The client sends a random nonce, and the server returns a signed hash binding the nonce to the current attestation state.

# Generate a random 32-byte nonce (hex-encoded)
NONCE=$(openssl rand -hex 32)

# Send challenge
curl -s -X POST https://tee.knowledgedataflow.org/api/v1/attestation/challenge \
  -H "Content-Type: application/json" \
  -d "{\"nonce\": \"$NONCE\"}" | jq .

Response:

{
  "nonce": "a1b2c3d4...",
  "attestation_hash": "e5f6a7b8c9d0...",
  "signature": "3045022100...",
  "public_key": "04ab12cd34...",
  "image_digest": "sha256:a1b2c3d4e5f6...",
  "platform": "GCE_AMD_SEV",
  "timestamp": "2026-03-24T12:00:00.000Z"
}

What the hash covers:

SHA-256(nonce || image_digest || platform || timestamp)

This binding ensures:

  • Freshness: Your nonce is included (prevents replay attacks)
  • Code binding: The specific image digest is attested
  • Platform binding: The TEE hardware type is attested
  • Temporal binding: The timestamp prevents stale attestation reuse

Verifying the Challenge Response​

To verify the attestation client-side:

  1. Recompute the attestation hash from the returned components
  2. Verify the Ed25519 signature against the public key
  3. Confirm the nonce matches what you sent
import hashlib
from nacl.signing import VerifyKey

# Response fields
nonce = bytes.fromhex(response["nonce"])
image_digest = (response["image_digest"] or "unknown").encode()
platform = (response["platform"] or "unknown").encode()
timestamp = response["timestamp"].encode()

# Recompute hash
expected_hash = hashlib.sha256(nonce + image_digest + platform + timestamp).hexdigest()
assert expected_hash == response["attestation_hash"]

# Verify Ed25519 signature
verify_key = VerifyKey(bytes.fromhex(response["public_key"]))
verify_key.verify(bytes.fromhex(expected_hash), bytes.fromhex(response["signature"]))

GET /api/v1/tee/nodes​

List all registered TEE nodes in the network.

curl -s https://tee.knowledgedataflow.org/api/v1/tee/nodes | jq .

Response:

{
  "nodes": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "address": "0xabc123...",
      "platform": "GCE_AMD_SEV",
      "voting_power": 100,
      "moniker": "tee-node-1",
      "registered_at": "2026-03-24T10:00:00.000Z"
    }
  ]
}

POST /api/v1/tee/register​

Register a new TEE node. The server verifies the attestation proof before accepting the registration.

curl -s -X POST https://tee.knowledgedataflow.org/api/v1/tee/register \
  -H "Content-Type: application/json" \
  -d '{
    "pub_key": [/* 32-byte Ed25519 public key */],
    "attestation_doc": "...",
    "moniker": "my-tee-node",
    "p2p_endpoint": "https://my-node:8443"
  }' | jq .

Health Endpoint Security Posture​

The standard health endpoint includes security posture information:

curl -s https://tee.knowledgedataflow.org/health | jq .security_posture
{
  "tee_platform": "GCE_AMD_SEV",
  "attestation_verified": true,
  "encryption_at_rest": true,
  "memory_encrypted": true,
  "trust_posture": "Enforced",
  "binary_hash": "sha256:a1b2c3d4e5f6..."
}
FieldDescription
tee_platformHardware TEE type (GCE_AMD_SEV, or null if not TEE)
attestation_verifiedWhether TEE platform was detected
encryption_at_restWhether property encryption is active
memory_encryptedWhether AMD SEV memory encryption is active
trust_postureEnforced, Audit, or Permissive
binary_hashContainer image digest or dev version

AMD SEV-SNP​

KnowledgeFlowDB TEE pods run on GCP Confidential VMs powered by AMD SEV-SNP (Secure Encrypted Virtualization - Secure Nested Paging):

  • Memory encryption: All VM memory is encrypted with a per-VM key managed by the AMD Secure Processor
  • Memory integrity: SEV-SNP adds integrity protection preventing memory tampering
  • Isolation: The hypervisor cannot read or modify encrypted VM memory
  • Attestation: Hardware-rooted proof that the VM is running on genuine AMD SEV hardware
note

KnowledgeFlowDB uses GCP Confidential VMs (not Confidential Space). Platform and image information is provided via Kubernetes environment variables rather than cryptographic JWT attestation tokens. This is reflected in the attestation API design.

Source Code​