Aleksandr Bogomiakov
90ef5cefec
Offline devices reserved names and IPv4 addresses indefinitely, leaving stale members in the device history. Give every authenticated network participant the same right to retire another device's observed signed claim without an owner, quorum, permanent identity ban or secret change. Add a separately signed retirement containing the target's original signed claim as proof. Verify both signatures and network scopes, retain the strongest proved cutoff per target with deterministic ties, and suppress claim versions at or below it in membership, hostname ownership and IPv4 allocation. Keep the old signed records and range agreement, and retain markers after a newer claim returns so old replicas cannot resurrect obsolete reservations. A returning device signs a newer claim, allocates against current holders and resets its previous hostname priority rather than taking a reused name with an old time. Commit local retirement and the requester's author counter atomically before announcing it; receivers persist proofs before applying them. Bound history to 1024 targets by default, reject additional targets without evicting protection, and treat corrupt or over-limit mandatory storage as an explicit error. Repeat bounded marker batches with a per-session rotating cursor so queue pressure cannot indefinitely starve later markers. Exclude retired claims and cached hints from history-derived discovery without preventing a fresh authenticated device from returning. Expose Agent::forget_node through the shared local control API. CLI command tsng network forget-node accepts exact network names, full ids or unique id prefixes, and exact node hostnames, ids, prefixes or overlay IPv4 addresses. Ambiguous selections change nothing. Recheck the observed version and refuse self, online nodes, the selected exit node and absent or changed claims. Add Forget with an identity confirmation to offline tray device rows. Widen Show devices to 1440x640 with an 800x400 minimum to fit its contents. Control ALPN/version advances to tsunagi/ctrl/7 and local IPC to 21; upgrade all peers and restart the agent with matching CLI/tray clients. Data ALPN 5, network identity derivation, handshake encoding and existing record signing bytes remain unchanged. SQLite schema 9 adds retirement storage while retaining identity, secrets, settings and signed claims. Document behavior and limits. Validation on Linux through nix develop: - cargo fmt --all -- --check - cargo clippy --locked --workspace --all-targets -- -D warnings - cargo test --locked --workspace --all-targets: 519 passed, 2 existing ignored tests; inherited TSUNAGI_CONTROL_SOCKET and TSUNAGI_CONTROL_GROUP were unset - git diff --check and the built CLI forget-node help Tests use real iroh authentication and SQLite. Cover restart, stale-replica recovery, equal rights and network isolation, hostname reuse and return, twelve marker batches through a two-message queue, malformed signatures and proofs, invented future cutoffs, deterministic merge, capacity, migration and injected counter-write rollback, selectors and cleanup through two real CLI processes. Earlier iterations caught a private test API, a collapsible tray conditional and a crash-based CLI test waiting for QUIC's idle timeout; corrected before the final successful suite. Manual tray rendering, macOS/Windows, privileged TUNs and public-network traversal were not run. The requested RC tag is v0.1.0-rc.31; no push was requested.
291 lines
14 KiB
Markdown
291 lines
14 KiB
Markdown
# Protocol
|
|
|
|
Module boundaries are in [architecture.md](architecture.md); the threat model
|
|
is in [threat-model.md](threat-model.md).
|
|
|
|
## Versioning
|
|
|
|
Two versions exist and are independent:
|
|
|
|
- **Identity scheme**, `tsunagi-network-id-v1`. Frozen. Changing it creates a
|
|
different network space for the same name and secret.
|
|
- **Control protocol**, ALPN `tsunagi/ctrl/7`, `PROTOCOL_VERSION = 7`.
|
|
|
|
Upgrading the crate or bumping the control protocol must never change an
|
|
existing `NetworkId`.
|
|
|
|
Control version 7 adds signed offline-node retirement messages to version 6's
|
|
private AWG transport negotiation and delivery checks. Data ALPN remains
|
|
`tsunagi/data/5`. All members must upgrade together; network ids, handshake
|
|
encoding and existing record signatures are unchanged. Local CLI/tray IPC is
|
|
version 21, so restart the agent with matching clients. SQLite schema 9 adds
|
|
retirement storage while preserving existing identities, settings and records.
|
|
See [sync-model.md](sync-model.md#offline-node-cleanup) and [amnezia.md](amnezia.md).
|
|
|
|
## Canonical encoding
|
|
|
|
Everything that is hashed or MAC'd uses length-prefixed fields, written here as
|
|
`LP(x) = u32_be(len(x)) || x`. String concatenation is never used, so no two
|
|
different field splits can produce the same bytes.
|
|
|
|
## Network space identity
|
|
|
|
```text
|
|
salt = SHA-256( LP("tsunagi-network-id-v1") || LP(name_utf8) )
|
|
prk = HKDF-SHA256-Extract(salt, ikm = secret_bytes)
|
|
|
|
info(label) = LP("tsunagi-network-id-v1") || LP(label)
|
|
network_id = HKDF-Expand(prk, info("network-id"), 32)
|
|
discovery_key = HKDF-Expand(prk, info("discovery-key"), 32)
|
|
auth_key = HKDF-Expand(prk, info("handshake-auth"), 32)
|
|
```
|
|
|
|
HKDF's `info` parameter is what separates the three outputs (RFC 5869 §3.2).
|
|
The labels and this encoding are frozen.
|
|
|
|
**Name rules.** 1..=64 bytes of UTF-8, no control characters, no leading or
|
|
trailing ASCII whitespace — such a name is *rejected*, not trimmed. The name is
|
|
used verbatim: no case folding, no Unicode normalisation. `Home` and `home` are
|
|
different network spaces.
|
|
|
|
**Secret rules.** Used verbatim: never trimmed, case-folded, normalised or
|
|
truncated. At least 16 bytes; `NetworkSecret::generate()` produces 32 random
|
|
bytes. The canonical text form is `tsn1` followed by lowercase unpadded base32.
|
|
|
|
**Key separation.** `network_id` is public. `discovery_key` is what a discovery
|
|
backend is told; it is secret-derived but is **not** a credential — learning it
|
|
does not help pass the handshake, and it must never be used as a password or
|
|
bearer token. `auth_key` never leaves the process.
|
|
|
|
## No competing genesis
|
|
|
|
A network's description is `NetworkDescriptor { scheme, name, network_id }`. It
|
|
contains no creator identity, no creation time and no owner signature, so two
|
|
agents started independently with the same parameters produce byte-identical
|
|
descriptors. No minimum-hash rule, no vote, no leader. The secret is not part
|
|
of it.
|
|
|
|
A network's name does not change inside an existing space. A different name or
|
|
secret is a different space.
|
|
|
|
## Framing
|
|
|
|
One QUIC bidirectional stream per session. A frame is `u32_be(len) || payload`.
|
|
The announced length is checked against `Limits::max_frame_len` (64 KiB by
|
|
default) **before** any buffer of that size is allocated. Payloads are
|
|
[postcard], a compact deterministic serde format — not a general RPC framework.
|
|
|
|
No encryption is layered on top of iroh: QUIC/TLS already provides
|
|
confidentiality, integrity and endpoint authentication.
|
|
|
|
[postcard]: https://docs.rs/postcard
|
|
|
|
## Handshake
|
|
|
|
A successful iroh connection proves only *which endpoint* is on the other side,
|
|
because the endpoint id is the public key in the TLS certificate. Anyone can
|
|
dial us. Membership of a specific network is proved separately.
|
|
|
|
iroh exposes the TLS exporter (RFC 5705) through
|
|
`Connection::export_keying_material`. That yields the same secret bytes on both
|
|
ends of *this* connection, which is what stops a proof being replayed
|
|
elsewhere. **It proves nothing about the shared secret on its own**, because
|
|
both ends of any connection can compute it. The membership proof is the HMAC
|
|
keyed by `auth_key`; the exporter output is just one of its inputs.
|
|
|
|
```text
|
|
cb = TLS-Exporter(label = "tsunagi/handshake/v1", context = network_id, 32)
|
|
|
|
transcript(role) = LP("tsunagi-handshake-v1")
|
|
|| LP(role) // "initiator-proof" | "responder-proof"
|
|
|| LP(u16_be(protocol_version))
|
|
|| LP(network_id) // 32 bytes
|
|
|| LP(initiator_endpoint_id) // 32 bytes
|
|
|| LP(responder_endpoint_id) // 32 bytes
|
|
|| LP(cb) // 32 bytes
|
|
|| LP(nonce_initiator) // 16 bytes
|
|
|| LP(nonce_responder) // 16 bytes
|
|
|
|
proof(role) = HMAC-SHA256(auth_key, transcript(role))
|
|
```
|
|
|
|
What each input buys:
|
|
|
|
| input | property |
|
|
|---|---|
|
|
| `auth_key` | membership in this network space |
|
|
| `cb` | binding to this connection; a captured proof is useless on another |
|
|
| `network_id` | binding to this network space |
|
|
| both endpoint ids | binding to these two identities |
|
|
| distinct `role` labels | no reflection: a proof cannot be bounced back |
|
|
| both nonces | freshness contributed by each side |
|
|
|
|
Message order:
|
|
|
|
```text
|
|
initiator -> responder : Hello { version, network_id, nonce_i }
|
|
initiator <- responder : HelloAck { version, nonce_r }
|
|
initiator -> responder : AuthProof { proof(initiator) }
|
|
initiator <- responder : AuthProof { proof(responder) } // only after the first verified
|
|
```
|
|
|
|
The responder emits nothing derived from `auth_key` until the initiator's proof
|
|
verifies, so a caller who does not know the secret learns nothing. Comparison
|
|
is constant time. Endpoint ids always come from the TLS certificate, never from
|
|
a peer's claim. Until both steps complete, no regular control message is
|
|
accepted in either direction. The whole exchange is bounded by
|
|
`Limits::handshake_timeout`.
|
|
|
|
A `Hello` naming a network this agent does not have active is rejected with
|
|
"unknown network". Because the claim is unverified at that point, the rejection
|
|
event does not report a network id.
|
|
|
|
## The data plane protocol
|
|
|
|
IP plugin packets never travel on a control connection. They use their own
|
|
ALPN, `tsunagi/data/5`, on their own iroh connection:
|
|
|
|
```text
|
|
initiator -> responder : (the same membership handshake as above)
|
|
initiator -> responder : DataOpen { protocol, max_datagram }
|
|
initiator <- responder : DataOpenAck { accepted, max_datagram }
|
|
thereafter : QUIC datagrams carrying fragments of opaque payloads
|
|
```
|
|
|
|
The membership handshake is identical and bound to the same network, so a data
|
|
channel cannot be opened by somebody who does not know the secret. `protocol`
|
|
is bounded and must name a plugin the responder actually runs; otherwise the
|
|
channel is declined, which is an ordinary outcome rather than an error.
|
|
|
|
Only one side dials — the one with the smaller endpoint id — so two agents
|
|
never open two channels for the same thing.
|
|
|
|
Packets ride as QUIC **datagrams**: unreliable and unordered, which is what a
|
|
tunnelled protocol wants, and free of the head-of-line blocking a stream would
|
|
add. `max_datagram` negotiates the reassembled payload limit (at most 65536
|
|
bytes), independently of the current QUIC path MTU. The transport reads QUIC's
|
|
current datagram capacity for every fragment, including after migration.
|
|
|
|
Every datagram starts with a 16-byte header: packet ID (`u64`), total payload
|
|
length (`u32`), and byte offset (`u32`), all big endian. The payload is the
|
|
complete peer-relay envelope containing opaque plugin bytes. Relays reassemble
|
|
before forwarding and fragment again for their outgoing path; they never
|
|
decrypt the plugin's payload. Small packets use the same framing in one part.
|
|
|
|
Reassembly tolerates reordering and exact duplicates. Conflicting lengths,
|
|
overlapping data and excessive fragment counts discard that packet. Each link
|
|
allows at most 64 incomplete packets, 256 KiB of their payload buffers, and 128
|
|
fragments per packet. Incomplete packets expire after five seconds, without
|
|
holding up subsequent packets. Packet IDs are scoped to a QUIC connection;
|
|
reassembly is created only after the membership handshake. All limits live in
|
|
`config.rs`. There is no transport-layer retransmission added by this framing.
|
|
|
|
Version 4 added a routing envelope inside the transport fragmentation framing,
|
|
and version 5 added the end-to-end protocol to it:
|
|
|
|
| field | bytes | encoding |
|
|
|---|---:|---|
|
|
| envelope version | 1 | `2` |
|
|
| remaining hops | 1 | initially `16`; transit decrements, drops at `1` |
|
|
| source peer | 32 | original endpoint public key |
|
|
| destination peer | 32 | final endpoint public key |
|
|
| flow id | 8 | big endian opaque stable hash supplied by the plugin |
|
|
| protocol | 8 | big endian FNV-1a of the end-to-end protocol id (`wg`, `tcp-tls`, ...) |
|
|
| payload | remaining | end-to-end encrypted plugin bytes |
|
|
|
|
The fixed header is 82 bytes. Zero/oversized hop limits, unknown versions,
|
|
short frames, oversized datagrams and unknown sources are rejected. A frame
|
|
addressed here is delivered to the inbox of its source and protocol; transit
|
|
goes straight to its next transport, whatever kind of transport that is. The
|
|
network is bound to the authenticated transport connection, not supplied by
|
|
the frame. The protocol names which end-to-end tunnel the payload belongs to
|
|
and is independent of the links it crosses: a datagram of one protocol can
|
|
travel over a link opened for another, and a middle member needs no protocol
|
|
in common with either end. Intermediate nodes cannot decrypt or authenticate
|
|
the inner payload; the destination's tunnel does that, so a frame naming the
|
|
wrong protocol or a forged source is simply discarded there. Flow ids are
|
|
routing hints, not authorization proofs.
|
|
|
|
`Reachable { links: [{ peer, protocol }] }` lists the sender's direct links;
|
|
`protocol` is the kind of transport the link is, for diagnostics, and routing
|
|
ignores it. Each row belongs to the authenticated sender and is replaced
|
|
atomically, expires after 90 seconds, and is withdrawn on session closure. Only
|
|
authenticated members enter the graph; local edges always come from actual
|
|
links.
|
|
Announcements refresh on the existing control maintenance interval and are
|
|
sent immediately on link changes. Topology stays volatile, outside signed state.
|
|
|
|
Version 5 also adds `hostname_since` to a signed hostname claim (signing domain
|
|
`tsunagi-signed-record-v3`): a name belongs to whoever claimed it first. Stored
|
|
records signed before are discarded on upgrade and re-published by their
|
|
authors.
|
|
|
|
Upgrade both endpoints and intermediate peers together. Older control and data
|
|
ALPNs cannot interoperate. The network secret, device identity, identity
|
|
derivation, transcript encoding and stored network configuration are unchanged.
|
|
|
|
Separate connections mean separate congestion control, so a saturated data
|
|
plane cannot delay control messages, and a data plane failure cannot take the
|
|
control plane down with it.
|
|
|
|
## Control messages
|
|
|
|
After authentication, every frame is an `Envelope { network_id, message }` and
|
|
the `network_id` is re-checked against the session's network on every message.
|
|
A mismatch ends that session and is counted as a protocol violation; it does
|
|
not affect other networks.
|
|
|
|
| message | meaning |
|
|
|---|---|
|
|
| `Announce { hostname, capabilities, broadcast }` | this agent's hostname, IP-plugin capabilities and local broadcast participation |
|
|
| `Transport { protocol, payload }` | private, bounded per-peer transport negotiation; never state or a public message event |
|
|
| `Ping { seq, payload }` | small request used to verify the exchange |
|
|
| `Pong { seq, payload }` | the echoed reply |
|
|
| `State { records }` | a snapshot of signed records, merged into what the receiver holds |
|
|
| `Retirements { markers }` | signed cleanup markers with the target's original signed claim as proof |
|
|
| `Peers { peers }` | unverified member address hints, requiring their own handshake |
|
|
| `Reachable { links }` | sender's current direct data links, by kind of transport |
|
|
| `Bye { reason }` | graceful goodbye; not a revocation of anything |
|
|
|
|
`broadcast` is a per-network local opt-in, enabled by default and treated as
|
|
false until an authenticated announcement arrives. It governs IP broadcast
|
|
fanout and local admission; encrypted transit still uses the existing envelope.
|
|
See [broadcast.md](broadcast.md) for scope and persistence.
|
|
|
|
A `State` snapshot is merged, never substituted: an author missing from it is
|
|
left untouched. Each record carries its own signature, so a peer forwarding
|
|
somebody else's record cannot alter it, and a record that fails verification
|
|
is dropped without affecting the rest of the batch. See
|
|
[sync-model.md](sync-model.md).
|
|
|
|
`PluginCapability { protocol, version, enabled, data }` is opaque to the core:
|
|
`data` is bounded and handed to the matching plugin unparsed. Nothing in it is
|
|
ever treated as a shell command, filesystem path or OS setting.
|
|
|
|
Every decoded message is validated against `Limits` before it reaches anything
|
|
else. A rejected message never stops a network or the agent.
|
|
|
|
## Limits
|
|
|
|
Defaults from `Limits`, all configurable:
|
|
|
|
| limit | default |
|
|
|---|---|
|
|
| frame payload | 64 KiB |
|
|
| hostname | 255 bytes |
|
|
| capabilities per announcement | 16 |
|
|
| capability payload | 4 KiB |
|
|
| echo payload | 4 KiB |
|
|
| reason string | 256 bytes |
|
|
| handshake timeout | 10 s |
|
|
| dial timeout | 10 s |
|
|
| write timeout | 30 s |
|
|
| concurrent dials per network | 8 |
|
|
| sessions per network | 64 |
|
|
| inbound handshakes in flight | 32 |
|
|
| outbound queue per session | 64 |
|
|
|
|
Liveness of an established session is delegated to QUIC: iroh configures
|
|
keep-alives and an idle timeout, so a dead peer surfaces as a read error rather
|
|
than needing a heartbeat in this protocol.
|