Repository navigation
SPEC.md draft 2: WireGuard as the connection, pluggable carriers - #28
Open
kylemclaren wants to merge 2 commits into
Open
kylemclaren wants to merge 2 commits into
kylemclaren wants to merge 2 commits into
Conversation
A peer's Ed25519 key, converted, is its WireGuard key, so the tunnel's mutual authentication is the protocol's and `auth` goes away. Carriers move WireGuard datagrams and are untrusted and interchangeable: udp, tailcat (the default), ws through any HTTP tunnel, unix. Addresses are awp1 blobs of key, pre-shared key and endpoints; hello carries `ep`. Draft 1's implementation notes are folded in. Not compatible with draft 1; the implementation still speaks v0, so the spec example test skips until the wire package follows.
- Pre-shared keys are per pair: the key two peers first connected with becomes theirs and both use it from then on, whoever dials; rotating the listener's key locks out only keys not met yet (5.2). - The tunnel IPv6 derives from the X25519 key, since a responder only learns that from a handshake; the Ed25519 sign-bit ambiguity is noted. - hello.addr is the sender's awp1 address without its pre-shared key, and introduce.peer.address an awp1 address that carries the key when the introducer holds it (open question 6 resolved). - Connection carriers frame datagrams with a 16-bit length prefix; the tailcat carrier's value is a tailcat address, and tailcat is an outer carrier trusted for nothing rather than the identity's own node. - The awp tunnel helper is described as built: one process per SDK peer, a control socket for dials, forwarding for accepted streams, and the hello-key check done before the SDK sees a line.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft 2 of the protocol. Spec text only; the implementation still speaks draft 1 (protocol v0), and
TestSpecExamplesskips with a reason until thewirepackage follows.What changes
authand the hello nonce are gone: the tunnel already proved both keys.hello.keymust match the tunnel's remote key. Worked key vectors are in §4.2, cross-checked both ways.udp(6PN, LAN, public addresses),tailcat(DERP bootstrap, NAT traversal, relay; still the defaultawp listencarrier and meant to stay the path of least resistance),ws(one datagram per binary WebSocket message; Cloudflare quick/named tunnels, ngrok, a Fly app, browsers),unix. There is no plaintext binding any more andcheckPrivate-style heuristics have no place in the spec.awp1+ base64url(CBOR{key, psk, ep[]}). The PSK is the admission secret: without it a listener is silent, with it any key is admitted to the tunnel (Tailscale's wireguard-go fork already supports this via its lookup hook, which is how tailcat admits clients).hello.epcarries the sender's endpoints so either side can reconnect. Tunnels roam: an endpoint change is not a reconnect.audon grants and attenuated delegation, cumulative acks, chunks before their msg,seencounts content lines only, strictly increasing ids, one connection per pair with the smaller-key rule, arefusedcode,too_largecloses, encodings and canonical JSON spelled out, outbox retention, what "open thread" means.awp tunnelstdio helper. Native tunnels and a WASM build are possible and conformant, not required.Not in this PR
transportwithudp/unixand the identity binding; tailcat behind the interface using the identity-derived node key;wscarrier and a cloudflared test; tunnel conformance scenarios and droppingauth; SDK driver contract fromtailcattoawp tunnel; schemav1.Open questions are reset in §19 (native datagram framing, multi-party, capability chains, key rotation, blobs on a second stream, PSK in introductions, more carriers).