feat: add post-quantum hybrid KEM + SQLCipher persistence
Feature 1 — Post-Quantum Hybrid KEM (X25519 + ML-KEM-768): - Create hybrid_kem.rs with keygen, encrypt, decrypt + 11 unit tests - Wire format: version(1) | x25519_eph_pk(32) | mlkem_ct(1088) | nonce(12) | ct - Add uploadHybridKey/fetchHybridKey RPCs to node.capnp schema - Server: hybrid key storage in FileBackedStore + RPC handlers - Client: hybrid keypair in StoredState, auto-wrap/unwrap in send/recv/invite/join - demo-group runs full hybrid PQ envelope round-trip Feature 2 — SQLCipher Persistence: - Extract Store trait from FileBackedStore API - Create SqlStore (rusqlite + bundled-sqlcipher) with encrypted-at-rest SQLite - Schema: key_packages, deliveries, hybrid_keys tables with indexes - Server CLI: --store-backend=sql, --db-path, --db-key flags - 5 unit tests for SqlStore (FIFO, round-trip, upsert, channel isolation) Also includes: client lib.rs refactor, auth config, TOML config file support, mdBook documentation, and various cleanups by user. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
100
docs/src/introduction.md
Normal file
100
docs/src/introduction.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# Introduction
|
||||
|
||||
**quicnprotochat** 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 and wire messages framed using [Cap'n Proto](https://capnproto.org/). The project exists to explore how modern transport encryption (QUIC), a formally specified group key agreement protocol (MLS), and a zero-copy serialisation format (Cap'n Proto) 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)
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Cap'n Proto RPC │ <- typed, schema-versioned 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 `b"capnp"`.
|
||||
|
||||
2. **Cap'n Proto RPC** defines the wire schema for all service operations (KeyPackage upload/fetch, message enqueue/fetch, health probes). Schemas live in `schemas/*.capnp` and are compiled to Rust at build time. Because Cap'n Proto uses a pointer-based layout, messages can be read without an unpacking step -- though quicnprotochat currently uses the unpacked wire format for simplicity.
|
||||
|
||||
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 |
|
||||
| Identity | Ed25519 (`ed25519-dalek`); public key used as MLS `BasicCredential` |
|
||||
| Framing | Cap'n Proto (unpacked wire format, schema-versioned) |
|
||||
|
||||
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 Cap'n Proto framing. The codebase is intentionally small (four crates, ~2 500 lines of non-generated Rust) so that every cryptographic boundary is auditable.
|
||||
|
||||
**Protocol designers** evaluating MLS deployment patterns. quicnprotochat 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.
|
||||
|
||||
**Rust developers** looking for a working example of:
|
||||
|
||||
- `quinn` + `rustls` server/client setup with self-signed certificates
|
||||
- `capnp-rpc` over QUIC bidirectional streams (including the `!Send` / `LocalSet` constraint)
|
||||
- `openmls` group creation, member addition, and application message encryption
|
||||
- `zeroize`-on-drop key material handling
|
||||
|
||||
---
|
||||
|
||||
## Quick links
|
||||
|
||||
| Section | What you will find |
|
||||
|---|---|
|
||||
| [Prerequisites](getting-started/prerequisites.md) | Toolchain and system dependencies |
|
||||
| [Building from Source](getting-started/building.md) | `cargo build`, Cap'n Proto 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 |
|
||||
| [Docker Deployment](getting-started/docker.md) | `docker compose up`, multi-stage build |
|
||||
| [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, Cap'n Proto, MLS, Hybrid KEM |
|
||||
| [Wire Format Reference](wire-format/overview.md) | Cap'n Proto schema documentation |
|
||||
| [Cryptography](cryptography/overview.md) | Identity keys, key lifecycle, forward secrecy, PCS, threat model |
|
||||
| [Design Rationale](design-rationale/overview.md) | ADRs and "why not Signal/Matrix" comparison |
|
||||
| [Roadmap](roadmap/milestones.md) | Milestone tracker and future research directions |
|
||||
|
||||
---
|
||||
|
||||
## Current status
|
||||
|
||||
quicnprotochat is a **proof of concept**. It has not been audited by a third party.
|
||||
|
||||
Known limitations:
|
||||
|
||||
- The server uses a **self-signed TLS certificate** by default. No certificate pinning or CA-based server identity is enforced.
|
||||
- MLS credentials use `CredentialType::Basic` (raw public key). A production system would bind credentials to a certificate authority or use X.509 certificates.
|
||||
- The Delivery Service performs **no authentication** of the `recipientKey` field -- anyone who knows a recipient's public key can enqueue messages for them. Access control is a future milestone.
|
||||
- The HPKE init private key generated during `register-state` is held in-process memory (or on-disk via the key store). If the process exits before the corresponding Welcome is consumed, `join` will fail because the private key is lost.
|
||||
- Group membership is currently limited to two-party groups in practice. Multi-party Commit fan-out is planned for milestone M5.
|
||||
|
||||
For the full milestone tracker, see [Milestones](roadmap/milestones.md).
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
quicnprotochat is released under the **MIT** license. See `LICENSE` in the repository root.
|
||||
Reference in New Issue
Block a user