quicproquo/docs/src/introduction.md

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) on top of QUIC + TLS 1.3 transport (via quinn and 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
• Post-Compromise Security
• Threat Model

---

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	Why quicprochat? IRC+SSL, XMPP, Telegram vs. our design
Prerequisites	Toolchain and system dependencies
Building from Source	cargo build, Protobuf codegen, troubleshooting
Running the Server	Server startup, configuration, TLS cert generation
Running the Client	All CLI subcommands with examples
Demo Walkthrough	Step-by-step Alice-and-Bob narrative with sequence diagram
Architecture Overview	Crate boundaries, service architecture, data flow
Protocol Layers	Deep dives into QUIC/TLS, Protobuf framing, MLS, Hybrid KEM
Wire Format Reference	Protobuf schema documentation and method ID table
Cryptography	Identity keys, key lifecycle, forward secrecy, PCS, threat model
Design Rationale	ADRs and protocol design decisions
Roadmap	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.

---

License

quicprochat is released under the MIT license. See LICENSE in the repository root.