From 82227203f95bc1475791440d9444476bbd38a2bf Mon Sep 17 00:00:00 2001 From: loki5512344 Date: Sat, 24 Oct 2026 22:05:19 +0200 Subject: [PATCH] docs: describe TLS 1.3 control connection and LNEx v3 in client docs --- CHANGELOG.md | 7 +++ README.md | 4 +- docs/05-features/encryption.md | 98 +++++++++++----------------------- 3 files changed, 41 insertions(+), 68 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ef57f30..4bfc1b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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) diff --git a/README.md b/README.md index 5e8050e..72787cb 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/docs/05-features/encryption.md b/docs/05-features/encryption.md index f9175b3..27ad053 100644 --- a/docs/05-features/encryption.md +++ b/docs/05-features/encryption.md @@ -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`.