Skip to main content

TEE Attestor

The TEE Attestor is the security-critical core of the zkIdentity system. It runs inside a Trusted Execution Environment -- a hardware-isolated enclave that ensures even the server operator cannot inspect or tamper with the data being processed. This document covers the attestor's architecture, responsibilities, security guarantees, and operational characteristics.

What is a Trusted Execution Environment?​

A Trusted Execution Environment (TEE) is a secure area within a processor that guarantees code and data loaded inside are protected with respect to confidentiality and integrity. TEEs provide three fundamental guarantees:

  1. Confidentiality: Data inside the enclave cannot be read by any external process, including the operating system, hypervisor, or server administrator.
  2. Integrity: Code running inside the enclave cannot be modified by external processes. Any tampering attempt is detected and causes the enclave to halt.
  3. Attestation: The enclave can produce a cryptographic proof that specific code is running inside a genuine TEE. This allows remote parties to verify that the attestor is legitimate.

zkIdentity leverages these properties to ensure that sensitive KYC data (API keys, provider responses, user documents) is processed in an environment where no party -- including Hadinet Africa -- can access the raw data.

Attestor Responsibilities​

The attestor performs five primary functions within the verification pipeline:

1. KYC Orchestration​

The attestor manages the lifecycle of verification sessions:

  • Session creation: When a user initiates verification, the attestor creates a session with the chosen KYC provider. This involves authenticating with the provider's API using credentials stored inside the TEE.
  • Webhook reception: The attestor exposes a webhook endpoint that KYC providers call to report verification results.
  • Result fetching: After receiving a webhook notification, the attestor fetches the full verification result from the provider's API.
User Request -> Attestor -> Provider API (create session)
                              |
Provider completes verification
                              |
Provider -> Attestor webhook -> Provider API (fetch result)

2. ZK Proof Generation​

After fetching the verification result, the attestor invokes zkFetch to generate 14 ZK proofs via TLS tunnels. This process is described in detail in ZK Proof System. The key point is that proof generation occurs entirely within the TEE, ensuring that the provider's raw response never leaves the secure enclave.

3. Document Encryption​

When verification involves document references, the attestor encrypts these references before they leave the TEE. The encryption key is derived from the user's wallet public key, ensuring only the user's wallet can decrypt the data.

4. Metadata Extraction​

The attestor extracts non-PII metadata from the provider's response for on-chain recording. This extraction follows strict rules:

Stored on-chain (non-PII):

  • Verification status (verified / rejected / pending)
  • Provider name (smile_id / plaid)
  • Country code
  • Verification level
  • ZK proof
  • Timestamp

Never stored (PII):

  • Full name
  • Date of birth
  • Document numbers (ID numbers)
  • Photographs or biometric data
  • Address
  • Phone number

The extraction logic is hardcoded in the attestor's source code and can be audited by inspecting the TEE's code measurement hash.

5. Rollup Submission​

After proof generation and document encryption, the attestor packages the attestation and submits it to the Cartesi rollup. The submission is signed with the attestor's enclave key, allowing the rollup to verify that the attestation came from a genuine TEE instance.

Security Guarantees​

Memory Isolation​

All data processed by the attestor -- including provider API keys, raw verification results, and encryption keys -- resides in enclave memory that is inaccessible to:

  • The host operating system
  • The hypervisor (in cloud deployments)
  • Other processes on the same machine
  • Physical memory inspection (encrypted by the CPU)

Code Integrity​

The attestor's code is measured (hashed) when loaded into the TEE. This measurement is included in the TEE's attestation report. Anyone can verify that the attestor is running the exact, audited version of the code by checking the measurement against the published hash.

Remote Attestation​

The TEE produces a cryptographic attestation report that can be verified by remote parties. This report includes:

  • The code measurement hash (proving which code is running)
  • The platform identity (proving the TEE is genuine hardware)
  • A user-supplied nonce (preventing replay attacks)

The Cartesi rollup verifies the attestor's remote attestation before accepting any submissions.

Sealed Storage​

Provider API keys and other long-lived secrets are stored using the TEE's sealed storage mechanism. Sealed data is encrypted with a key derived from the enclave's identity, meaning:

  • The data can only be decrypted by the same enclave code on the same platform.
  • If the attestor code is modified, sealed data becomes inaccessible.
  • If the platform hardware changes, sealed data must be re-provisioned.

Attestor Lifecycle​

Initialization​

When the attestor starts, it performs the following initialization sequence:

  1. Confirms it is running inside a genuine TEE.
  2. Decrypts provider API keys and configuration from sealed storage.
  3. Generates or loads the attestor's signing key pair.
  4. Verifies connectivity to configured KYC providers.
  5. Verifies connectivity to the Cartesi rollup input endpoint.
  6. Begins accepting webhook callbacks from providers.
  7. Begins responding to health check probes.

Steady State​

During normal operation, the attestor processes verification requests concurrently. Each request is handled in an isolated context within the enclave to prevent cross-contamination between sessions.

Shutdown​

On shutdown, the attestor:

  1. Stops accepting new verification requests.
  2. Completes any in-progress verifications (with a configurable timeout).
  3. Flushes any pending rollup submissions.
  4. Secures sealed storage.
  5. Exits cleanly.

Failure Recovery​

If the attestor crashes or is terminated unexpectedly:

  • In-progress verifications are lost and must be retried by the user.
  • Completed but unsubmitted attestations may be recovered from a write-ahead log on restart.
  • Sealed storage integrity is maintained by the TEE hardware.