Talon/voice-cat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Talon
2026-06-17 00:52:02 +02:00
parent 63b241cc2e
commit 2f643e4293
6 changed files with 160 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/security.md
View File

@@ -29,14 +29,26 @@ media channel. Plus server identity, authentication, accounts at rest, and anti-
Self-hosting means most servers won't have a CA-signed cert for a hostname. We support
both, advertised in `ServerHello`:
1. **TOFU (Trust On First Use)** — default for hobby servers. The server has a long-lived
**Ed25519 identity key**; its fingerprint is shown to the user on first connect (like
SSH host keys / TeamSpeak server keys) and pinned locally. Subsequent connects verify
the pin; a changed key warns loudly. The TLS cert is self-signed and bound to this
identity key.
1. **TOFU (Trust On First Use)** — default for hobby servers. On first connect the client
shows an identity dialog and, if accepted, pins the value locally. Subsequent connects
verify the pin silently; a changed value warns loudly (`MISMATCH`).
2. **PKI** — a server with a domain can use a normal CA-signed cert (e.g. Let's Encrypt);
clients validate the chain conventionally. TOFU pinning still applies on top.
**What is actually pinned (M4 implementation):** the **TLS leaf certificate's SHA-256
fingerprint** — verifiable directly from the TLS handshake before any application data is
trusted. The server also declares an Ed25519 identity fingerprint in `ServerHello`, but this
value is **display-only** and is *not* the value that is pinned or verified. Reason: the TLS
cert and the Ed25519 identity key are generated independently with no cryptographic binding
between them, so pinning the self-declared Ed25519 value (sent *inside* the channel being
trust-decided) would be circular — an attacker who impersonates the server at the TLS level
would supply whatever Ed25519 value they like. Pinning the TLS cert fingerprint is the only
value that is genuinely verifiable at the moment of trust decision.
This is a known limitation of the current design. Closing it properly requires binding the
Ed25519 key into the TLS cert (e.g. as a SubjectAltName or extension), which is a planned
future improvement. Until then, clients display both values but gate on the cert fingerprint.
Client certificates are reserved for a future "key-based identity" option (see roadmap) but
are not required in v1.