owen/umn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

a lot

Browse Source
This commit is contained in:
Owen Qwen
2026-08-31 16:44:54 -05:00
parent e71b3ada71
commit 5f99d9b137
21 changed files with 1045 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/protocol.md
+13 -7
View File
@@ -1,10 +1,10 @@
# Ultra Mesh Protocol v1
# Ultra Mesh Protocol v2
This document describes the protocol implemented by `umnd`. Multi-byte integers use network byte order unless the binary property-list encoding defines their representation.
## Framing and identities
Every peer message is a four-byte unsigned body length followed by a binary property-list `WireEnvelope`. Bodies are limited to 1,200,000 bytes. An envelope carries protocol version `1` and one `WireMessage`. Unknown versions terminate the peer session.
Every peer message is a four-byte unsigned body length followed by a binary property-list `WireEnvelope`. Bodies are limited to 1,200,000 bytes. An envelope carries protocol version `2` and one `WireMessage`. Unknown versions terminate the peer session, so v1 peers fail closed.
A node record contains:
@@ -36,9 +36,11 @@ The sender serializes an `InnerFrame`, signs its bytes with Ed25519, and encrypt
3. Derive a 32-byte key using HKDF-SHA256, salt `umn-e2e-v1`, and the destination address as shared information.
4. Seal with ChaCha20-Poly1305.
The routed payload contains only the ephemeral public key and the combined authenticated ciphertext. The receiver decrypts it, verifies the signature, validates the embedded source record, and confirms that its derived address matches the outer source address. Relays cannot decrypt the inner frame. Neighbor discovery and topology metadata are authenticated but intentionally public in v1.
The routed payload contains only the ephemeral public key and the combined authenticated ciphertext. The receiver decrypts it, verifies the signature, validates the embedded source record, and confirms that its derived address matches the outer source address. Relays cannot decrypt the inner frame. Neighbor discovery and topology metadata are authenticated but intentionally public in v2.
Inner frame kinds are ping request/reply, text, stream open/data/ack/close/reset, and error. Logical destination ports are inside the sealed payload.
Inner frame kinds are ping request/reply, text, stream open/data/ack/close/reset, `ipv6Packet`, and error. Logical destination ports are inside the sealed payload. An `ipv6Packet` contains the complete IPv6 packet and a signed UUID retained in a bounded destination replay cache. Routed packets mark native bulk traffic so neighbor queues can bound and deprioritize it behind hello, link-state, and keepalive messages.
Native packets must use the authenticated outer source and destination as their IPv6 source and destination. Endpoints accept TCP, UDP, ICMPv6 echo and related errors, plus bounded standard extension-header chains. They reject fragments, multicast, malformed lengths, non-mesh addresses, unsafe routing headers, and unsupported next-header values. Relays route ciphertext and do not inspect the IP header.
## Streams and failure handling
@@ -46,7 +48,7 @@ A stream uses a random 64-bit identifier. `streamOpen` occupies sequence zero; d
Unacknowledged frames are retransmitted through the route table's current next hop. Retry delay begins at 500 milliseconds and backs off to five seconds. No progress for 60 seconds resets the stream. This makes streams independent of any one neighbor TCP connection and allows an access-point path to be replaced by a peer-to-peer or multi-hop path.
Each endpoint enforces these v1 resource bounds:
Each endpoint enforces these resource bounds:
- 1 MiB aggregate data per stream.
- 32 simultaneous streams per node.
@@ -57,6 +59,10 @@ New operations are live-route-only and are not written to a durable delivery que
## Firewall and local IPC
Ping terminates in the daemon and is always available. All ports otherwise default to denied. A stream or text message is delivered only when an allow rule matches its authenticated source and a local process currently binds the destination port. Firewall rules affect terminating traffic, not transit forwarding.
Ping terminates in the daemon and is always available. Firewall rules explicitly select `overlay`, `tcp`, or `udp`. Persisted rules without a protocol decode as `overlay`; new IPC mutations must specify one. A stream or text message is delivered only when an overlay allow rule matches its authenticated source and a local process currently binds the destination port. Outbound native flows are allowed, return TCP/UDP state is bounded and timed, and new inbound flows require a matching source/port rule. ICMPv6 echo has per-source rate limiting. Firewall rules affect terminating traffic, not transit forwarding.
Local tools use a mode-`0600` Unix-domain socket. IPC messages use the same four-byte framing and binary property-list encoding, carry IPC version `1`, and support control operations, service binding, and stream events. A binding is removed when its IPC connection closes.
Local tools use a mode-`0600` Unix-domain socket. IPC messages use the same four-byte framing and binary property-list encoding, carry IPC version `2`, and support control operations, interface diagnostics, service binding, and stream events. A binding is removed when its IPC connection closes.
## Privileged interface protocol
The root LaunchDaemon accepts only the installing UID (verified with `getpeereid`) on its mode-`0600` socket. After an `UMN2 <local-address>` greeting it creates an MTU-1280 `utun`, configures the local `/128`, and sends a duplicated descriptor using `SCM_RIGHTS`. Subsequent `ROUTES` messages replace a validated set of at most 31 mesh `/128` routes. Commands are invoked as fixed `/sbin/ifconfig` or `/sbin/route` argument arrays, never through a shell. EOF removes all routes and closes the interface.