# Introduction **quicprochat** is a research-oriented, end-to-end encrypted group messaging system written in Rust. It layers the Messaging Layer Security protocol (MLS, [RFC 9420](https://datatracker.ietf.org/doc/rfc9420/)) on top of QUIC + TLS 1.3 transport (via [quinn](https://github.com/quinn-rs/quinn) and [rustls](https://github.com/rustls/rustls)), with all service RPCs framed using a compact binary Protocol Buffers format over a custom framing layer. The project exists to explore how modern transport encryption (QUIC), a formally specified group key agreement protocol (MLS), and post-quantum hybrid key encapsulation compose in practice -- and to provide a readable, auditable reference implementation for security researchers, protocol designers, and Rust developers who want to study or extend the design. --- ## Protocol stack ``` +---------------------------------------------+ | Application / MLS ciphertext | <- group key ratchet (RFC 9420) +---------------------------------------------+ | Protobuf framing (custom binary header) | <- typed, length-prefixed framing +---------------------------------------------+ | QUIC + TLS 1.3 (quinn/rustls) | <- mutual auth + transport secrecy +---------------------------------------------+ ``` Each layer addresses a distinct concern: 1. **QUIC + TLS 1.3** provides authenticated, confidential transport with 0-RTT connection establishment and multiplexed streams. The server presents a TLS 1.3 certificate (self-signed by default); the client verifies it against a local trust anchor. ALPN negotiation uses the token `qpc`. 2. **Protobuf framing** defines the wire format for all service operations across 44 RPC methods. Each request carries a `[method_id: u16][request_id: u32][payload_len: u32]` header followed by a Protobuf-encoded payload. Server-to-client push events use a separate frame type on QUIC uni-streams. Message definitions live in `proto/qpc/v1/*.proto` and are compiled to Rust with `prost` at build time. 3. **MLS (RFC 9420)** provides the group key agreement layer. Each participant holds an Ed25519 identity keypair and generates single-use HPKE KeyPackages. The MLS epoch ratchet delivers forward secrecy and post-compromise security: compromising a member's state at epoch *n* does not reveal plaintext from epochs *< n* (forward secrecy) or *> n+1* (post-compromise security, once the compromised member updates). --- ## Security properties | Property | Mechanism | |---|---| | Transport confidentiality | TLS 1.3 over QUIC (`rustls` with `TLS13` only) | | Transport authentication | TLS 1.3 server certificate (self-signed, SANs: `localhost`, `127.0.0.1`, `::1`) | | Group key agreement | `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519` | | Post-compromise security (PCS) | MLS epoch ratchet -- each Commit advances the key schedule | | Post-quantum readiness | X25519 + ML-KEM-768 hybrid KEM envelope | | Identity | Ed25519 (`ed25519-dalek`); public key used as MLS `BasicCredential` | | Password auth | OPAQUE (password never sent to server) | | Metadata protection | Sealed sender + message padding | | Local storage | SQLCipher + Argon2id + ChaCha20-Poly1305 | | Framing | Protobuf (prost) with custom binary header (method_id, request_id, length) | For a deeper discussion of the cryptographic guarantees, threat model, and known gaps, see: - [Forward Secrecy](cryptography/forward-secrecy.md) - [Post-Compromise Security](cryptography/post-compromise-security.md) - [Threat Model](cryptography/threat-model.md) --- ## Who is this for? **Security researchers** studying how MLS composes with QUIC transport and post-quantum hybrid KEM. The codebase spans 9 workspace crates with clear cryptographic boundaries for auditability. **Protocol designers** evaluating MLS deployment patterns. quicprochat implements a concrete Authentication Service (AS) and Delivery Service (DS) pair, demonstrating single-use KeyPackage lifecycle, Welcome routing, and epoch advancement in a live system. **Application developers** building on the platform via the Rust SDK: - **`quicprochat-sdk`** -- `QpqClient` with async event streams and a `ConversationStore` - **C FFI** -- cross-language integration via `quicprochat-plugin-api` **Rust developers** looking for a working example of: - `quinn` + `rustls` server/client setup with self-signed certificates - Custom binary framing over QUIC bidirectional streams - `openmls` group creation, member addition, and application message encryption - `zeroize`-on-drop key material handling --- ## Quick links | Section | What you will find | |---|---| | **[Comparison with Classical Protocols](design-rationale/protocol-comparison.md)** | **Why quicprochat? IRC+SSL, XMPP, Telegram vs. our design** | | [Prerequisites](getting-started/prerequisites.md) | Toolchain and system dependencies | | [Building from Source](getting-started/building.md) | `cargo build`, Protobuf codegen, troubleshooting | | [Running the Server](getting-started/running-the-server.md) | Server startup, configuration, TLS cert generation | | [Running the Client](getting-started/running-the-client.md) | All CLI subcommands with examples | | [Demo Walkthrough](getting-started/demo-walkthrough.md) | Step-by-step Alice-and-Bob narrative with sequence diagram | | [Architecture Overview](architecture/overview.md) | Crate boundaries, service architecture, data flow | | [Protocol Layers](protocol-layers/overview.md) | Deep dives into QUIC/TLS, Protobuf framing, MLS, Hybrid KEM | | [Wire Format Reference](wire-format/overview.md) | Protobuf schema documentation and method ID table | | [Cryptography](cryptography/overview.md) | Identity keys, key lifecycle, forward secrecy, PCS, threat model | | [Design Rationale](design-rationale/overview.md) | ADRs and protocol design decisions | | [Roadmap](roadmap/milestones.md) | Milestone tracker and future research directions | --- ## Current status quicprochat is a **research project** with production-grade features. It has not been audited by a third party. The test suite covers 301 tests across core, server, client, E2E, and P2P modules. **What works today:** - OPAQUE password authentication (register + login, 4-method handshake) - 44 Protobuf RPC methods across 14 proto files and 9 workspace crates - MLS group creation, member add, message encryption, and epoch advancement - Hybrid X25519 + ML-KEM-768 key encapsulation for post-quantum readiness - SQLCipher-backed local storage with Argon2id key derivation - Key transparency (REVOKE, CHECK_REVOCATION, AUDIT) - Multi-device management and push notification registration - Blob storage (upload/download) - Federation relay for cross-server message delivery - Content moderation (report, ban, unban) - Account recovery bundle store **Known limitations:** - MLS credentials use `CredentialType::Basic` (raw public key). A production system would bind credentials to a certificate authority or use X.509 certificates. - The hybrid KEM envelope is implemented and tested, but not yet integrated into the OpenMLS CryptoProvider for full post-quantum MLS (planned for a future milestone). - Browser connectivity requires a WebSocket-to-Protobuf bridge proxy (not yet included). For the full milestone tracker, see [Milestones](roadmap/milestones.md). --- ## License quicprochat is released under the **MIT** license. See `LICENSE` in the repository root.