How signalapp/libsignal works
Project Type and Purpose
• This is an open-source, multi-platform library repository (“libsignal”) that implements the Signal cryptographic protocol in Rust and exposes it via language-specific bindings (Java, Swift, TypeScript/Node).
• The Rust subprojects deliver core functionality (protocol, crypto, media, attestation, zero-knowledge groups, etc.). Bridge layers (JNI, Node-API, C-API) wrap those for language environments. Language-specific modules (java/, node/, swift/) package the native libraries and provide idiomatic APIs.
Top-Level Architectural Components
A. Rust Core Crates (bottom layer)
• protocol (implements Double Ratchet, sessions, state)
• crypto (AES, hashes)
• media (mp4, webp sanitization)
• attest (SGX/HSM attestation, DCAP, SVR2)
• zkgroup & zkcredential & poksho (zero-knowledge group proofs)
• account-keys (PIN‐based key derivation)
• usernames (generation, proofs)
• device-transfer (device-to-device key transfer)
B. Bridge Layers (middle layer)
• rust/bridge/jni (generates JNI wrappers, cbindgen for Java)
• rust/bridge/node (node-gyp, N-API, TypeScript declaration generation)
• swift/SignalFfi (C-API headers)
C. Language Bindings and Packaging (top layer)
• java/ (Gradle project producing libsignal-client, libsignal-server, libsignal-android; uses JNI to load native libs)
• node/ (npm package @signalapp/libsignal-client; invokes node-gyp to build the Rust library; TypeScript definitions in node/ts)
• swift/ (Swift Package Manager target LibSignalClient; bridges via C headers from SignalFfi)
D. Tooling & CI
• bin/, justfile, build scripts (mac_setup.sh, build_helpers.py, update_versions.py)
• .github/workflows (build/test pipelines for Rust, Java, Node, Swift)
• Cargo.toml, package.json, Podspec (dependency & packaging metadata)
Relationships and Data Flows
• Bridge crates depend on specific subsets of core crates (e.g., rust/bridge/jni uses protocol, crypto, media).
• Language modules call into bridge crates via FFI (JNI for Java, N-API for Node, C for Swift).
• Build tools orchestrate: cargo builds core + bridge → cbindgen generates headers → language builds compile FFI adapters → final packages (JAR/AAR, .so/.dll/dylib, .node addon, .framework/.swiftmodule)
Architectural Patterns & Principles
• Modular crate design: each Rust feature lives in its own Cargo crate.
• Dependency inversion: language modules depend on abstracted bridge APIs, not on core internals.
• FFI boundary isolation: separate bridge crates encapsulate all unsafe/FFI code.
• Multi-language packaging: each target environment has its own build and packaging toolchain (Gradle, npm/node-gyp, SwiftPM/CocoaPods).
Elements
• Core → Bridge
• Bridge → Language Packaging
• Language Packaging → Consumer Apps
• Build Tooling → All layers (annotate “cargo build,” “node-gyp,” “Gradle,” “SwiftPM”).
• Rust crates: blue rectangles
• Bridge crates: green rounded rectangles
• Language modules: orange rectangles
• External consumers: grey clouds