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:
102
docs/src/cryptography/overview.md
Normal file
102
docs/src/cryptography/overview.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Cryptography Overview
|
||||
|
||||
quicnprotochat layers multiple cryptographic protocols to provide confidentiality,
|
||||
integrity, authentication, forward secrecy, and post-compromise security. This
|
||||
page catalogues every algorithm in the system, the crate that supplies it, and
|
||||
the security margin it provides.
|
||||
|
||||
## Algorithm Inventory
|
||||
|
||||
| Algorithm | Purpose | Crate | Security Level |
|
||||
|-----------|---------|-------|----------------|
|
||||
| Ed25519 | Identity signing, MLS credentials | `ed25519-dalek 2` | 128-bit classical |
|
||||
| X25519 | Noise DH, MLS HPKE key exchange | `x25519-dalek 2` | 128-bit classical |
|
||||
| ChaCha20-Poly1305 | Noise AEAD | `chacha20poly1305 0.10` | 256-bit key |
|
||||
| AES-128-GCM | MLS AEAD | `openmls` (via RustCrypto) | 128-bit |
|
||||
| BLAKE2s | Noise hash function | `snow 0.9` (built-in) | 128-bit |
|
||||
| SHA-256 | Key fingerprints, HKDF | `sha2 0.10` | 128-bit collision resistance |
|
||||
| ML-KEM-768 | Post-quantum KEM | `ml-kem 0.2` | NIST Level 3 (~192-bit PQ) |
|
||||
| HKDF-SHA256 | Key derivation | `hkdf 0.12` | Depends on input entropy |
|
||||
|
||||
> **Note:** The system provides 128-bit classical security throughout. When the
|
||||
> hybrid KEM is active (M5 onward), content encryption gains 192-bit
|
||||
> post-quantum security via ML-KEM-768.
|
||||
|
||||
## Where Each Algorithm Appears
|
||||
|
||||
### Transport Layer
|
||||
|
||||
The transport layer uses two independent encryption substrates:
|
||||
|
||||
1. **QUIC/TLS 1.3** (via `quinn 0.11` + `rustls 0.23`): Provides the
|
||||
outermost encrypted tunnel. The TLS 1.3 handshake negotiates an ephemeral
|
||||
ECDHE key exchange (X25519 or P-256, depending on the peer) and an AEAD
|
||||
cipher (AES-128-GCM or ChaCha20-Poly1305). This layer protects connection
|
||||
metadata from passive network observers.
|
||||
|
||||
2. **Noise\_XX** (via `snow 0.9`): Runs inside the QUIC stream. The Noise
|
||||
pattern `Noise_XX_25519_ChaChaPoly_BLAKE2s` provides mutual authentication
|
||||
using static X25519 keys, with ChaCha20-Poly1305 as the AEAD and BLAKE2s
|
||||
as the hash function. See [X25519 Transport Keys](transport-keys.md) for
|
||||
details on the keypair.
|
||||
|
||||
### Application Layer
|
||||
|
||||
1. **MLS (RFC 9420)** (via `openmls 0.5`): Provides end-to-end encrypted
|
||||
group messaging. The ciphersuite is
|
||||
`MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519`, which uses:
|
||||
- X25519 for DHKEM (HPKE key exchange)
|
||||
- AES-128-GCM for content encryption
|
||||
- SHA-256 for the KDF and transcript hashing
|
||||
- Ed25519 for signing Commits, Proposals, and credentials
|
||||
|
||||
2. **Hybrid KEM** (via `ml-kem 0.2` + `x25519-dalek 2` + `hkdf 0.12`):
|
||||
An outer encryption layer combining X25519 and ML-KEM-768. The combined
|
||||
shared secret is derived through HKDF-SHA256 and used with
|
||||
ChaCha20-Poly1305 for AEAD. See
|
||||
[Post-Quantum Readiness](post-quantum-readiness.md) for integration plans.
|
||||
|
||||
### Identity Layer
|
||||
|
||||
- **Ed25519** provides long-term identity signing. Each client generates a
|
||||
single Ed25519 keypair that serves as the MLS `BasicCredential`, the
|
||||
Authentication Service registration key, and the delivery queue index. See
|
||||
[Ed25519 Identity Keys](identity-keys.md).
|
||||
|
||||
- **SHA-256** computes key fingerprints -- a 32-byte digest of the Ed25519
|
||||
public key bytes used for compact, collision-resistant identification in logs
|
||||
and protocol messages.
|
||||
|
||||
## Security Level Summary
|
||||
|
||||
All classical algorithms in the system target at least 128-bit security. The
|
||||
post-quantum component (ML-KEM-768) targets NIST Level 3, which corresponds to
|
||||
roughly 192-bit security against quantum adversaries.
|
||||
|
||||
The weakest classical link is the 128-bit security level of AES-128-GCM in the
|
||||
MLS ciphersuite. This is consistent with the IETF's recommended MLS ciphersuite
|
||||
and is considered adequate for the foreseeable future.
|
||||
|
||||
```text
|
||||
Layer Classical Security Post-Quantum Security
|
||||
--------------------------------------------------------------------
|
||||
QUIC/TLS 1.3 128-bit (ECDHE) None (classical only)
|
||||
Noise_XX 128-bit (X25519) None (classical only)
|
||||
MLS (content) 128-bit (AES-128-GCM) None (classical only)
|
||||
Hybrid KEM (M5+) 128-bit (X25519) ~192-bit (ML-KEM-768)
|
||||
```
|
||||
|
||||
See the [Threat Model](threat-model.md) for a discussion of what is and is not
|
||||
protected, and [Forward Secrecy](forward-secrecy.md) and
|
||||
[Post-Compromise Security](post-compromise-security.md) for the advanced
|
||||
security properties these algorithms enable.
|
||||
|
||||
## Related Pages
|
||||
|
||||
- [Ed25519 Identity Keys](identity-keys.md) -- long-term signing keypair
|
||||
- [X25519 Transport Keys](transport-keys.md) -- Noise handshake keypair
|
||||
- [Key Lifecycle and Zeroization](key-lifecycle.md) -- creation through destruction
|
||||
- [Forward Secrecy](forward-secrecy.md) -- past message protection
|
||||
- [Post-Compromise Security](post-compromise-security.md) -- future message recovery
|
||||
- [Post-Quantum Readiness](post-quantum-readiness.md) -- ML-KEM-768 hybrid KEM
|
||||
- [Threat Model](threat-model.md) -- attacker models and known gaps
|
||||
Reference in New Issue
Block a user