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:
142
docs/src/appendix/glossary.md
Normal file
142
docs/src/appendix/glossary.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Glossary
|
||||
|
||||
Alphabetical glossary of terms used throughout the quicnprotochat documentation.
|
||||
Each entry includes a brief definition and, where applicable, a reference to the
|
||||
relevant specification or documentation page.
|
||||
|
||||
---
|
||||
|
||||
**AEAD** -- Authenticated Encryption with Associated Data. A symmetric encryption
|
||||
scheme that provides both confidentiality and integrity. quicnprotochat uses
|
||||
AES-128-GCM (in the MLS ciphersuite) and ChaCha20-Poly1305 (in the Noise
|
||||
transport). See [Cryptography Overview](../cryptography/overview.md).
|
||||
|
||||
**ALPN** -- Application-Layer Protocol Negotiation. A TLS extension that allows
|
||||
the client and server to agree on an application protocol during the TLS
|
||||
handshake. quicnprotochat uses the ALPN token `b"capnp"` to identify Cap'n Proto
|
||||
RPC connections. See [QUIC + TLS 1.3](../protocol-layers/quic-tls.md).
|
||||
|
||||
**AS** -- Authentication Service. The server component that stores and
|
||||
distributes single-use MLS KeyPackages. Clients upload KeyPackages after identity
|
||||
generation; peers fetch them to add new members to a group.
|
||||
See [Architecture Overview](../architecture/overview.md).
|
||||
|
||||
**Cap'n Proto** -- A zero-copy serialisation format with a built-in RPC system.
|
||||
quicnprotochat uses Cap'n Proto for all wire messages and service RPCs. Schemas
|
||||
live in `schemas/*.capnp` and are compiled to Rust at build time.
|
||||
See [Cap'n Proto Serialisation and RPC](../protocol-layers/capn-proto.md).
|
||||
|
||||
**Commit** -- An MLS message type that advances the group to a new epoch. When a
|
||||
member sends a Commit (e.g., after adding or removing a member), all group
|
||||
participants update their key schedule. Commits are the mechanism for both
|
||||
forward secrecy and post-compromise security.
|
||||
See [MLS (RFC 9420)](../protocol-layers/mls.md).
|
||||
|
||||
**Credential** -- An MLS identity binding that associates a member's signing key
|
||||
with their identity. quicnprotochat uses `BasicCredential`, which contains the
|
||||
raw Ed25519 public key bytes. See
|
||||
[Ed25519 Identity Keys](../cryptography/identity-keys.md).
|
||||
|
||||
**DER** -- Distinguished Encoding Rules. A binary encoding format for ASN.1
|
||||
structures, used for X.509 certificates and TLS certificate chains. The
|
||||
self-signed TLS certificate generated by quicnprotochat is DER-encoded.
|
||||
|
||||
**DS** -- Delivery Service. The server component that provides store-and-forward
|
||||
relay for opaque MLS payloads. The DS never inspects ciphertext -- it routes
|
||||
solely by recipient public key and optional channel ID.
|
||||
See [Architecture Overview](../architecture/overview.md).
|
||||
|
||||
**Ed25519** -- Edwards-curve Digital Signature Algorithm on Curve25519. Used for
|
||||
MLS identity credentials and signing (KeyPackages, Commits, group operations).
|
||||
quicnprotochat uses the `ed25519-dalek` crate.
|
||||
See [Ed25519 Identity Keys](../cryptography/identity-keys.md).
|
||||
|
||||
**Epoch** -- The version number of an MLS group's key state. Each Commit
|
||||
advances the epoch by one. Messages encrypted under epoch *n* cannot be
|
||||
decrypted by members who have advanced to epoch *n+1*, providing forward secrecy.
|
||||
See [Forward Secrecy](../cryptography/forward-secrecy.md).
|
||||
|
||||
**Forward Secrecy (FS)** -- The property that past sessions remain secure even
|
||||
if long-term keys are later compromised. In MLS, forward secrecy is achieved by
|
||||
the epoch ratchet: key material from earlier epochs is deleted when the epoch
|
||||
advances. See [Forward Secrecy](../cryptography/forward-secrecy.md).
|
||||
|
||||
**HKDF** -- HMAC-based Key Derivation Function. Used in MLS to derive symmetric
|
||||
keys from shared secrets. quicnprotochat uses HKDF-SHA256.
|
||||
|
||||
**HPKE** -- Hybrid Public Key Encryption. The public-key encryption scheme used
|
||||
in MLS for key exchange (encrypting to a KeyPackage's init key). Defined in
|
||||
RFC 9180. In quicnprotochat, HPKE uses DHKEM(X25519, HKDF-SHA256).
|
||||
See [Hybrid KEM](../protocol-layers/hybrid-kem.md).
|
||||
|
||||
**KEM** -- Key Encapsulation Mechanism. A cryptographic primitive that generates
|
||||
a shared secret and an encapsulated (encrypted) version of that secret. Used in
|
||||
HPKE and in the hybrid post-quantum construction (X25519 + ML-KEM-768).
|
||||
|
||||
**KeyPackage** -- An MLS structure containing a member's public key material
|
||||
(HPKE init key, signing key, credential) that peers use to add the member to a
|
||||
group. KeyPackages are single-use per the MLS specification (RFC 9420) -- each
|
||||
is consumed on fetch. See
|
||||
[ADR-005: Single-Use KeyPackages](../design-rationale/adr-005-single-use-keypackages.md).
|
||||
|
||||
**ML-KEM-768** -- Module-Lattice-based Key Encapsulation Mechanism, security
|
||||
level 3 (NIST FIPS 203). A post-quantum KEM based on the hardness of the
|
||||
module learning-with-errors (MLWE) problem. 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).
|
||||
|
||||
**MLS** -- Messaging Layer Security. A protocol for group key agreement defined
|
||||
in RFC 9420. MLS provides forward secrecy and post-compromise security for
|
||||
groups of any size through an efficient tree-based key schedule.
|
||||
See [MLS (RFC 9420)](../protocol-layers/mls.md).
|
||||
|
||||
**Noise\_XX** -- A Noise Protocol Framework handshake pattern providing mutual
|
||||
authentication. Both parties transmit their static public keys during the
|
||||
handshake (encrypted after the first round-trip). The M1 transport stack uses
|
||||
Noise\_XX over TCP; the M3+ stack uses QUIC + TLS 1.3 as the primary transport.
|
||||
See [Noise\_XX Handshake](../protocol-layers/noise-xx.md).
|
||||
|
||||
**PCS** -- Post-Compromise Security. The property that a protocol recovers
|
||||
security after a member's state is compromised. In MLS, once a compromised
|
||||
member sends an Update or Commit, subsequent epochs are secure again (assuming
|
||||
the attacker does not maintain persistent access).
|
||||
See [Post-Compromise Security](../cryptography/post-compromise-security.md).
|
||||
|
||||
**PIR** -- Private Information Retrieval. A cryptographic technique that allows
|
||||
a client to fetch a record from a database without the server learning which
|
||||
record was requested. Explored as a future enhancement for metadata-hiding
|
||||
KeyPackage and message fetch.
|
||||
See [Future Research](../roadmap/future-research.md).
|
||||
|
||||
**QUIC** -- A UDP-based, multiplexed, encrypted transport protocol defined in
|
||||
RFC 9000. QUIC integrates TLS 1.3 for authentication and confidentiality and
|
||||
provides 0-RTT connection establishment, stream multiplexing, and built-in
|
||||
congestion control. quicnprotochat uses the `quinn` crate.
|
||||
See [QUIC + TLS 1.3](../protocol-layers/quic-tls.md).
|
||||
|
||||
**Ratchet Tree** -- The binary tree data structure used in MLS for efficient
|
||||
group key derivation. Each leaf corresponds to a group member; internal nodes
|
||||
hold derived key material. Updates propagate along the path from a leaf to the
|
||||
root, giving O(log N) cost for key updates in a group of N members.
|
||||
|
||||
**TLS 1.3** -- Transport Layer Security version 1.3, defined in RFC 8446. The
|
||||
standard for authenticated, encrypted transport. quicnprotochat uses TLS 1.3
|
||||
exclusively (via `rustls` with `TLS13` cipher suites only) as part of the QUIC
|
||||
transport. See [QUIC + TLS 1.3](../protocol-layers/quic-tls.md).
|
||||
|
||||
**Welcome** -- An MLS message sent to new members when they are added to a
|
||||
group. The Welcome contains the group state (ratchet tree, group context,
|
||||
epoch secrets) encrypted under the new member's HPKE init key from their
|
||||
KeyPackage. See [MLS (RFC 9420)](../protocol-layers/mls.md).
|
||||
|
||||
**X25519** -- Elliptic curve Diffie-Hellman key exchange on Curve25519 (using
|
||||
the Montgomery form). Used for the Noise\_XX handshake (transport
|
||||
authentication) and as the classical component of DHKEM in MLS.
|
||||
quicnprotochat uses the `x25519-dalek` crate.
|
||||
See [X25519 Transport Keys](../cryptography/transport-keys.md).
|
||||
|
||||
**Zeroize** -- The practice of securely clearing sensitive data (private keys,
|
||||
shared secrets) from memory when it is no longer needed. quicnprotochat uses the
|
||||
`zeroize` crate with the `ZeroizeOnDrop` derive macro to ensure that key material
|
||||
is overwritten on drop.
|
||||
See [Key Lifecycle and Zeroization](../cryptography/key-lifecycle.md).
|
||||
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