docs: describe TLS 1.3 control connection and LNEx v3 in client docs
Claude-Session: https://claude.ai/code/session_01GDjxLvBcnJqniFQGUGb1V4
This commit is contained in:
parent
9a20ace6e6
commit
79e5755d2d
3 changed files with 41 additions and 68 deletions
|
|
@ -5,6 +5,13 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
### Changed (breaking): LNEx v3, TLS 1.3 control connection
|
||||
- The control connection is TLS 1.3 only (rustls, ALPN `vnox-lnex/3`). The custom X25519/HKDF/ChaCha20 TCP layer, the plaintext loopback shortcut and the `lnex://` plaintext meaning are removed. Protocol version `v3`; old gateways are refused with an explicit error, no fallback.
|
||||
- Server trust: SPKI SHA-256 pin stored in `~/.config/vnox/known_servers.json` (trust on first use with a confirmation dialog, RU/EN), public CA certificates accepted without a prompt, a changed fingerprint or server identity is blocked and offers "Forget this server".
|
||||
- Client auth signatures are bound to the TLS exporter and cannot be replayed on another connection.
|
||||
- `vnox-e2e-voice` now needs `--fingerprint HEX` or `--trust-first-use`.
|
||||
- Design and trust model: VNOX-Server `docs/02-protocol/tls.md`.
|
||||
|
||||
### Added — Phase 2 guild member list + identity export/import + channel rate limit (fourth batch)
|
||||
|
||||
#### Phase 2 guild member list with kick / role-assign UI (Phase E4)
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ The official desktop client for [VNOX](https://github.com/loki5512344/Vnox) —
|
|||
|
||||
### Implemented
|
||||
- **Auth:** Ed25519 keypair generation, challenge-response login, reconnect with exponential backoff
|
||||
- **Encryption:** ChaCha20-Poly1305 AEAD + X25519 ECDH key exchange
|
||||
- **Encryption:** TLS 1.3 (rustls) on the control connection with certificate pinning (trust on first use), ChaCha20-Poly1305 on UDP voice
|
||||
- **Text chat:** Persistent history, reactions, replies, edit, delete, typing indicators, read receipts
|
||||
- **Channel management:** Join, leave, create, delete; text and voice channels
|
||||
- **Guilds:** Create, list, leave, member list with roles, kick, audit log viewer
|
||||
|
|
@ -58,7 +58,7 @@ Phase 1 is implemented. Not production ready.
|
|||
| Direct Messages | ✅ Working |
|
||||
| Friends & presence | ✅ Working |
|
||||
| Voice (send/receive) | 🔧 Partial (audio pipeline) |
|
||||
| Encryption | ✅ ChaCha20-Poly1305 + X25519 |
|
||||
| Encryption | ✅ TLS 1.3 (TCP) + ChaCha20-Poly1305 (voice) |
|
||||
| In-game overlay | 🔲 Phase 2 |
|
||||
| Mobile client | 🔲 Phase 3 |
|
||||
|
||||
|
|
|
|||
|
|
@ -1,78 +1,44 @@
|
|||
# Encryption — Phase 1.1
|
||||
# Encryption
|
||||
|
||||
> **Phase 1.1 status:** Fully implemented. ChaCha20-Poly1305 AEAD with X25519 ECDH + HKDF-SHA256 key exchange. Both TCP (control) and UDP (voice) paths are now encrypted. Forward secrecy via ephemeral session keys.
|
||||
> **Status (LNEx v3):** the TCP control plane is protected by **TLS 1.3** (rustls).
|
||||
> The UDP voice path is protected by per route ChaCha20-Poly1305 keys delivered over the
|
||||
> TLS control connection. The earlier custom X25519 + HKDF + ChaCha20-Poly1305 layer on
|
||||
> TCP (LNEx v2) was removed. Design and trust model: [02-protocol/tls.md](../02-protocol/tls.md).
|
||||
|
||||
## Goal
|
||||
## Layers
|
||||
|
||||
Replace all plaintext traffic (TCP + UDP) with ChaCha20-Poly1305 AEAD encryption.
|
||||
X25519 ECDH ephemeral key exchange during handshake for forward secrecy.
|
||||
| Path | Protection | Keys |
|
||||
|------|------------|------|
|
||||
| TCP control (chat, channels, auth) | TLS 1.3, ALPN `vnox-lnex/3`, no fallback | TLS handshake, server cert pinned by SPKI SHA-256 (TOFU) or a public CA |
|
||||
| Server authenticity | Ed25519 server identity signs HELLO over the TLS exporter (channel binding) | `server_identity.json` |
|
||||
| Client authenticity | Ed25519 client key signs AUTH over the same exporter | client identity |
|
||||
| UDP voice | ChaCha20-Poly1305 AEAD per route | random `c2s_key` / `s2c_key` sent in `VoiceSession` over TLS |
|
||||
| Direct messages E2EE (optional) | X25519 + HKDF + ChaCha20-Poly1305 between clients | per conversation keys, unchanged |
|
||||
|
||||
✅ **COMPLETED in Phase 1.1**
|
||||
## What changed from v2
|
||||
|
||||
## Key exchange (during HELLO handshake)
|
||||
- Removed: ephemeral X25519 exchange in HELLO/AUTH, HKDF session key derivation for TCP,
|
||||
per frame ChaCha20-Poly1305 with the `ENCRYPTED` flag, `SessionCrypto` in gateway and client.
|
||||
- Added: mandatory TLS 1.3 listener and connector, certificate management, client trust store,
|
||||
channel bound Ed25519 signatures.
|
||||
- Unchanged: UDP voice packet format, voice node, E2EE for direct messages, Ed25519 identities.
|
||||
|
||||
1. Server generates ephemeral X25519 keypair per session
|
||||
2. Server sends public key in `HELLO` packet
|
||||
3. Client generates own ephemeral X25519 keypair
|
||||
4. Both compute shared secret via X25519 ECDH
|
||||
5. Shared secret → HKDF-SHA256 → two keys:
|
||||
- `client→server` encryption key
|
||||
- `server→client` encryption key
|
||||
6. Ephemeral keys discarded after session (forward secrecy)
|
||||
## Why TLS instead of a custom layer
|
||||
|
||||
## Packet encryption
|
||||
- Reviewed, widely deployed handshake and record layer instead of a protocol we maintain.
|
||||
- Standard tooling and key lifecycle (Let's Encrypt works out of the box).
|
||||
- Forward secrecy, key updates and replay protection are provided by TLS 1.3.
|
||||
|
||||
- Algorithm: **ChaCha20-Poly1305** (AEAD)
|
||||
- 96-bit nonce: `session_id || packet_sequence`
|
||||
- 16-byte Poly1305 authentication tag per packet
|
||||
- Applied to ALL packets on both TCP and UDP
|
||||
## Voice keys
|
||||
|
||||
## Why ChaCha20-Poly1305 over AES-GCM
|
||||
|
||||
- Constant-time on all platforms (no hardware AES requirement)
|
||||
- Faster in software on ARM (common for mobile — Phase 3)
|
||||
- Simpler nonce management (no IV collision risk)
|
||||
|
||||
## Implementation plan
|
||||
|
||||
### ✅ Client (DONE)
|
||||
- `client/src/net/crypto.rs` — SessionCrypto with ChaCha20-Poly1305
|
||||
- `client/src/net/voice.rs` — `build_packet()` encrypts voice payloads with c2s_key
|
||||
- `client/src/net/voice.rs` — `spawn_recv()` decrypts incoming voice with s2c_key
|
||||
- `client/src/net/session/session_loop.rs` — voice_seq counter for encryption nonces
|
||||
|
||||
### ✅ Gateway (DONE)
|
||||
- `gateway/src/proto/crypto.rs` — X25519 ECDH, HKDF-SHA256, ChaCha20-Poly1305
|
||||
- `gateway/src/net/handshake.rs` — ephemeral key exchange in HELLO/AUTH
|
||||
- `gateway/src/net/io.rs` — TCP framing with encryption
|
||||
|
||||
### ✅ Voice
|
||||
- `client/src/net/voice.rs` — encrypted voice packets on UDP (plaintext at rest in voice-node, encrypted on wire)
|
||||
- Voice-node treats packets as opaque bytes (transparent relay)
|
||||
- End-to-end encryption: client A → encrypted → voice-node → encrypted → client B
|
||||
|
||||
## Nonce management
|
||||
|
||||
Each session has a monotonic sequence counter:
|
||||
- Start at 0 on session establishment
|
||||
- Increment per packet (both directions independently)
|
||||
- Nonce = `session_id (8 bytes) || sequence (4 bytes)`
|
||||
- 12-byte nonce fits ChaCha20-Poly1305 standard
|
||||
|
||||
## Key dependencies
|
||||
|
||||
Already in `Cargo.toml` (workspace):
|
||||
- `chacha20poly1305 = "0.10"`
|
||||
- `x25519-dalek = { version = "2", features = ["static_secrets"] }`
|
||||
|
||||
Need to add:
|
||||
- `hkdf = "0.12"` for key derivation
|
||||
- `sha2 = "0.10"` (HKDF dependency, likely already transitive)
|
||||
`VoiceSession` is delivered after the channel authorization check. Keys are random per
|
||||
route and never derived from the TCP session, so the UDP implementation did not need to
|
||||
change when the TCP layer was replaced.
|
||||
|
||||
## Testing
|
||||
|
||||
- ✅ Unit test: encrypt → decrypt round-trip with known keys (`client/src/net/crypto.rs`)
|
||||
- ✅ Unit test: tampered ciphertext fails authentication
|
||||
- ✅ Unit test: build_packet creates valid encrypted packets
|
||||
- Manual test: Run client + gateway + voice-node, join voice channel, verify packets encrypted
|
||||
- Wireshark: Capture UDP traffic, confirm it's not readable plaintext
|
||||
- Unit: SPKI fingerprint extraction, pin match and mismatch, unknown server, TLS 1.2 client
|
||||
rejected, plaintext/v2 client gets an explicit error, channel binding signature replay rejected.
|
||||
- Integration: `VNOX_GATEWAY_BIN=... cargo test --test gateway_interop -- --ignored`
|
||||
in `VNOX-Client`, including the first trust flow.
|
||||
- Voice: `cargo run --bin vnox-e2e-voice -- 127.0.0.1:7600 --trust-first-use` against `vnox-serverd`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue