diff --git a/DESIGN.md b/DESIGN.md index 05c7952..a87ea11 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -171,6 +171,44 @@ Server pubkey in DNS TXT record prevents impersonation. But DNS itself could be - TOFU for server keys (pin on first contact) - Certificate transparency-style log for server key changes +### Key Transparency via DNS + +Use DNS as a decentralized public key registry — prevents the server from performing MITM attacks on key exchange. + +Each user publishes their public key as a DNS TXT record, signed by their own identity key: + +``` +_wz._id..example.com TXT "v=wz1; fp=a3f8c912...; pubkey=base64...; sig=base64..." +``` + +- `fp` — full fingerprint +- `pubkey` — user's Ed25519 public identity key +- `sig` — self-signature over (fp + pubkey), proving the DNS record was authored by the key holder + +**Verification flow:** +``` +Bob wants Alice's key: +1. Ask server → server says Alice's key is X +2. DNS lookup → _wz._id..example.com → key is X, self-signed +3. Match? → trusted +4. Mismatch? → HARD WARNING: server may be performing MITM +5. No DNS record? → fall back to TOFU (trust on first use) +``` + +**Why DNS works here:** +- Decentralized: no single party controls all DNS (especially across domains) +- The self-signature in the TXT record means even the DNS admin can't forge it without Alice's private key +- DNSSEC adds transport integrity (record wasn't tampered in transit) +- Records are globally cached and replicated — hard to silently change + +**Privacy concern:** public DNS means anyone can enumerate users by scanning TXT records. Mitigation: subdomain is `SHA-256(fingerprint)[:16]` — you must already know the fingerprint to look up the record. This makes enumeration impractical. + +**Scalability:** one TXT record per user. Fine for thousands of users per domain. Large orgs can shard across subdomains. + +**When users don't control DNS:** in an org deployment, the admin controls the DNS zone. The admin could collude with the server to MITM. But the self-signature still protects — the admin would need the user's private key to forge a valid record. The only attack is *deleting* the record (forcing TOFU fallback), not *replacing* it. + +**Integration with federation:** the same DNS zone handles both server discovery (`_warzone._tcp`) and user key transparency (`_wz._id`). One DNS zone, two purposes. + --- ## 4. Warzone Delivery — Mule Protocol @@ -380,8 +418,10 @@ warzone.wasm # browser client (via wasm-pack) - [ ] TUI client (ratatui) - [ ] Web client (WASM) -### Phase 3 — Federation -- [ ] DNS TXT record format specification +### Phase 3 — Federation & Key Transparency +- [ ] DNS TXT record format specification (server discovery + user key transparency) +- [ ] User self-signed key publication to DNS (`_wz._id..domain`) +- [ ] Key verification: server response vs DNS record cross-check - [ ] Server-to-server mutual TLS authentication - [ ] Federated message delivery - [ ] Server key pinning (TOFU) @@ -433,19 +473,17 @@ warzone.wasm # browser client (via wasm-pack) | Deniability | **Deniability by default** (Signal model) | Safety-first for users in hostile environments. Non-repudiation can be added as opt-in per-conversation later. | | Server-at-rest encryption | **Optional, not in core** | Nice to have. Implement as a flag: `--encrypt-db` with passphrase on boot. E2E already protects message content. | | Incentives / tokenization | **Not in scope** | This is an organizational/military tool. Participants cooperate by mandate, not incentive. | -| Transport fallbacks | **Bluetooth + LoRa** | Mules use Bluetooth for device-to-device. LoRa for extreme last-resort (low bandwidth but km range). | +| Transport fallbacks | **Bluetooth + LoRa** | Mules use Bluetooth for device-to-device. LoRa for extreme last-resort (low bandwidth but km range). LoRa is not Phase 1. | +| Key transparency | **DNS TXT records** | Each user self-signs their pubkey in a DNS TXT record. Server can't MITM because it can't forge the self-signature. Integrated with federation DNS in Phase 3. | +| Multi-device ratchet | **Per-device sessions** | Each device maintains its own Double Ratchet session with each contact (Signal's approach). Cross-device history sync via encrypted device-to-device channel using shared seed. | ## Open Questions -1. **Key transparency**: Should we implement a transparency log for identity keys (like CONIKS)? Prevents server MITM on key exchange. Adds complexity but significantly hardens the trust model. Could be Phase 7+. +1. **LoRa investment**: LoRa has ~250 byte payload limit. Emergency-only (receipts + short text) or a real feature? Not Phase 1 either way — but the compact binary format should be designed early so the message layer doesn't assume JSON everywhere. -2. **LoRa message format**: LoRa has ~250 byte payload limit. Need a compact binary format for LoRa transport — possibly just delivery receipts and tiny text messages, not full media. How much do we invest here vs treating it as emergency-only? +2. **Legal**: E2E encryption with mule delivery designed for warzone use has significant legal implications in many jurisdictions. Needs legal review before deployment. -3. **Legal**: E2E encryption with mule delivery designed for warzone use has significant legal implications in many jurisdictions. Needs legal review before deployment. - -4. **Sealed sender vs onion routing**: Sealed sender (Signal's approach — server knows recipient but not sender) is lighter than full onion routing. Implement sealed sender first as the default metadata protection, onion routing as Phase 6 upgrade? - -5. **Multi-device conflict resolution**: When two devices are offline and both send messages, how do we resolve Double Ratchet state conflicts on sync? Signal handles this per-device (each device has its own session). Do we want shared-session across devices (harder, requires device-to-device sync)? +3. **Sealed sender vs onion routing**: Sealed sender (Signal's approach — server knows recipient but not sender) is lighter than full onion routing. Plan: sealed sender first as the default metadata protection, full onion routing as Phase 6 upgrade for when connectivity allows it. ---