docs: rewrite mdBook documentation for v2 architecture
Update 25+ files and add 6 new pages to reflect the v2 migration from Cap'n Proto to Protobuf framing over QUIC. Integrates SDK and Operations docs into the mdBook, restructures SUMMARY.md, and rewrites the wire format, architecture, and protocol sections with accurate v2 content.
This commit is contained in:
@@ -182,29 +182,22 @@ could provide an additional detection mechanism.
|
||||
|
||||
### No Client Authentication on the Delivery Service
|
||||
|
||||
The Delivery Service does not currently authenticate clients. Anyone who knows
|
||||
a recipient's Ed25519 public key can enqueue messages for that recipient. This
|
||||
enables spam and potential denial-of-service by flooding a recipient's queue.
|
||||
The Delivery Service requires a valid OPAQUE session token for all DS
|
||||
operations. The session token is bound to the client's identity key, and the
|
||||
server rejects enqueue and fetch operations that lack a valid token.
|
||||
|
||||
**Impact:** Queue flooding, spam delivery. MLS provides its own authentication
|
||||
(the recipient will reject messages not signed by a group member), so forged
|
||||
content will not be accepted, but the recipient must still download and attempt
|
||||
to process the spam.
|
||||
**Status:** Mitigated. Token-based authentication is enforced via the OPAQUE
|
||||
login flow (methods 100-103). Unauthenticated enqueue attempts are rejected.
|
||||
|
||||
**Mitigation path:** The AUTHZ\_PLAN introduces token-based authentication,
|
||||
binding identityKey to accounts and requiring valid access tokens for all
|
||||
DS operations.
|
||||
### Rate Limiting
|
||||
|
||||
### No Rate Limiting
|
||||
The server enforces a sliding window rate limit on all RPC methods. Requests
|
||||
exceeding the configured threshold per IP or per account are rejected with a
|
||||
rate-limit error response.
|
||||
|
||||
The server does not currently enforce per-client or per-IP rate limits. A
|
||||
malicious client could flood the server with requests, consuming resources and
|
||||
degrading service for other users.
|
||||
|
||||
**Impact:** Denial of service.
|
||||
|
||||
**Mitigation path:** The AUTHZ\_PLAN specifies per-IP and per-account/device
|
||||
rate limits (e.g., 50 requests/second, 5 MB payload cap).
|
||||
**Status:** Mitigated. Rate limiting is active (sliding window, configurable
|
||||
threshold, default 50 requests/second per IP). The `rate_limit_hit_total`
|
||||
Prometheus metric tracks rejections. See [Monitoring](../operations/monitoring.md).
|
||||
|
||||
### BasicCredential Only
|
||||
|
||||
@@ -234,18 +227,30 @@ hybrid KEM is active for MLS).
|
||||
**Mitigation path:** Adopt post-quantum TLS (ML-KEM in TLS 1.3 handshake) when
|
||||
`rustls` supports it.
|
||||
|
||||
## Future Mitigations
|
||||
## Implemented Mitigations
|
||||
|
||||
### Sealed Sender
|
||||
|
||||
**Goal:** Hide the sender's identity from the server.
|
||||
**Status:** Implemented. The `--sealed-sender` flag encrypts the sender's
|
||||
identity inside the MLS ciphertext. When enabled, the server routes by recipient
|
||||
queue index only and cannot determine who sent the message. This reduces server
|
||||
metadata visibility from "who sent to whom" to "someone sent to this recipient."
|
||||
|
||||
**Approach:** Encrypt the sender's identity inside the MLS ciphertext. The
|
||||
server cannot determine who sent a message -- it only knows the recipient
|
||||
(delivery queue index). Signal implements a version of this as "Sealed Sender."
|
||||
### OPAQUE Authentication
|
||||
|
||||
**Benefit:** Reduces the server's metadata visibility from "who sent to whom"
|
||||
to "someone sent to this recipient."
|
||||
**Status:** Implemented. The OPAQUE protocol (RFC 9497) is the only supported
|
||||
login mechanism. The server stores OPAQUE registration records; it never receives
|
||||
or stores the client's password. Session tokens issued on login are required for
|
||||
all authenticated RPCs.
|
||||
|
||||
### Username Enumeration Protection
|
||||
|
||||
**Status:** Implemented. All auth responses (including failures) are subject to
|
||||
a 5ms timing floor, preventing timing-based username enumeration.
|
||||
|
||||
---
|
||||
|
||||
## Future Mitigations
|
||||
|
||||
### Private Information Retrieval (PIR)
|
||||
|
||||
@@ -272,17 +277,6 @@ verify that their public key has not been replaced by an attacker.
|
||||
**Benefit:** Detects attacks where the server (or an attacker who compromised
|
||||
the server) substitutes a victim's public key with the attacker's key.
|
||||
|
||||
### OPAQUE Authentication
|
||||
|
||||
**Goal:** Zero-knowledge password authentication.
|
||||
|
||||
**Approach:** Use the OPAQUE protocol (RFC 9497) for client-server
|
||||
authentication. OPAQUE allows the client to prove knowledge of a password
|
||||
without revealing it to the server, even during registration.
|
||||
|
||||
**Benefit:** The server never learns the client's password, preventing
|
||||
credential theft in a server compromise.
|
||||
|
||||
### Tor/I2P Integration
|
||||
|
||||
**Goal:** Hide client IP addresses from the server and network adversaries.
|
||||
@@ -315,11 +309,12 @@ communication patterns from traffic analysis.
|
||||
|--------|-------------------|-----|-------------|
|
||||
| Passive eavesdropper | TLS 1.3 + MLS (2 layers) | Traffic analysis | Padding, Tor |
|
||||
| Active MITM | TLS 1.3 (QUIC) | Self-signed certs | Cert pinning, CA |
|
||||
| Compromised server | MLS E2E encryption | Metadata visible | Sealed Sender, PIR |
|
||||
| Compromised server | MLS E2E encryption + Sealed Sender | Metadata partially visible | PIR |
|
||||
| Compromised client | FS + PCS | Current epoch exposed | Periodic Updates |
|
||||
| Spam/flooding | None | No auth on DS | AUTHZ\_PLAN |
|
||||
| Spam/flooding | Rate limiting + OPAQUE session tokens | -- | -- |
|
||||
| Username enumeration | 5ms timing floor on all auth responses | -- | -- |
|
||||
| Key substitution | None | BasicCredential only | Key Transparency |
|
||||
| Quantum adversary (content) | Hybrid KEM (M5+) | Pre-M5 messages | Deploy hybrid ASAP |
|
||||
| Quantum adversary (content) | Hybrid KEM (X25519 + ML-KEM-768) | Pre-v2 messages | -- |
|
||||
| Quantum adversary (transport) | None | Classical TLS (ECDHE) | PQ TLS |
|
||||
|
||||
## Related Pages
|
||||
|
||||
Reference in New Issue
Block a user