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:
121
docs/src/appendix/references.md
Normal file
121
docs/src/appendix/references.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# References and Further Reading
|
||||
|
||||
This page collects the standards, crate documentation, and research papers
|
||||
referenced throughout the quicnprotochat documentation. Entries are organised by
|
||||
category.
|
||||
|
||||
---
|
||||
|
||||
## Standards and RFCs
|
||||
|
||||
| Reference | Description |
|
||||
|-----------|-------------|
|
||||
| [RFC 9420 -- The Messaging Layer Security (MLS) Protocol](https://datatracker.ietf.org/doc/rfc9420/) | The group key agreement protocol used by quicnprotochat. Defines KeyPackages, Welcome messages, Commits, the ratchet tree, epoch advancement, and the security properties (forward secrecy, post-compromise security). See [MLS (RFC 9420)](../protocol-layers/mls.md). |
|
||||
| [RFC 9000 -- QUIC: A UDP-Based Multiplexed and Secure Transport](https://datatracker.ietf.org/doc/rfc9000/) | The transport protocol underlying quicnprotochat's primary connection layer. Provides multiplexed streams, 0-RTT connection establishment, and built-in congestion control. See [QUIC + TLS 1.3](../protocol-layers/quic-tls.md). |
|
||||
| [RFC 9001 -- Using TLS to Secure QUIC](https://datatracker.ietf.org/doc/rfc9001/) | Defines how TLS 1.3 is integrated into QUIC for authentication and key exchange. quicnprotochat uses this via the `quinn` + `rustls` stack. |
|
||||
| [RFC 8446 -- The Transport Layer Security (TLS) Protocol Version 1.3](https://datatracker.ietf.org/doc/rfc8446/) | The TLS version used exclusively by quicnprotochat (no TLS 1.2 fallback). Provides the handshake, key schedule, and record layer for QUIC transport security. |
|
||||
| [RFC 9180 -- Hybrid Public Key Encryption (HPKE)](https://datatracker.ietf.org/doc/rfc9180/) | The public-key encryption scheme used internally by MLS for encrypting to KeyPackage init keys. quicnprotochat's MLS ciphersuite uses DHKEM(X25519, HKDF-SHA256) with AES-128-GCM. |
|
||||
| [NIST FIPS 203 -- Module-Lattice-Based Key-Encapsulation Mechanism Standard (ML-KEM)](https://csrc.nist.gov/pubs/fips/203/final) | The post-quantum KEM standard. quicnprotochat plans to use ML-KEM-768 in a hybrid construction with X25519 at milestone M7. See [Post-Quantum Readiness](../cryptography/post-quantum-readiness.md). |
|
||||
| [Noise Protocol Framework](https://noiseprotocol.org/noise.html) | The framework defining the Noise\_XX handshake pattern used in quicnprotochat's M1 transport stack. Provides mutual authentication and channel encryption. See [Noise\_XX Handshake](../protocol-layers/noise-xx.md). |
|
||||
| [Cap'n Proto specification](https://capnproto.org/) | The zero-copy serialisation format and RPC system used for all quicnprotochat wire messages and service interfaces. See [Cap'n Proto Serialisation and RPC](../protocol-layers/capn-proto.md). |
|
||||
| [draft-ietf-tls-hybrid-design -- Hybrid Key Exchange in TLS 1.3](https://datatracker.ietf.org/doc/draft-ietf-tls-hybrid-design/) | The combiner approach used by quicnprotochat's hybrid KEM construction (X25519 shared secret concatenated with ML-KEM-768 shared secret, fed through HKDF). See [Hybrid KEM](../protocol-layers/hybrid-kem.md). |
|
||||
| [RFC 9497 -- OPAQUE](https://datatracker.ietf.org/doc/rfc9497/) | Asymmetric password-authenticated key exchange. Considered for future authentication (see [Future Research](../roadmap/future-research.md)). |
|
||||
|
||||
---
|
||||
|
||||
## Rust Crate Documentation
|
||||
|
||||
| Crate | docs.rs | Role in quicnprotochat |
|
||||
|-------|---------|----------------------|
|
||||
| `openmls` | [docs.rs/openmls](https://docs.rs/openmls/) | MLS protocol implementation: group creation, member addition, Welcome processing, application message encryption/decryption. See [MLS (RFC 9420)](../protocol-layers/mls.md). |
|
||||
| `openmls_rust_crypto` | [docs.rs/openmls_rust_crypto](https://docs.rs/openmls_rust_crypto/) | Pure-Rust cryptographic backend for openmls. Provides the `OpenMlsRustCrypto` provider used by `GroupMember`. |
|
||||
| `quinn` | [docs.rs/quinn](https://docs.rs/quinn/) | QUIC transport implementation. Provides the `Endpoint`, `Connection`, and stream types for client and server. See [QUIC + TLS 1.3](../protocol-layers/quic-tls.md). |
|
||||
| `rustls` | [docs.rs/rustls](https://docs.rs/rustls/) | TLS 1.3 implementation used by `quinn`. Configured with `TLS13` cipher suites only and custom certificate verification. |
|
||||
| `snow` | [docs.rs/snow](https://docs.rs/snow/) | Noise Protocol Framework implementation. Provides the Noise\_XX handshake for the M1 transport stack. See [Noise\_XX Handshake](../protocol-layers/noise-xx.md). |
|
||||
| `capnp` | [docs.rs/capnp](https://docs.rs/capnp/) | Cap'n Proto serialisation library. Used for building and reading all wire messages. |
|
||||
| `capnp-rpc` | [docs.rs/capnp-rpc](https://docs.rs/capnp-rpc/) | Cap'n Proto RPC framework. Provides the async RPC system for `NodeService`. Runs inside the QUIC encrypted channel. |
|
||||
| `capnpc` | [docs.rs/capnpc](https://docs.rs/capnpc/) | Cap'n Proto compiler invoked at build time (`build.rs`) to generate Rust types from `.capnp` schemas. |
|
||||
| `ml-kem` | [docs.rs/ml-kem](https://docs.rs/ml-kem/) | ML-KEM (NIST FIPS 203) implementation. Vendored in the workspace for the planned hybrid post-quantum KEM (M7). |
|
||||
| `ed25519-dalek` | [docs.rs/ed25519-dalek](https://docs.rs/ed25519-dalek/) | Ed25519 signing and verification. Used for MLS identity credentials (`BasicCredential`). See [Ed25519 Identity Keys](../cryptography/identity-keys.md). |
|
||||
| `x25519-dalek` | [docs.rs/x25519-dalek](https://docs.rs/x25519-dalek/) | X25519 Diffie-Hellman key exchange. Used for Noise\_XX transport authentication. See [X25519 Transport Keys](../cryptography/transport-keys.md). |
|
||||
| `zeroize` | [docs.rs/zeroize](https://docs.rs/zeroize/) | Secure memory zeroisation. All private key types implement `Zeroize + ZeroizeOnDrop`. See [Key Lifecycle and Zeroization](../cryptography/key-lifecycle.md). |
|
||||
| `tokio` | [docs.rs/tokio](https://docs.rs/tokio/) | Async runtime. All server and client I/O runs on Tokio. |
|
||||
| `clap` | [docs.rs/clap](https://docs.rs/clap/) | CLI argument parser for the client binary. |
|
||||
| `dashmap` | [docs.rs/dashmap](https://docs.rs/dashmap/) | Concurrent hash map. Used for the in-memory AS key store and DS delivery queues (to be replaced by SQLite at M6). |
|
||||
| `tracing` | [docs.rs/tracing](https://docs.rs/tracing/) | Structured logging framework. Used throughout the server for request logging and diagnostics. |
|
||||
| `thiserror` | [docs.rs/thiserror](https://docs.rs/thiserror/) | Derive macro for typed error enums in library crates. |
|
||||
| `anyhow` | [docs.rs/anyhow](https://docs.rs/anyhow/) | Flexible error handling for application crates (server, client). |
|
||||
|
||||
---
|
||||
|
||||
## Research Papers and Background
|
||||
|
||||
### MLS Motivation and Design
|
||||
|
||||
**"On Ends-to-Ends Encryption: Asynchronous Group Messaging with Strong Security Guarantees"**
|
||||
Katriel Cohn-Gordon, Cas Cremers, Luke Garratt, Jon Millican, and Kevin Milner.
|
||||
*ACM CCS 2018.*
|
||||
|
||||
This paper analyses the security properties of group messaging protocols and
|
||||
motivates the design of MLS. It defines the security goals (forward secrecy,
|
||||
post-compromise security, asynchronous operation) that MLS formalises into a
|
||||
protocol. Essential background for understanding why quicnprotochat uses MLS
|
||||
rather than extending the Signal protocol to groups.
|
||||
|
||||
### Signal Protocol
|
||||
|
||||
**"The Double Ratchet Algorithm"**
|
||||
Trevor Perrin and Moxie Marlinspike.
|
||||
[signal.org/docs/specifications/doubleratchet](https://signal.org/docs/specifications/doubleratchet/)
|
||||
|
||||
Defines the double ratchet used in Signal's 1:1 messaging. Relevant as a
|
||||
potential optimisation for quicnprotochat's 1:1 channels (see
|
||||
[Future Research: Double-Ratchet DM Layer](../roadmap/future-research.md#double-ratchet-dm-layer))
|
||||
and as background for understanding how MLS generalises ratcheting to groups.
|
||||
|
||||
**"The X3DH Key Agreement Protocol"**
|
||||
Moxie Marlinspike and Trevor Perrin.
|
||||
[signal.org/docs/specifications/x3dh](https://signal.org/docs/specifications/x3dh/)
|
||||
|
||||
Defines the extended triple Diffie-Hellman key agreement used in Signal's initial
|
||||
key exchange. MLS KeyPackages serve an analogous role to X3DH's prekeys,
|
||||
enabling asynchronous group setup.
|
||||
|
||||
### Post-Quantum Cryptography
|
||||
|
||||
**"CRYSTALS-Kyber: A CCA-Secure Module-Lattice-Based KEM"**
|
||||
Roberto Avanzi et al.
|
||||
[NIST PQC Round 3 submission](https://pq-crystals.org/kyber/)
|
||||
|
||||
The predecessor to ML-KEM (NIST FIPS 203). CRYSTALS-Kyber was selected by NIST
|
||||
and standardised as ML-KEM. quicnprotochat uses the `ml-kem` crate which
|
||||
implements the final FIPS 203 standard.
|
||||
|
||||
### Noise Protocol
|
||||
|
||||
**"The Noise Protocol Framework"**
|
||||
Trevor Perrin.
|
||||
[noiseprotocol.org/noise.html](https://noiseprotocol.org/noise.html)
|
||||
|
||||
The specification for the Noise protocol framework, including the XX handshake
|
||||
pattern used in quicnprotochat's M1 transport stack.
|
||||
|
||||
### Metadata Resistance
|
||||
|
||||
**"Sealed Sender"**
|
||||
Signal Blog.
|
||||
[signal.org/blog/sealed-sender](https://signal.org/blog/sealed-sender/)
|
||||
|
||||
Describes Signal's approach to hiding sender identity from the server. Relevant
|
||||
to quicnprotochat's future research on metadata resistance (see
|
||||
[Future Research](../roadmap/future-research.md)).
|
||||
|
||||
---
|
||||
|
||||
## Cross-references
|
||||
|
||||
- [Glossary](glossary.md) -- definitions of terms used in these references
|
||||
- [Protocol Layers Overview](../protocol-layers/overview.md) -- how the protocols layer in quicnprotochat
|
||||
- [Cryptography Overview](../cryptography/overview.md) -- cryptographic properties and threat model
|
||||
- [Future Research](../roadmap/future-research.md) -- technologies under consideration
|
||||
- [Milestones](../roadmap/milestones.md) -- current project status
|
||||
Reference in New Issue
Block a user