From c7ae6065041b36766939815d16f8e7ca979c1476 Mon Sep 17 00:00:00 2001 From: goodboy Date: Mon, 17 Aug 2026 17:44:58 -0400 Subject: [PATCH] Clarify the `wg`-over-TIPC motivation, harden caveats MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-on to 4aa7a890 now that the encryption premise is corrected: reframe *why* we want a `wg` mesh under TIPC (#502) rather than leaving a "wg adds the crypto TIPC lacks" reading lying around, since that reading is flat wrong. The motivation is different but still real, - TIPC's keys are **symmetric + pre-shared**, so distribution, rotation and revocation are all on the operator; `wg` brings public-key identity and a handshake. - `wg` is an overlay *every* tpt can sit on (tcp now, quic later), not a TIPC-only mechanism. - NAT traversal / roaming, which raw TIPC bearers have no story for at all. Which to actually default to wants **benchmarking** — native crypto skips a tunnel hop and may win for LAN-local clusters. Also lean much harder on the udp-bearer-only caveat in the handoff doc; it's the one that bites. A wg iface is L3/`tun` w/ no L2 addr, so there's no device for `media eth` to name — which means #378's "ethernet bearers pair most excellently w/ wg tunnelling" framing does NOT hold: on a given link the L2 path and the wg path are mutually exclusive. Any design assuming both is broken from the start. (this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`)) --- ai/tpt-backends/01_tipc_HANDOFF.md | 48 +++++++++++++++++++++-- docs/guide/tipc.rst | 18 ++++++--- examples/multihost/tipc_cluster/README.md | 19 ++++++--- 3 files changed, 70 insertions(+), 15 deletions(-) diff --git a/ai/tpt-backends/01_tipc_HANDOFF.md b/ai/tpt-backends/01_tipc_HANDOFF.md index c66e6e0a..b378c729 100644 --- a/ai/tpt-backends/01_tipc_HANDOFF.md +++ b/ai/tpt-backends/01_tipc_HANDOFF.md @@ -84,8 +84,8 @@ plan originally assumed. | Topology `struct tipc_event` is **48 bytes** (`4+4+4+8+28`) | the plan said 40 | | The topology server **accepts native `'='` byte-order** | the plan's proposed `'>'`-retry endianness probe was deleted as unnecessary | | `TIPC_WAIT_FOREVER` is `-1` in python | must be masked (`& 0xFFFFFFFF`) before packing as unsigned | -| TIPC **has** AES-GCM encryption (`tipc node set key`, linux 5.9+) | cluster/master/per-node keys + rekeying. Symmetric pre-shared, which is why a wg mesh is still preferred — see §6. | -| A wg interface is L3/`tun` (`POINTOPOINT,NOARP`, `link/none`) | TIPC's `eth` media **cannot** bind it; the udp bearer is mandatory over wg | +| TIPC **has** AES-GCM encryption (`tipc node set key`, linux 5.9+) | cluster/master/per-node keys + rekeying. So "wg adds the encryption TIPC lacks" is **false** — see §6 for the real motivation. | +| A wg interface is L3/`tun` (`POINTOPOINT,NOARP`, `link/none`) | TIPC's `eth` media **cannot** bind it — udp media is *mandatory* over wg. See the §6 caveat; this one bites. | Two design decisions that are **closed**, with reasons: @@ -170,8 +170,48 @@ All filed with the `follow-up` label. ### the wg direction [#502] is the strategic one. The intent is that TIPC-over-`wg` -becomes our go-to multihost transport deployment, with composed -addresses of the form: +becomes our go-to multihost transport deployment. + +> ⚠️ **Do not repeat the claim that wg adds encryption TIPC +> lacks.** We assumed that initially and it is **wrong**. TIPC +> ships AES-GCM crypto of its own (`tipc node set key`, linux +> 5.9+) with cluster/master/per-node keys and rekeying. +> +> The motivation is different but still real: +> - **key management** — TIPC keys are symmetric and +> *pre-shared*; distribution, rotation and revocation are the +> operator's problem. wg gives public-key identity + handshake. +> - **uniformity** — wg is an overlay *every* backend can sit on +> (tcp now, quic later), not a TIPC-only mechanism. +> - **NAT traversal / roaming**, which raw TIPC bearers have no +> story for. +> +> Which to default to should be **benchmarked**, not assumed: +> TIPC-native crypto avoids a tunnel hop and may win on latency +> for LAN-local clusters. + +> ⚠️ **`udp` media is MANDATORY over wg — `eth` cannot work.** +> A wg interface is L3/`tun`: `POINTOPOINT,NOARP`, `link/none`, +> no L2 address at all. There is no device for `tipc bearer +> enable media eth device …` to name. +> +> ```bash +> # impossible over wg +> sudo tipc bearer enable media eth device wg0 +> # required, bound to the wg overlay IP +> sudo tipc bearer enable media udp name wgmesh localip 10.0.11.1 +> ``` +> +> Consequence worth internalizing: #378's "ethernet bearers pair +> most excellently with wireguard tunnelling" framing does **not** +> hold — on a given link the low-latency L2 path and the wg path +> are *mutually exclusive*. Any design that assumes both is +> broken from the start. +> +> Also mind the MTU: wg links are typically 1420, under +> ethernet's 1500, so TIPC link MTU wants checking not assuming. + +Composed addresses take the form: ``` /ip4//udp/51820/wg/u/tipc/// diff --git a/docs/guide/tipc.rst b/docs/guide/tipc.rst index 21be2448..d50fa3de 100644 --- a/docs/guide/tipc.rst +++ b/docs/guide/tipc.rst @@ -185,12 +185,18 @@ examples in ``examples/multihost/wg_lan/``. .. note:: - TIPC is **not** unencrypted — it ships AES-GCM crypto of its - own (``tipc node set key``, linux 5.9+) with cluster, master - and per-node keys plus rekeying intervals. Those keys are - symmetric and pre-shared though, so a wg mesh is still - preferred for public-key identity, NAT traversal, and an - overlay every transport can share. + **wg is not about confidentiality here.** TIPC ships AES-GCM + crypto of its own (``tipc node set key``, linux 5.9+) with + cluster, master and per-node keys plus rekeying intervals, so + "wg adds the encryption TIPC lacks" is simply wrong. + + The motivation is different but real: TIPC's keys are + *symmetric and pre-shared*, leaving distribution, rotation and + revocation to the operator, whereas wg brings public-key + identity and a handshake — plus NAT traversal, and one overlay + that *every* transport can share rather than a TIPC-only + mechanism. Which to prefer is worth benchmarking; native + crypto avoids a tunnel hop entirely. Gotchas ------- diff --git a/examples/multihost/tipc_cluster/README.md b/examples/multihost/tipc_cluster/README.md index ee2c0872..fca083a2 100644 --- a/examples/multihost/tipc_cluster/README.md +++ b/examples/multihost/tipc_cluster/README.md @@ -136,12 +136,21 @@ Note the tipc segment has no locative part, unlike tcp's inner `/ip4/../tcp/..` — a service name is location-independent, so wg carries the routing and tipc carries identity. -Worth knowing: TIPC is **not** unencrypted. It ships AES-GCM +**wg here is not about confidentiality.** TIPC ships AES-GCM crypto of its own (`tipc node set key`, linux 5.9+) with -cluster/master/per-node keys and rekeying. Those keys are -symmetric and pre-shared, which is why a wg mesh is still -preferred — public-key identity, NAT traversal, and one overlay -shared by every transport. +cluster/master/per-node keys and rekeying, so "wg adds the +encryption TIPC lacks" is wrong. + +The motivation is different but real: TIPC's keys are *symmetric +and pre-shared* — distribution, rotation and revocation are all +on you — whereas wg gives public-key identity and a handshake, +NAT traversal, and one overlay shared by every transport instead +of a TIPC-only mechanism. Worth benchmarking either way; native +crypto skips the tunnel hop. + +Note too that the ethernet-bearer pairing #378 imagined does +**not** apply over wg: on a given link the L2 path and the wg +path are mutually exclusive. ### scope