How signalapp/securevaluerecovery2 works
Project Type and Purpose
• This is a security-critical, full-stack service that combines:
– A host-side Go microservice (the “host” process) exposing APIs to clients.
– A trusted-execution enclave (C++ code) running inside hardware TEEs (SGX, Nitro, SEV-SNP).
– A lightweight in-memory Raft consensus layer for replication and state durability.
– A build/deploy toolchain (Docker, Packer) and trusted VM image builder for SEV.
• Its purpose is to securely store low-entropy client secrets behind a rate-limited recovery protocol, using TEEs to guard keys and state.
a. Clients
• Mobile/desktop applications or CLI tools that call the host over HTTP/gRPC/REST/WebSocket.
• Responsible for pin input, OPRF flows, attestation verification.
b. Host Service (Go)
• HTTP/gRPC server with sub-modules:
– Web handlers (host/web/handlers)
– Control CLI (host/cmd/control, svr2client, svr3client)
– Configuration loader (host/config)
– Dispatch layer that serializes requests into protobufs and routes them to the enclave (host/dispatch)
– Health, metrics, rate-limiting middleware
• Manages enclave lifecycle: initialization, remote attestation, secure channel
• Integrates a Rust client (host/rustclient) and communicates via protobufs over a UNIX or TCP socket.
c. Enclave (C++)
• Entry-point modules (ecalls/ecalls.cc) for incoming host requests.
• Core logic modules:
– Secret storage & Raft consensus (enclave/core, enclave/raft)
– Cryptography (enclave/hmac, enclave/noise, enclave/ristretto)
– Storage layer abstractions (enclave/db, enclave/fs)
– Attestation adapters (SGX in enclave/attestation/oe, Nitro in enclave/attestation/nitro, TPM2/SEV modules)
– Utilities and metrics (enclave/util, enclave/metrics)
• Shared interface definitions (in enclave/proto and shared/proto for protobuf, shared/svr2.edl for ocall/ecall).
d. Consensus & Replication
• In-memory Raft ring of enclave instances across nodes
• Host processes open peer-to-peer channels to run Raft (uses protobuf messages over network).
e. Build & Deployment Tooling
• Docker build image (docker/Dockerfile) that compiles both host and enclave
• Packer configurations and scripts in trustedimage/ to build VMs for SEV-SNP
• CI workflows (.github/workflows) to run tests and builds on PRs/pushes
Component Relationships & Data Flows
• Client → Host API: Over TLS/HTTP, passes user PIN or OPRF request.
• Host → Enclave: Via a secure channel (OE enclave socket, Nitro CLI socket, SEV VM agent) using protobuf messages defined in shared/proto.
• Enclave internal:
– ecall handlers deserialize requests → core modules
– Core invokes Raft replication to update state on peer enclaves
– Crypto modules perform OPRF or encrypt/decrypt secrets
– ecall returns result → host
• Enclave → Host ocalls: For filesystem access, logging, metrics
• Raft peer traffic: Enclave-to-enclave messages on TCP ports for consensus
• Build pipeline: Developers run make → Docker container → produce enclave.signed, host binary, trusted VM image
Architectural Patterns & Principles
• Trust boundary: clearly separate “host” untrusted process from “enclave” trusted process.
• Modular attestation adapters: one per TEE backend (SGX, Nitro, SEV, TPM2).
• Pluggable crypto stack: Noise protocol for secure channel, Ristretto OPRF for SVR3.
• High-availability via in-memory Raft: sacrificing liveness for security is a conscious choice.
• Shared IDLs (protobuf + EDL) enforce schema consistency across host/enclave.