How signalapp/contactdiscoveryservice-icelake works
Project Type and Purpose
• CDSI is a hybrid full-stack service combining a Java (Micronaut) host-side server with an Intel SGX enclave implemented in C.
• It exposes a WebSocket/API endpoint for client contact-discovery requests, enforces authentication and multi-tier rate limiting, and uses a secure enclave to store and query directory data.
• It ingests account updates from AWS DynamoDB/Kinesis via an AWS Lambda “filter-cds-updates” function.
Main Components
a. Client Layer
• Signal mobile/desktop clients (or any WebSocket-capable client)
b. Host Application (Java/Micronaut)
• HTTP/WebSocket API layer (WebSocketHandler)
• Authentication filter (ExternalServiceTokenAuthenticationProvider)
• Rate-limiting filters
– Connection rate limiter (Redis-backed leaky-bucket)
– Directory query rate limiter (Cosmos DB token bucket)
• Account synchronization
– DynamoDbAccountPopulator (reads from DynamoDB + Kinesis via KinesisClientFactory)
– RandomAccountPopulator (dev/mock)
• EnclaveClient (JNI wrapper for native C enclave calls)
• Health & metrics endpoints
c. Enclave (C/Open Enclave)
• Native enclave binary (loaded via shim/JNI)
• Data structures and algorithms (ohtable, path_oram, noiseutil, etc.)
• Account directory storage and secure query logic
d. AWS Lambda: filter-cds-updates
• Consumes DynamoDB stream events, filters relevant updates, writes to Kinesis
e. External Services & Data Stores
• AWS DynamoDB table + update stream
• AWS Kinesis stream
• Azure Cosmos DB (directory query rate-limiter backend)
• Redis Cluster (connection rate-limiter backend)
• Authentication secret store (external service credentials)
Key Interactions & Data Flows
1. Account update in DynamoDB → DynamoDB stream → AWS Lambda (filter) → Kinesis
2. Host service Kinesis consumer → calls DynamoDbAccountPopulator → EnclaveClient.ingestAccount()
3. Client connects via WebSocket → Authentication → Connection rate limiter (Redis) → Directory query rate limiter (Cosmos) → EnclaveClient.queryDirectory() → results → client
4. Health checks & metrics reported to Micronaut actuator endpoints
Architectural Patterns & Principles
• Layered architecture: API layer → business logic → enclave boundary → native code
• Secure enclave boundary via JNI/OpenEnclave (Separation of trust domains)
• Event-driven ingestion (AWS Lambda → Kinesis → populator)
• Pluggable account sources (DynamoDB/Kinesis vs. random/mock)
• Circuit-breaker, retry, and back-pressure (via Micronaut, Kinesis retry configs)
• Reactive/non-blocking WebSocket I/O (Micronaut Netty)