How signalapp/sparsepostquantumratchet works
Project Type and Purpose
• Type: A Rust cryptographic library (crate) implementing a post-quantum secure ratchet protocol.
• Purpose: Produce message keys for encryption/decryption to provide Forward Secrecy (FS) and Post-Compromise Security (PCS).
• Not a standalone messaging service—designed for integration into hybrid secure messaging protocols.
File Structure
Top-level:
• Cargo.toml / build.rs – Rust build configuration and custom build script.
• hax.py, proofs/ – Tools and artifacts for formal verification (F* extraction, ProVerif models).
• benches/ – Benchmark harnesses for performance testing.
• src/ – Core Rust modules:
– chain.rs: Symmetric ratchet state machine
– v1/: ML-KEM braid public ratchet implementation
– encoding/: Erasure coding (Reed-Solomon), finite-field arithmetic
– authenticator.rs: Message authentication support
– kdf.rs: Key derivation function
– proto.rs / proto/pq_ratchet.proto: Protobuf definitions & codegen for message framing
– serialize.rs: (De)serialization utilities
– test/: Integration and behavior tests
– util.rs: Shared helper routines
Extract Architectural Insights from the README
• Core protocol split into:
– Public ratchet (v1/ML-KEM Braid)
– Symmetric ratchet (chain.rs)
– Encoding layer for chunked message resilience
• Formal verification pipeline: hax (F* extraction) + ProVerif models
• CI workflows trigger tests, benchmarks, and proofs
a. Main Components
1. API Layer (public Rust crate interface)
2. Public Ratchet Module (src/v1)
3. Symmetric Ratchet Module (src/chain.rs)
4. Encoding Layer (src/encoding)
5. Serialization & Protobuf (src/proto, serialize.rs)
6. Authenticator & KDF (src/authenticator.rs, src/kdf.rs)
7. Tests & Benchmarks (src/test, benches/)
8. Formal Verification Tools (hax.py, proofs/fstar, proofs/proverif)
9. Build & CI (build.rs, .github/workflows/*.yml)
b. Relationships & Data Flows
• Consumer calls into API → assembles handshake parameters → Public Ratchet
• Public Ratchet produces shared secret → fed into KDF → Symmetric Ratchet
• Symmetric Ratchet state → derives message keys
• Outgoing message keys + plaintext → Encoding layer (chunking + erasure codes)
• Chunks → Serializer / Protobuf → Network transport (external)
• Incoming raw data → Deserializer → Encoding decode → Symmetric ratchet decrypt
• All modules rely on util.rs for shared math and byte-buffer routines
c. Architectural Patterns & Principles
• Layered design: Key agreement → symmetric state machine → encoding → serialization
• Clear separation of public vs. symmetric ratchet concerns
• Formal‐verification pipeline isolated from core library code
• Benchmarks and tests decoupled from production API
d. Key Technologies & Frameworks
• Rust + Cargo for build and dependency management
• Protobuf (via proto/pq_ratchet.proto)
• hax + F* for machine‐checked proofs
• ProVerif for symbolic security proofs
• Reed-Solomon erasure coding (in encoding/polynomial.rs)
Diagramming Recommendations
– Handshake → shared secret → KDF → ratchet → keys → encode → serialize
– Blue: Core ratchet logic
– Green: Encoding & serialization
– Orange: Verification & CI
Essential Architectural Elements
• Public-ratchet vs. symmetric-ratchet layers
• Encoding resilience (chunking + erasure codes)
• Protobuf framing boundary
• Verification pipeline (hax → F* → ProVerif)
• CI/build orchestration