COCOON Documentation

COCOON (Confidential Compute Open Network) is a decentralized AI inference network built on TON. It allows for running AI models within Trusted Execution Environments (TEEs) to ensure privacy and confidentiality.

The network consists of three primary roles:

• Workers (GPU Owners): Earn TON cryptocurrency by providing GPU compute services to serve models.
• App Developers: Integrate with the network to access low-cost, secure, and verifiable AI compute.
• Users: Access AI services with full privacy and confidentiality.

RA-TLS (Remote Attestation over TLS) is a mechanism that embeds TDX attestation directly into TLS certificates. This allows a single TLS handshake to achieve both encryption and remote attestation (proving code identity).

Unlike traditional TLS where a certificate proves DNS identity via a CA, an RA-TLS certificate is self-signed and contains a TDX quote to prove the server is running the correct, untampered code.

In COCOON, verification is bidirectional (mutual authentication):

• Client ↔ Proxy: Both verify each other's TDX images.
• Proxy ↔ Worker: Both verify each other's TDX images.

In production, seal-server is a mandatory component that runs on the host. It uses an SGX enclave to provide secure key derivation for TDX guests.

Key Requirements:

• It must be running before the worker starts.
• You must use the enclave.so (or enclave.signed.so) file included in the official distribution to ensure compatibility.
• One seal-server instance can serve multiple workers.
• It ensures that persistent keys are tied to the specific TDX image and configuration while remaining inaccessible to the host.

Note: seal-server is not required when running in test mode with the --test --fake-ton flags.

# Start seal-server (keep it running in the background)
./seal-server --enclave-path ./bin/enclave.signed.so

Key Sealing is used to protect sensitive persistent data from host access. A seal key is generated uniquely based on a combination of the following factors:

• Chip unique secret
• Guest measurement at launch
• Family ID
• Image ID
• Guest Policy

This seal key acts as a master key, from which various other keys are derived using a Key Derivation Function (KDF).

A Proxy Contract is unique to every proxy instance. Because no two instances can share a private key, every proxy instance must generate its own contract.

Key Responsibilities:

• Holding all client payments for that specific proxy.
• Notifying the proxy of incoming payments or configuration changes (client/worker).
• Processing payment and withdrawal requests.
• Committing state to the blockchain to prevent database rollbacks or state-copying attacks.

Important Note on Redeployment: Changing core parameters, such as price per token, requires a redeployment of the proxy contract. The old contract remains active until it reaches a 'safe closure' (all payments and withdrawals are completed).

RA-TLS uses self-signed X.509 certificates (depth 0) with Ed25519 keys. The certificates include custom critical extensions to hold attestation data.

Custom OIDs

We use the private enterprise OID space 1.3.6.1.4.1.12345.*. These are marked as critical, meaning non-aware TLS implementations will reject them.

• 1.3.6.1.4.1.12345.1 (TDX_QUOTE): Contains the raw binary TDX quote (~5-10 KB).
• 1.3.6.1.4.1.12345.2 (TDX_USER_CLAIMS): Contains serialized user claims.

User Claims

Currently, UserClaims consists of the certificate's Ed25519 public key (32 bytes). This is serialized as raw bytes.

GPU attestation proves the hardware is in a secure state. During the TDX guest boot, a systemd service (nvidia-tdx.service) runs the reprodebian/gpu_attest/gpu_attest.py script before cocoon-init to verify the GPU.

Verification Process

1. The script calls the NVIDIA attestation SDK.
2. It generates GPU evidence using a random nonce.
3. It verifies the evidence against a policy (reprodebian/gpu_attest/attest_policy.json).

What is verified?

• GPU architecture matches the policy.
• CC mode is enabled.
• Firmware/VBIOS measurements and signatures are valid.
• Certificates are not revoked.
• The nonce matches (prevents replay attacks).

If verification fails, the guest boot fails, preventing the worker from running on untrusted hardware.

Certificate Binding

To prevent quote reuse attacks, the certificate's public key is cryptographically bound to the TDX quote. The implementation ensures that quote.reportdata == SHA-512(user_claims), where user_claims contains the certificate's public key. If an attacker tries to use a valid quote with a different certificate, verification will fail.

Quote Replay Protection

Since TDX quotes do not include timestamps, COCOON employs several mitigations:

1. Short Lifetimes: Certificates are valid for only 1 day.
2. User Claims: Timestamps can be included in user claims (verified by policy).
3. Daily Regeneration: Certificates are regenerated frequently.
4. Runtime Freshness: Parties verify time similarity via pings during communication.

COCOON utilizes the TON blockchain to manage worker registration, payment settlements, reputation tracking, and a central registry. The architecture follows a hierarchical payment flow where clients pay proxies, and proxies pay workers.

Payment Flow Hierarchy:

1. Client Wallet: Pays for inference.
2. Proxy Contract: Receives client payments and pays workers.
3. Worker Contract: Receives payments from the proxy and allows workers to withdraw earnings.
4. Owner Wallet: Receives funds from the proxy owner.

When a TDX VM boots, Intel hardware measures the loaded components into specific registers. These measurements are used for attestation to prove the VM is in a known, verified state.

MRTD (Measurement Register for TD)

Contains the hash of the firmware code (TDVF) and initial page tables. This is set during VM construction and does not change after boot.

RTMR[0-3] (Runtime Measurement Registers)

• RTMR[0]: Firmware data (configuration tables, ACPI, etc.)
• RTMR[1]: Linux kernel hash (including EFI stub)
• RTMR[2]: Initrd hash and kernel boot parameters
• RTMR[3]: Used by COCOON to store the config hash. This allows different configurations to result in different attestation quotes.