chore(server): checkpoint deployed services and unfinished forums

User requested a checkpoint and stopped all agents. Deployed artifacts remain the last verified releases; unfinished settings/categories/forums are preserved as WIP. See TODO/roadmap for verification and remaining release/updater work.
This commit is contained in:
Loki 2026-11-01 15:31:20 +01:00
parent d6d406bbf5
commit c18ccadf99
Signed by: boba
GPG key ID: 253067914055423B
96 changed files with 8665 additions and 276 deletions

View file

@ -1,8 +1,10 @@
# TLS 1.3 for the TCP control plane (LNEx v3)
# TLS 1.3 for the TCP control plane (LNEx v4)
> Status: design accepted and implemented together with this document.
> Current version: LNEx v4. TLS was introduced in v3; v4 adds mandatory
> [Central account admission](central-account.md), preserving the TLS security model.
> This document describes the current v4 transport parameters.
> This is a **breaking change**: LNEx v2 (custom X25519 + HKDF + ChaCha20-Poly1305
> layer on TCP) is removed. The protocol version is bumped to `v3`.
> layer on TCP) is removed. The protocol version is bumped to `v4`.
> UDP voice is **not** affected (see [Voice](#voice-udp-is-unchanged)).
## Goals
@ -27,7 +29,7 @@
| # | Decision |
|---|----------|
| D1 | `rustls` 0.23 with the `aws_lc_rs` provider, **TLS 1.3 only** on both sides. ALPN `vnox-lnex/3` is required. |
| D1 | `rustls` 0.23 with the `aws_lc_rs` provider, **TLS 1.3 only** on both sides. ALPN `vnox-lnex/4` is required. |
| D2 | The server certificate is either user supplied (`tls_cert_path` / `tls_key_path`, for example Let's Encrypt) or **auto generated** on first start and stored in `data_dir/tls/self-signed.pem`. |
| D3 | The auto generated certificate uses the **server identity Ed25519 key as its TLS key**. Therefore the certificate fingerprint is a pure function of the identity key, survives certificate regeneration, and no second private key is stored. |
| D4 | The **pin** is `SHA-256(SubjectPublicKeyInfo DER)` of the leaf certificate (the "SPKI fingerprint"). It is the trust anchor for self-signed servers. |
@ -35,7 +37,7 @@
| D6 | A changed fingerprint is a **hard block** with a warning. There is no "connect anyway". The only way forward is an explicit "forget this server" followed by a new trust decision. |
| D7 | The Ed25519 client authentication stays, but its signature covers a **TLS exporter value (channel binding)**, so it cannot be relayed over another TLS connection. The server HELLO is signed with its identity key over the same binding. |
| D8 | The X25519 + HKDF + ChaCha20-Poly1305 layer on TCP, the `ENCRYPTED` packet flag on TCP and the ephemeral key fields in `Hello` and `Auth` are removed. |
| D9 | LNEx version is bumped from `v2` to `v3`. Old clients and old servers fail with an explicit error. Downgrade is impossible by construction. |
| D9 | LNEx version is bumped from `v2` to `v4`. Old clients and old servers fail with an explicit error. Downgrade is impossible by construction. |
## Threat model
@ -45,7 +47,7 @@
| Active MITM terminating TLS with its own certificate | Pin mismatch (known server) or TOFU prompt showing a different fingerprint (new server). Even if the user accepted a wrong fingerprint, the MITM cannot produce the server's Ed25519 signature over this connection's exporter, and the client rejects a server identity that differs from the stored one. |
| MITM relaying the server's HELLO to the client | HELLO signature covers the exporter of the TLS session between the client and the relay, which differs from the relay to server session. Verification fails. |
| Malicious server relaying a client's AUTH to another server | AUTH signature covers the exporter of the connection to the malicious server. Another server computes a different value and rejects it. |
| Downgrade to plaintext, TLS 1.2 or LNEx v2 | The client never opens a plaintext socket, the rustls configs list only TLS 1.3, the server requires ALPN `vnox-lnex/3`, and the version string `v3` is inside the signed transcripts. |
| Downgrade to plaintext, TLS 1.2 or LNEx v2 | The client never opens a plaintext socket, the rustls configs list only TLS 1.3, the server requires ALPN `vnox-lnex/4`, and the version string `v4` is inside the signed transcripts. |
| First connection MITM (TOFU weakness) | Unavoidable without a CA or out of band data. Mitigation: the server prints its fingerprint at startup and writes it to `data_dir/tls/fingerprint.txt`; owners should publish it with the invitation, users compare before confirming. Public CA certificates skip TOFU. |
| Compromised or replaced server key | Fingerprint changes, clients block (D6). |
@ -82,7 +84,7 @@ At startup the gateway logs `TLS SPKI SHA-256 fingerprint: <hex>` and writes it
- Protocol versions: TLS 1.3 only (`rustls::version::TLS13`).
- Cipher suites: the rustls defaults for TLS 1.3 (AES-GCM, ChaCha20-Poly1305).
- ALPN: `vnox-lnex/3`. A connection without the negotiated ALPN is dropped before any
- ALPN: `vnox-lnex/4`. A connection without the negotiated ALPN is dropped before any
LNEx byte is read.
- No client certificates.
- Handshake timeouts: 15 seconds for the TLS handshake and 15 seconds for the LNEx HELLO/AUTH/SESSION exchange.
@ -99,7 +101,7 @@ The server peeks at the first byte of a new connection (up to 2 seconds).
A TLS client sends a handshake record (`0x16`) immediately. Anything else (a v2 client
waits for the server HELLO and sends nothing, a plaintext client sends LNEx bytes)
receives one plaintext LNEx `Error` frame, `ErrorCode::VersionMismatch`, with the message
`TLS 1.3 required (LNEx v3): update your client`, and the connection is closed. This
`TLS 1.3 required (LNEx v4): update your client`, and the connection is closed. This
frame is the only plaintext the gateway ever writes and it contains no secrets.
## Client
@ -150,7 +152,7 @@ TLS 1.3 handshake with a custom ServerCertVerifier:
UI on UntrustedServer: show host, fingerprint (grouped hex), "Trust" / "Cancel".
Trust -> trust_store[host:port] = { pin, fingerprint }, reconnect.
LNEx v3 handshake inside the tunnel (see below)
LNEx v4 handshake inside the tunnel (see below)
after a valid server HELLO:
rec.identity set and != server_pubkey -> ERROR IdentityChanged (hard block)
otherwise store identity (TOFU of the identity inside an already trusted channel)
@ -175,7 +177,7 @@ When a pinned server presents another SPKI the client:
server migration (for example moving from a self-signed certificate to Let's Encrypt
or restoring a server without its `server_identity.json`).
## LNEx v3 handshake inside TLS
## LNEx v4 handshake inside TLS
The 12 byte packet header and protobuf payloads are unchanged. Frames are written
directly into the TLS stream. The `flags` field must be `0` on the TCP control plane
@ -184,10 +186,10 @@ directly into the TLS stream. The `flags` field must be `0` on the TCP control p
```
Client Gateway
| -- TCP + TLS 1.3 handshake (ALPN) ---> |
| both sides: binding = Export("EXPORTER-VNOX-LNEx-v3-channel-binding", no context, 32)
| <------ HELLO (seq 0) ---------------- | lnex_version="v3", server_pubkey, challenge_nonce,
| both sides: binding = Export("EXPORTER-VNOX-LNEx-v4-channel-binding", no context, 32)
| <------ HELLO (seq 0) ---------------- | lnex_version="v4", server_pubkey, challenge_nonce,
| | node_name, private_mode, server_signature
| ------- AUTH (seq 0) ----------------> | client_pubkey, nickname, lnex_version="v3", signature
| ------- AUTH (seq 0) ----------------> | client_pubkey, nickname, lnex_version="v4", signature, account_proof
| <------ SESSION (seq 1) -------------- | session_id, token, expires_at
```
@ -195,10 +197,10 @@ Signatures (Ed25519, strict verification):
```
server_signature = Sign(server_key,
"VNOX-LNEx-v3-server-hello\0" || binding || protobuf(Hello with server_signature empty))
"VNOX-LNEx-v4-server-hello\0" || binding || protobuf(Hello with server_signature empty))
client signature = Sign(client_key,
"VNOX-LNEx-v3-client-auth\0" || binding
"VNOX-LNEx-v4-client-auth\0" || binding
|| u32be(len(signed_hello)) || signed_hello
|| protobuf(Auth with signature empty))
```
@ -238,18 +240,18 @@ needs the client to trust the gateway certificate (`--trust-first-use` or `--fin
| Client | Server | Result |
|--------|--------|--------|
| v3 | v3 | works |
| v2 (old) | v3 | server sends a plaintext `Error(VersionMismatch)` "TLS 1.3 required (LNEx v3): update your client"; an old client shows a handshake error or times out. Nothing is negotiated. |
| v3 | v2 (old) | the server answers the TLS ClientHello with LNEx bytes. The client maps the rustls decode failure to "The server does not speak TLS 1.3 (LNEx v3). It is probably an outdated server, ask the owner to update." No retry in plaintext. |
| v3, TLS 1.2 only peer | v3 | handshake failure, protocol version alert, same explicit message. |
| v3 | v3 with `lnex_version` other than `v3` in HELLO/AUTH | `VersionMismatch`, connection closed. |
| v4 | v4 | works |
| v2 (old) | v4 | server sends a plaintext `Error(VersionMismatch)` "TLS 1.3 required (LNEx v4): update your client"; an old client shows a handshake error or times out. Nothing is negotiated. |
| v4 | v2 (old) | the server answers the TLS ClientHello with LNEx bytes. The client maps the rustls decode failure to "The server does not speak TLS 1.3 (LNEx v4). It is probably an outdated server, ask the owner to update." No retry in plaintext. |
| v4, TLS 1.2 only peer | v4 | handshake failure, protocol version alert, same explicit message. |
| v4 | v4 with `lnex_version` other than `v4` in HELLO/AUTH | `VersionMismatch`, connection closed. |
There is no version negotiation and no compatibility window: the old handshake is not
implemented in the new binaries.
## Operations: enabling it on a server
1. Update the gateway (and `serverd`) to the LNEx v3 build. Remove `tls_enabled = false`
1. Update the gateway (and `serverd`) to the LNEx v4 build. Remove `tls_enabled = false`
if present.
2. Self-signed: nothing to configure. Start the gateway, read the fingerprint from the
log or `data_dir/tls/fingerprint.txt`, publish it to your users.