Verify

Enclave Verification Guide

This page explains how to verify that our treasury enclave is running exactly the code we claim. AWS Nitro Enclaves provide cryptographic proof — called remote attestation — that ties a running enclave to a specific, measurable code image. No one (including us) can modify code inside the enclave without changing its measurement hash.

What is an Enclave?

An AWS Nitro Enclave is an isolated virtual machine with no persistent storage, no network access, and no interactive login — not even for the server operator. The only way to communicate with it is through a narrow, predefined API. Private keys never leave the enclave's memory.

The enclave's code is measured at launch by the Nitro hypervisor, producing a PCR0 hash — a SHA-384 fingerprint of the entire enclave image. This hash is embedded in a cryptographically signed attestation document issued by AWS, which anyone can verify.

The Three Pillars of Verification

1. Source Code

Everything that runs inside the enclave is published below. There is no additional code — the Dockerfile copies only these files into the enclave image.

Dockerfile

The enclave image is built from Dockerfile.enclave:

• Base image: Amazon Linux 2 (multi-stage build)
• Builder stage: Installs Python 3.8 and the minimal dependency set, then downloads and SHA-256-verifies the official AWS Nitro root certificate
• Runtime stage: Copies only the enclave application code (no database, no API server, no watcher/sweeper). Generates a self-signed TLS certificate for the encrypted vsock channel. Verifies that mock/dev credentials are excluded from the image
• Baked-in policy constants: Platform fee addresses (EVM, BTC, LTC, SOL), maximum fee rate, and maximum merchant count are set as ENV variables in the Dockerfile. Because these are part of the image, they are included in the PCR0 measurement — changing any fee address changes the hash, requiring an explicit update to the allowed PCR list on the host

Production safety checks baked into the build:

• _mock_root_key.pem (dev-only mock signing key) must NOT be present — build fails if it is
• aws_nitro_root.pem (real AWS root cert) MUST be present — build fails if it is missing
• Plaintext provisioning endpoint is physically removed from the running server in production

Application Code

Dependencies

The enclave uses a minimal dependency set (requirements-enclave.txt):

2. Build Instructions

To reproduce the enclave image and independently verify the PCR0 hash, run the following on a Nitro-capable EC2 instance (e.g., m5.xlarge or any .metal instance with Nitro Enclaves enabled):

Prerequisites: Docker, nitro-cli (installed via amazon-linux-extras install aws-nitro-enclaves-cli)

# Clone the repository
git clone <repo-url>
cd backend

# Build the Docker image
docker build -f Dockerfile.enclave -t enclave-signer:latest .

# Build the Enclave Image File (EIF)
nitro-cli build-enclave \
    --docker-uri enclave-signer:latest \
    --output-file enclave-signer.eif

The nitro-cli build-enclave command outputs JSON containing the PCR measurements:

{
  "Measurements": {
    "HashAlgorithm": "Sha384",
    "PCR0": "<96-character hex string>",
    "PCR1": "...",
    "PCR2": "..."
  }
}

PCR0 is the measurement that matters — it is the SHA-384 hash of the entire enclave image. Compare it to the expected value published below.

Note on reproducibility: The enclave image generates a random TLS certificate at build time, which means a fresh build will produce a different PCR0 than ours. The purpose of publishing the source code is so that anyone can audit what the enclave does — the attestation document from AWS proves that our specific build is what is actually running. Both pieces together provide the full guarantee.

How Attestation Works

When the enclave starts, the following happens:

1. The Nitro hypervisor measures the enclave image and records the hash as PCR0
2. The enclave generates a fresh RSA-2048 keypair in memory
3. The enclave requests an attestation document from the hypervisor via /dev/nsm, embedding its public key
4. The hypervisor returns a COSE_Sign1 document signed by the AWS Nitro root certificate, containing:
   • The PCR0 measurement
   • The enclave's public key
   • A certificate chain back to the AWS Nitro root CA
5. Anyone can fetch this attestation document and verify:
   • The signature chains back to the AWS Nitro root certificate
   • The PCR0 matches the expected value published on this page
   • The public key is bound to the attestation (so you know you're encrypting secrets for this specific enclave)

This proves that the enclave is running the exact code that produced the published PCR0, and that no one — including the server operator — has tampered with it.

What This Guarantees