Repository navigation
Description
Problem
Since v0.6.0 (#84, #85) every tailcat address carries a WireGuard pre-shared key, and the docs describe it as providing post-quantum confidentiality and keeping a DERP operator who sees the node keys out of the tunnel. Both properties hold only while the address is secret: the PSK is a symmetric secret that lives in the address.
But the README also documents, as a first-class flow, publishing the address in a DNS TXT record and gating access with tailcat serve --allow=.... In that flow the PSK is public, so harvest-now-decrypt-later protection is zero, and --psk=true vs --psk=false makes no security difference at all. Nothing says so today: ConnInfo.PresharedKey's doc comment and the --psk help text still attribute post-quantum confidentiality to the PSK unconditionally. (Filippo's suggestion in #84 was explicitly conditioned on the addresses "already [being] secret tokens".)
Everything else in tailcat is already public-key based (Noise IK / X25519 for the tunnel, client node keys for --allow, separate disco keys). The PQ layer is the one piece that is symmetric and address-secrecy-dependent.
Question
Is any asymmetric / post-quantum key agreement planned? If not, would you be open to a PR along the lines below? I have a fuller writeup (byte layouts, KDF, negotiation matrix, test plan) and can attach it or send the PR directly if the direction is acceptable.
Proposal: ephemeral ML-KEM-768 in the meow bootstrap, per-connection PSK
- The client generates an ephemeral ML-KEM-768 keypair per
Client(Go stdlibcrypto/mlkem, no new dependency). - New meow ping type
0x03: today's fields plus a KEM id and the encapsulation key (1184 B; packet ≈ 1254 B). The server runs the usualonMeow/ allow-list path, encapsulates, and answers with a new meowed type0x04: KEM id, an 8-byte tag of the ek, and the ciphertext (1088 B; packet ≈ 1102 B). Well underderp.MaxPacketSize. - Both sides derive a per-peer PSK:
HKDF-SHA256(ikm = kem_ss, salt = addr_psk, info = "tailcat pq psk v1" || kem_id || server_pub || client_pub || H(ek) || H(ct)).
The server keeps a small per-client PSK map behind the existingSetPeerConfigFuncsource (peerConfigis already per-peer), memoised by(client, H(ek))so the 1 s ping resends and replays are idempotent, and callsSyncDevicePeerwhen a client shows up with a new ek. The client installs its PSK beforemeowWaitcloses, so the very first WireGuard handshake is already hybrid. - Address format unchanged, no new persisted key material, PQ forward secrecy per connection (the server never holds a KEM private key). The address PSK stays as the salt, so secret-address deployments keep every property they have now.
- Compatibility: old clients send
0x01and get classical service as today; new clients send0x03and, inautomode, start alternating with0x01after ~2 s so an old server (which never answers0x03) still works.--pq=auto|require|offonserveand on client modes lets either side refuse the downgrade.tailcat pingreports(post-quantum)/(classical), served processes getTAILCAT_PEER_PQ.
Why an unauthenticated exchange over DERP is fine
The KEM secret is only ever used as the WireGuard PSK, which is mixed into the Noise IK handshake. If anyone (including the DERP operator) substitutes ek or ct in flight, the two sides derive different PSKs and the handshake fails; the attacker cannot complete a handshake without the server's static private key. So an active attacker gets denial of service, which a relay already has, and a passive / harvest-now-decrypt-later attacker must break both X25519 and ML-KEM-768. This is the same trust model as TLS 1.3 X25519MLKEM768: the key share is unauthenticated in flight and authentication is bound in afterwards. Authentication itself stays classical, as in WireGuard, TLS hybrid KEX, and Tailscale.
Alternatives I considered and would not propose
- A static ML-KEM encapsulation key in the address: addresses go from ~60 to ~1650 characters, no PQ forward secrecy, key-file and wasm-storage migration.
- A Rosenpass-style in-tunnel upgrade after a classical handshake: same security, two extra round trips before the first byte, and more state to get the gating right.
Questions for you
- Are you comfortable with a ~1.25 KB meow ping (resent each second, max 10 s) on the shared tailcat.dev relays?
- ML-KEM-768 (the TLS default) or 1024?
- Should addresses gain a "server speaks PQ meow" capability bit so new clients can skip the fallback dance for new addresses? One CBOR bool that old clients ignore. I would leave it out of v1.
- Independently of the feature: the README "Key Management" text and the
--pskhelp should probably stop attributing post-quantum protection to the address PSK once the address is published.
Rough size if you want it: ~350 lines of non-test Go, ~400 lines of tests, small doc changes.
Activity
bradfitz commentedon Sep 26, 2026
Thanks for writing this up. I like the proposal. Couple misc thoughts:
But the one requirement I didn't see you address:
Thoughts?
XavierXIEXIN commentedon Sep 27, 2026
Thanks for the quick and thorough reply, and for the clear answers on packet size and ML-KEM-768. Taking your points in turn, with the goal of leaving this in a state where you don't need to come back to it until you want to.
The shared-relay-operator property is kept, I just buried it
The address PSK is not dropped in the proposal. It stays in the address and is the HKDF salt:
So the KEM does the post-quantum work and the address PSK does exactly the job you describe: a relay operator who knows the server's WireGuard public key can send a meow, can even complete the ML-KEM exchange and learn
kem_ss, but withoutaddr_pskthey derive a differentpsk_peerand the Noise handshake fails. That is the same outcome they get today, where the meow succeeds and only the handshake fails. Nothing the operator sees on the wire (ek,ct, both node keys) helps, becauseaddr_psknever leaves the address.If you want the property to hold one layer earlier, so the operator can't even get a
meowedor make the server do KEM work and allocate peer state, a 32-byte tag on the PQ ping does it:HMAC-SHA256(addr_psk, client_pub || ek), checked against the DERP source key before anything else. Pings from anyone who doesn't know the address PSK are dropped before encapsulation. The server would still accept--psk=falseaddresses without a tag, as today. I'd include that; it's cheap and it makes the "relays should be dumb" argument hold at every step rather than only at the handshake.For addresses that are deliberately published (TXT record +
--allow), the PSK is public and the relay-operator property is gone regardless of mechanism, which matches your answer in #105: at that point--allowis the access control. The KEM still gives those deployments the HNDL protection they currently lack, which was the original motivation.Tailscale's in-handshake ML-KEM
If wireguard-go gets ML-KEM-768 blended into the handshake, I agree that's the better end state and tailcat should just inherit it: the PSK becomes the anti-relay-operator part, the handshake becomes the PQ part, and the meow-level KEM in this proposal becomes unnecessary. I don't think tailcat should ship two PQ mechanisms. So I'd treat the meow-KEM design as the standalone fallback in case the handshake work is far off, and otherwise leave it on the shelf; the writeup is here if it's ever useful.
One small follow-up that applies either way: the current README "Key Management" text and the
--pskhelp say the address PSK provides post-quantum protection. That's true for secret addresses and false for published ones; once the handshake change lands it becomes simply true. Might be worth a one-line qualification in the meantime.Capability version, and what I'd ship now regardless
Fully agree on getting a "needs newer protocol" signal out ahead of time, and a capability integer is better than a bit. Concretely:
ExtraDecErrorUnknownFieldis opt-in), so today's clients parse such an address fine and then fail later with a timeout; that's unavoidable for already-shipped builds. The prep release adds the check and fails immediately with something likethis address requires tailcat protocol v2; this build supports v1, please upgrade.tailcat parseprints it.--min-client-version(or fold it into--pq=requirelater) so operators can refuse old clients once they choose to, with a log line saying which client was refused and why.That prep change is independent of which PQ mechanism eventually lands and is small (wire field, parse-time check, one meow type, help text, tests). I'm happy to send it as a PR if that's welcome; if you'd rather do it in-house alongside the Tailscale handshake work, the notes above should be enough and no reply is needed on my side.
Thanks again for engaging with this so carefully.
bradfitz commentedon Nov 4, 2026
@XavierXIEXIN, see #160. Thoughts?