From 0a72317b59f13e2d5b97c1009d12def6fee383e8 Mon Sep 17 00:00:00 2001 From: Johnathan Corgan Date: Sat, 21 Feb 2026 22:05:44 +0000 Subject: [PATCH] =?UTF-8?q?Design=20documentation=20illustration=20pass=20?= =?UTF-8?q?and=20FLP=E2=86=92FMP=20rename?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename FIPS Link Protocol (FLP) to FIPS Mesh Protocol (FMP) The "Link Protocol" name understated the layer's scope — spanning tree construction, bloom filter routing, greedy forwarding, and mesh-wide coordination go well beyond link-level concerns. Rename fips-link-layer.md to fips-mesh-layer.md, update FLP→FMP throughout docs and source code (FLP_VERSION→FMP_VERSION, wire.rs, rx_loop.rs, spanning_tree.rs). New SVG illustrations - Protocol stack: color-coded layer diagram replacing ASCII art - OSI mapping: side-by-side comparison with traditional networking layers - Bloom filter propagation: 6-node tree with sender-colored filter boxes showing split-horizon computation per link - Routing decision flowchart: 5-step priority chain with candidate ranking by tree distance and link performance - Coordinate discovery: sequence diagram showing LookupRequest propagation, response caching, and SessionSetup cache warming Redesigned existing SVGs - Architecture overview: uniform node layout, U-shaped encrypted link connectors, separate end-to-end session line - Node architecture: split Router Core into FSP and FMP layers, reorganize transports into Overlay/Shared Medium/Point-to-Point categories - Identity derivation: wider boxes, visible encode arrow, dashed npub line fips-intro.md revisions - Add inline references to prior work: Yggdrasil/Ironwood for coordinate routing, Noise Protocol Framework for IK handshakes, WireGuard for index-based session dispatch, Wikipedia for bloom filters, split-horizon, and greedy embedding - Add explanatory paragraphs after bloom filter diagram describing split-horizon filter computation and candidate selection behavior - Simplify transport abstraction language, remove I2P/LoRa references - Fix LookupRequest wording ("propagates" not "floods"), note intermediate node coordinate caching on lookup responses - Rewrite architecture overview prose to match redesigned diagrams --- docs/design/README.md | 4 +- docs/design/fips-architecture-overview.svg | 201 +++++++------ docs/design/fips-bloom-propagation.svg | 147 ++++++++++ docs/design/fips-configuration.md | 2 +- docs/design/fips-coordinate-discovery.svg | 156 +++++++++++ docs/design/fips-identity-derivation.svg | 53 ++-- docs/design/fips-intro.md | 264 +++++++----------- docs/design/fips-ipv6-adapter.md | 6 +- ...{fips-link-layer.md => fips-mesh-layer.md} | 68 ++--- docs/design/fips-mesh-operation.md | 4 +- docs/design/fips-node-architecture.svg | 168 +++++------ docs/design/fips-osi-mapping.svg | 64 +++++ docs/design/fips-protocol-stack.svg | 49 ++++ docs/design/fips-routing-decision.svg | 153 ++++++++++ docs/design/fips-session-layer.md | 22 +- docs/design/fips-software-architecture.md | 10 +- docs/design/fips-transport-layer.md | 66 +++-- docs/design/fips-wire-formats.md | 8 +- src/mmp/mod.rs | 2 +- src/node/handlers/rx_loop.rs | 8 +- src/node/session_wire.rs | 2 +- src/node/tests/spanning_tree.rs | 4 +- src/node/wire.rs | 20 +- src/noise/mod.rs | 2 +- src/noise/session.rs | 2 +- src/protocol/session.rs | 4 +- src/upper/icmp.rs | 10 +- 27 files changed, 997 insertions(+), 502 deletions(-) create mode 100644 docs/design/fips-bloom-propagation.svg create mode 100644 docs/design/fips-coordinate-discovery.svg rename docs/design/{fips-link-layer.md => fips-mesh-layer.md} (91%) create mode 100644 docs/design/fips-osi-mapping.svg create mode 100644 docs/design/fips-protocol-stack.svg create mode 100644 docs/design/fips-routing-decision.svg diff --git a/docs/design/README.md b/docs/design/README.md index d3a3113..a821c55 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -16,7 +16,7 @@ specific topics. | -------- | ----------- | | [fips-intro.md](fips-intro.md) | Protocol introduction: goals, architecture, layer model | | [fips-transport-layer.md](fips-transport-layer.md) | Transport layer: datagram delivery over arbitrary media | -| [fips-link-layer.md](fips-link-layer.md) | FIPS Link Protocol (FLP): peer authentication, link encryption, forwarding | +| [fips-mesh-layer.md](fips-mesh-layer.md) | FIPS Mesh Protocol (FMP): peer authentication, link encryption, forwarding | | [fips-session-layer.md](fips-session-layer.md) | FIPS Session Protocol (FSP): end-to-end encryption, sessions | | [fips-ipv6-adapter.md](fips-ipv6-adapter.md) | IPv6 adaptation: TUN interface, DNS, MTU enforcement | @@ -58,7 +58,7 @@ specific topics. fips-transport-layer fips-mesh- fips-software- │ operation architecture ▼ │ │ - fips-link-layer ◄────────┤ ▼ + fips-mesh-layer ◄────────┤ ▼ │ │ fips-state-machines ▼ │ fips-session-layer ├──► fips-spanning-tree diff --git a/docs/design/fips-architecture-overview.svg b/docs/design/fips-architecture-overview.svg index d75f960..59dd2f4 100644 --- a/docs/design/fips-architecture-overview.svg +++ b/docs/design/fips-architecture-overview.svg @@ -1,122 +1,113 @@ - + - + - + + + Node A + (source) + + + App + + FIPS + + WiFi - - Node A - npub1aaa... - (source) - - - App - - FIPS - - WiFi - - + Node B - npub1bbb... - (relay) - - - FIPS - - WiFi - - Eth + (transit) + + + FIPS + + WiFi + + Eth - - Node C - npub1ccc... - (relay) - - - FIPS - - Eth - - UDP + + Node C + (transit) + + + FIPS + + Eth + + UDP - - Node D - npub1ddd... - (relay) - - - FIPS - - UDP - - Tor + + Node D + (transit) + + + FIPS + + UDP + + Tor - - Node E - npub1eee... - (dest) - - - App - - FIPS - - Tor + + Node E + (destination) + + + App + + FIPS + + Tor - - - - - - WiFi + + + + WiFi + encrypted FMP link - - - - - Ethernet + + + Ethernet + encrypted FMP link - - - - - UDP/IP + + + UDP/IP + encrypted FMP link - - - - - Tor + + + Tor + encrypted FMP link - - - End-to-end encrypted session (A ↔ E) + + + End-to-end FSP session encryption (A ↔ E) - - Link - - Link - - Link - - Link - + + + FSP session encryption (end-to-end) + + + FMP link encryption (hop-by-hop) + + + Multi-transport architecture — each link encrypted independently, session spans the full path diff --git a/docs/design/fips-bloom-propagation.svg b/docs/design/fips-bloom-propagation.svg new file mode 100644 index 0000000..fe2ea86 --- /dev/null +++ b/docs/design/fips-bloom-propagation.svg @@ -0,0 +1,147 @@ + + + + + + + + Bloom Filter Propagation + Each link carries two filters — one in each direction (split-horizon) + + + + + + + + + + + + + + R + + + B + + + C + + + D + + + E + + + F + + + + + + + + + + B to R + + B D E + + + R to B + + C F R + + + + + C to R + + C F + + + R to C + + B D E R + + + + + D to B + + D + + + B to D + + B C E F R + + + + + E to B + + E + + + B to E + + B C D F R + + + + + F to C + + F + + + C to F + + B C D E R + + + merges D + E + self, sends to R + merges F + self, sends to R + + + + X to Y + + filter X sends to Y — box color matches sender node + + + + Candidate selection + At any node, each peer's filter answers: "can you maybe reach destination X?" + Example: D wants to reach F. D checks the filter from B: B C E F R — F present, so B is a candidate. + + + At steady state, every node knows full network reachability through each of its peers + diff --git a/docs/design/fips-configuration.md b/docs/design/fips-configuration.md index b9792c3..f39ce5e 100644 --- a/docs/design/fips-configuration.md +++ b/docs/design/fips-configuration.md @@ -166,7 +166,7 @@ configurable. ### Link-Layer MMP (`node.mmp.*`) Metrics Measurement Protocol for per-peer link measurement. See -[fips-link-layer.md](fips-link-layer.md) for behavioral details. +[fips-mesh-layer.md](fips-mesh-layer.md) for behavioral details. | Parameter | Type | Default | Description | |-----------|------|---------|-------------| diff --git a/docs/design/fips-coordinate-discovery.svg b/docs/design/fips-coordinate-discovery.svg new file mode 100644 index 0000000..6feee57 --- /dev/null +++ b/docs/design/fips-coordinate-discovery.svg @@ -0,0 +1,156 @@ + + + + + + + + Coordinate Discovery and Caching + LookupRequest/Response warms caches along the path + + + + + + + A + Source + + + + B + Transit + + + + C + Transit + + + + D + Destination + + + + + + + + + + + + Phase 1 + Discovery + + + + + LookupRequest + + + + + LookupRequest + + + + + LookupRequest + + + guided by bloom filters at each hop + + + + + + + + + Phase 2 + Response + + + + + LookupResponse + coords + + + + cache D + + + + + LookupResponse + coords + + + + cache D + + + + + LookupResponse + coords + + + + + + + + + Phase 3 + Routing + + + + + Data + + + cached coords + + + + + Data + + + cached coords + + + + + Data + + + cached coords enable efficient forwarding — no re-discovery needed + + + Each transit node caches coordinates from the LookupResponse return path + diff --git a/docs/design/fips-identity-derivation.svg b/docs/design/fips-identity-derivation.svg index 0e5d53b..6749b57 100644 --- a/docs/design/fips-identity-derivation.svg +++ b/docs/design/fips-identity-derivation.svg @@ -1,4 +1,4 @@ - + - + - FIPS Identity Derivation - From Nostr keypair to protocol identifiers + FIPS Identity Derivation + From Nostr keypair to protocol identifiers @@ -36,8 +36,8 @@ - - + + encode @@ -46,14 +46,13 @@ human-readable form - + Display & configuration User-facing identifiers DNS queries (npub.fips) - - - + + @@ -62,10 +61,10 @@ - - Endpoint authentication - Link & session encryption - Known only to endpoints + + Endpoint authentication + Link & session encryption + Known only to endpoints @@ -86,10 +85,10 @@ - - Packet header addressing - Spanning tree coordinates - Bloom filter entries + + Packet header addressing + Spanning tree coordinates + Bloom filter entries @@ -110,17 +109,17 @@ - - TUN interface (fips0) - Unmodified IP applications - ping, curl, ssh, etc. + + TUN interface (fips0) + Unmodified IP applications + ping, curl, ssh, etc. - - Privacy boundary - Intermediate routers see only - node_addr — never the pubkey. + + Privacy boundary + Intermediate routers see only + node_addr — never the pubkey. - + diff --git a/docs/design/fips-intro.md b/docs/design/fips-intro.md index 7e47027..099e1c3 100644 --- a/docs/design/fips-intro.md +++ b/docs/design/fips-intro.md @@ -14,12 +14,17 @@ as an IPv6 endpoint for compatibility with existing IP-based applications. ## Why FIPS? +**Self-sovereign identity**: FIPS nodes generate their own addresses, node IDs, +and security credentials without coordination with any central authority. The +identity system uses Nostr keypairs (secp256k1), so existing npub/nsec pairs +work directly. + **Infrastructure independence**: The internet depends on centralized infrastructure — ISPs, backbone providers, DNS, certificate authorities. FIPS -works over any transport that can carry packets: a LoRa radio link between -mountain towns, a serial cable between air-gapped systems, onion-routed -connections through Tor, or the existing internet as an overlay. When the -internet is unavailable, unreliable, or untrusted, the mesh still works. +works over any transport that can carry packets: a serial cable between +air-gapped systems, onion-routed connections through Tor, radio links between +remote sites, or the existing internet as an overlay. When the internet is +unavailable, unreliable, or untrusted, the mesh still works. **End-to-end security**: FIPS provides secure, authenticated, and encrypted communication between any two nodes in the mesh, independent of the mix of @@ -33,11 +38,6 @@ exposure is limited to direct peers only. automatically. Connect to one peer and you can reach the entire mesh. The network self-heals around failures and adapts to changing topology. -**Self-sovereign identity**: FIPS nodes generate their own addresses, node IDs, -and security credentials without coordination with any central authority. The -identity system uses Nostr keypairs (secp256k1), so existing npub/nsec pairs -work directly. - ## A Self-Organizing Mesh Traditional networks are built top-down. A central authority assigns addresses, @@ -86,62 +86,16 @@ FIPS is organized in three protocol layers, each with distinct responsibilities and clean service boundaries. Understanding these layers is key to understanding how FIPS works. -```text -┌─────────────────────────────────────────────────────────────┐ -│ Applications │ -│ (native FIPS API / IPv6 adapter) │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ FIPS Session Protocol (FSP) │ -│ End-to-end authenticated encryption between endpoints │ -│ Session lifecycle, coordinate caching, replay protection │ -│ │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ FIPS Link Protocol (FLP) │ -│ Hop-by-hop link encryption, peer authentication │ -│ Spanning tree, bloom filters, routing, forwarding │ -│ │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ Transport Layer │ -│ Datagram delivery over arbitrary media │ -│ UDP, Ethernet, LoRa, Tor, serial, ... │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` +![Protocol Stack](fips-protocol-stack.svg) ### Mapping to Traditional Networking Readers familiar with the OSI model or TCP/IP networking may find it helpful to see how FIPS concepts relate to traditional layers: -```text - Traditional FIPS Key Difference -───────────────────────────────────────────────────────────────────── - Application Applications Same role — user-facing - (IPv6 adapter) software -───────────────────────────────────────────────────────────────────── - Transport (TCP/UDP) (not present) FIPS provides datagrams, - not reliable streams -───────────────────────────────────────────────────────────────────── - Session FSP End-to-end encryption - and session management -───────────────────────────────────────────────────────────────────── - Network (IP) FLP Routing, forwarding, - address resolution — - but self-organizing -───────────────────────────────────────────────────────────────────── - Link (Ethernet/WiFi) FLP (link encryption) Peer authentication - and hop-by-hop crypto -───────────────────────────────────────────────────────────────────── - Physical (PHY) Transport layer Abstracted — FIPS - (UDP, radio, serial) treats all media the - same way -───────────────────────────────────────────────────────────────────── -``` +![OSI Mapping](fips-osi-mapping.svg) -Note that FLP spans what would traditionally be separate link and network +Note that FMP spans what would traditionally be separate link and network layers. This is intentional — in a self-organizing mesh, the same layer that authenticates peers also makes routing decisions, because routing depends on authenticated peer state (spanning tree positions, bloom filters). @@ -152,27 +106,28 @@ authenticated peer state (spanning tree positions, bloom filters). medium. Each transport type (UDP socket, Ethernet interface, radio modem) implements the same abstract interface: send and receive datagrams, report MTU. The transport layer knows nothing about FIPS identities, routing, or encryption. -It provides raw datagram delivery to FLP above. +It provides raw datagram delivery to FMP above. See [fips-transport-layer.md](fips-transport-layer.md) for the transport layer specification. -**FIPS Link Protocol (FLP)**: Manages peer connections, authenticates peers via -Noise IK handshakes, and encrypts all traffic on each link. FLP is where the +**FIPS Mesh Protocol (FMP)**: Manages peer connections, authenticates peers via +Noise IK handshakes, and encrypts all traffic on each link. FMP is where the mesh organizes itself — nodes exchange spanning tree announcements and bloom -filters with their direct peers, and FLP makes forwarding decisions for transit -traffic. FLP provides authenticated, encrypted forwarding to FSP above. +filters with their direct peers, and FMP makes forwarding decisions for transit +traffic. FMP provides authenticated, encrypted forwarding to FSP above. -See [fips-link-layer.md](fips-link-layer.md) for the FLP specification and -[fips-mesh-operation.md](fips-mesh-operation.md) for how FLP's routing and +See [fips-mesh-layer.md](fips-mesh-layer.md) for the FMP specification and +[fips-mesh-operation.md](fips-mesh-operation.md) for how FMP's routing and self-organization work in practice. **FIPS Session Protocol (FSP)**: Provides end-to-end authenticated encryption between any two nodes, regardless of how many intermediate hops separate them. FSP manages session lifecycle (setup, data transfer, teardown), caches destination coordinates for efficient routing, and handles the warmup strategy -that keeps transit node caches populated. FSP provides a datagram service to -applications above. +that keeps transit node caches populated. Session dispatch uses index-based +routing inspired by [WireGuard](https://www.wireguard.com/), enabling O(1) +packet demultiplexing. FSP provides a datagram service to applications above. See [fips-session-layer.md](fips-session-layer.md) for the FSP specification. @@ -187,48 +142,38 @@ See [fips-ipv6-adapter.md](fips-ipv6-adapter.md) for the IPv6 adapter. ## Architecture Overview -![Architecture Overview](fips-architecture-overview.svg) +Each node is a self-contained protocol stack with a strict layered architecture. +No layer depends on the specifics of the layers above or below it — transport +plugins know nothing about sessions, the routing layer knows nothing about +application addressing, and applications know nothing about which physical +media carry their traffic. This separation means new transports, protocol +features, and application interfaces can be added independently. -Each link uses a different transport, but the end-to-end session encryption is -independent of the transport mix. Intermediate nodes decrypt the link layer to -make routing decisions, then re-encrypt for the next hop. They cannot read the -session-layer payload. - -```text - Application ──────────── End-to-end FSP session ──────────── Application - │ │ - ▼ ▼ - ┌─────────┐ FLP link ┌─────────┐ FLP link ┌─────────┐ - │ Node A │◄──────────────►│ Node B │◄──────────────►│ Node C │ - └────┬────┘ (Noise IK) └────┬────┘ (Noise IK) └────┬────┘ - │ │ │ - UDP/IP Ethernet LoRa - transport transport transport -``` - -Each FLP link operates over its own transport type, with independent link-layer -encryption. The FSP session spans the entire path, providing end-to-end -confidentiality that is independent of the transport mix along the route. +Two application interfaces sit at the top of the stack: a native datagram API +addressed by npub, and an IPv6 TUN adapter that maps npubs to `fd::/8` +addresses so unmodified IP applications can use the network transparently. Below +them, FSP manages end-to-end encrypted sessions while FMP handles mesh routing, +peer authentication, and hop-by-hop link encryption. At the bottom, transport +plugins abstract the physical diversity — each implements the same interface, so +the router treats UDP, Ethernet, Tor, and serial links identically. ![Node Architecture](fips-node-architecture.svg) -Internally, each node is organized in the three protocol layers. At the top, -two application interfaces provide access to the mesh: a native datagram API -addressed by npub, and an IPv6 TUN adapter that maps npubs to `fd::/8` -addresses so unmodified IP applications can use the network transparently. The -FSP and FLP layers in the middle implement session management, routing, and -encryption. At the bottom, transport plugins handle the physical diversity — -each plugin implements the same interface, so the router treats UDP, Ethernet, -LoRa, Tor, and serial links identically. Adding a new transport requires no -changes to the routing or session layers. +The mesh routes application traffic across heterogeneous transports +transparently. A packet may traverse WiFi, Ethernet, UDP/IP, and Tor links on +its way from source to destination — the application never needs to know which +transports are involved. Each hop is independently encrypted at the link layer, +while a single end-to-end session protects the payload across the entire path. + +![Architecture Overview](fips-architecture-overview.svg) --- ## Identity System -FIPS uses Nostr keypairs (secp256k1) as node identities. The public key -identifies the node; the private key signs protocol messages and establishes -encrypted sessions. +FIPS uses [Nostr](https://github.com/nostr-protocol/nips) keypairs (secp256k1) +as node identities. The public key identifies the node; the private key signs +protocol messages and establishes encrypted sessions. The FIPS address (synonymous with the pubkey) is the primary means for application-layer software to identify communication endpoints. The @@ -238,7 +183,7 @@ native API to the FIPS node software, or through an IPv6 adaptation layer that converts the node identity into an IPv6 address and provides DNS resolution from npub to this address for traditional software. -### Node Address Derivation +### FIPS Identity Handling ![Identity Derivation](fips-identity-derivation.svg) @@ -250,44 +195,23 @@ Intermediate routers see only node_addrs — they can forward traffic without learning the Nostr identities of the endpoints. An observer can verify "does this node_addr belong to pubkey X?" but cannot enumerate which pubkeys are communicating by inspecting traffic. The IPv6 address prepends `fd` to the -first 15 bytes of the node_addr, providing an overlay address for unmodified +first 15 bytes of the node_addr, providing a ULA overlay address for unmodified IP applications via the TUN interface. -### Address Format - -When using the IPv6 adaptation layer, FIPS addresses use the IPv6 Unique Local -Address (ULA) prefix `fd00::/8`, providing 120 bits from the node_addr hash. -These are overlay identifiers — they appear in the TUN interface for application -compatibility but are not routable on the underlying transport. The fd prefix -ensures no collision with addresses that may be in use on the transport network. +Below the FIPS identity layer, each transport uses its own native addressing — +IP:port tuples, MAC addresses, .onion identifiers. These **link addresses** are +opaque to everything above FMP and discarded once link authentication completes. ### Identity Verification -The Noise Protocol Framework is used to mutually authenticate both peer-to-peer -link connections (at FLP) and end-to-end session traffic (at FSP), proving each +The Noise Protocol Framework mutually authenticates both peer-to-peer link +connections (at FMP) and end-to-end session traffic (at FSP), proving each party controls the private key for their claimed identity. -See [fips-link-layer.md](fips-link-layer.md) for peer authentication and +See [fips-mesh-layer.md](fips-mesh-layer.md) for peer authentication and [fips-session-layer.md](fips-session-layer.md) for end-to-end session establishment. -### Terminology: Addresses and Identifiers - -FIPS uses several related but distinct identifiers at different protocol layers: - -| Term | Layer | Visible To | Description | -| ---- | ----- | ---------- | ----------- | -| **FIPS address / pubkey** | Application/FSP | Endpoints only | 32-byte secp256k1 public key — the endpoint identity | -| **npub** | (encoding) | Human readers | Bech32 encoding of pubkey for display/config | -| **node_addr** | FLP (routing) | Routing nodes | SHA-256(pubkey) truncated to 128 bits — cannot be reversed to pubkey | -| **link_addr** | Transport | Direct peers | IP:port, MAC, .onion — transport-specific | -| **IPv6 address** | IPv6 adapter | Applications | fd::/8 derived from node_addr — optional compatibility | - -**Privacy property**: The pubkey (FIPS address / Nostr identity) is never -exposed to intermediate routing nodes. They see only the node_addr, a one-way -hash. An observer can verify "does this node_addr belong to pubkey X?" but -cannot derive the pubkey from traffic. - --- ## Two-Layer Encryption @@ -296,14 +220,14 @@ FIPS uses independent encryption at two protocol layers: | Layer | Scope | Pattern | Purpose | | ----- | ----- | ------- | ------- | -| **FLP (Link)** | Hop-by-hop | Noise IK | Encrypt all traffic on each peer link | +| **FMP (Mesh)** | Hop-by-hop | Noise IK | Encrypt all traffic on each peer link | | **FSP (Session)** | End-to-end | Noise IK | Encrypt application payload between endpoints | ### Link Layer (Hop-by-Hop) -When two nodes establish a direct connection, they perform a Noise IK -handshake. This authenticates both parties and establishes symmetric keys for -encrypting all traffic on that link. Every packet between direct peers is +When two nodes establish a direct connection, they perform a +[Noise IK](https://noiseprotocol.org/) handshake. This authenticates both +parties and establishes symmetric keys for encrypting all traffic on that link. Every packet between direct peers is encrypted — gossip messages, routing queries, and forwarded session datagrams alike. @@ -331,20 +255,20 @@ twice: once by the session layer (end-to-end) and once by the link layer A packet from A to adjacent peer B: 1. A encrypts payload with A↔B session key (FSP) -2. A wraps in SessionDatagram, encrypts with A↔B link key (FLP), sends to B +2. A wraps in SessionDatagram, encrypts with A↔B link key (FMP), sends to B 3. B decrypts link layer, then decrypts session layer to get payload A packet from A to D through intermediate node B: 1. A encrypts payload with A↔D session key (FSP) -2. A wraps in SessionDatagram, encrypts with A↔B link key (FLP), sends to B +2. A wraps in SessionDatagram, encrypts with A↔B link key (FMP), sends to B 3. B decrypts link layer, reads destination, re-encrypts with B↔D link key 4. D decrypts link layer, then decrypts session layer to get payload Intermediate nodes can route based on destination node_addr but cannot read session-layer payloads. -See [fips-link-layer.md](fips-link-layer.md) for link encryption and +See [fips-mesh-layer.md](fips-mesh-layer.md) for link encryption and [fips-session-layer.md](fips-session-layer.md) for session encryption. --- @@ -363,7 +287,9 @@ mechanisms provide the information each node needs. Nodes self-organize into a spanning tree rooted at a deterministically-elected node (the one with the smallest node_addr). Each node selects a single parent from among its direct peers, and the resulting tree gives every node a -**coordinate** — its path from itself to the root. +**coordinate** — its path from itself to the root. This coordinate-based +approach is adapted from [Yggdrasil](https://yggdrasil-network.github.io/)'s +[Ironwood](https://github.com/Arceliar/ironwood) routing library. These coordinates enable distance calculations between any two nodes: the distance is the number of hops from each node to their lowest common ancestor @@ -382,10 +308,13 @@ walkthroughs. ### Bloom Filters: Candidate Selection -Each node maintains bloom filters summarizing which destinations are reachable -through each of its peers. Bloom filters propagate via gossip, with each node -computing outbound filters by merging the filters received from its other -peers. At steady state, filters represent the entire reachable network. +Each node maintains [bloom filters](https://en.wikipedia.org/wiki/Bloom_filter) +summarizing which destinations are reachable through each of its peers. Bloom +filters propagate via gossip, with each node computing outbound filters by +merging the filters received from its other peers (a +[split-horizon](https://en.wikipedia.org/wiki/Split_horizon_route_advertisement) +technique borrowed from distance-vector routing). At steady state, filters +represent the entire reachable network. Bloom filters answer a single question: "can peer P possibly reach destination D?" The answer is either "no" (definitive) or "maybe" (probabilistic — false @@ -396,17 +325,35 @@ decision requires tree coordinates to rank those candidates by distance. See [fips-bloom-filters.md](fips-bloom-filters.md) for filter parameters and mathematical properties. +![Bloom filter propagation on a spanning tree](fips-bloom-propagation.svg) + +Every filter is computed identically regardless of link type: the outbound filter +for peer Q merges this node's identity with all inbound filters except Q's +(split-horizon exclusion). The protocol makes no distinction between tree parents, +tree children, or mesh peers — the asymmetry visible in the diagram is a +consequence of tree topology, not a different operation. + +A node with multiple peers receives genuinely different filters from each. In the +diagram, R receives {B, D, E} from B and {C, F} from C — two disjoint subtrees. +When R needs to reach F, only C's filter matches. This is where bloom filters +provide real candidate selection: a node with several peers can narrow the +forwarding choice before consulting tree coordinates. Leaf nodes like D have only +one peer, so their single inbound filter is necessarily near-complete (everything +except themselves) and offers no selection — but leaf nodes have no choice to make +anyway. + ### Routing Decisions -At each hop, FLP makes a local forwarding decision using the following priority +At each hop, FMP makes a local forwarding decision using the following priority chain: 1. **Local delivery** — the destination is this node 2. **Direct peer** — the destination is an authenticated neighbor 3. **Bloom-guided candidate selection** — bloom filters identify peers that can reach the destination; tree coordinates rank them by distance -4. **Greedy tree routing** — fallback when bloom filters haven't converged; - forward to the peer that minimizes tree distance to the destination +4. **[Greedy routing](https://en.wikipedia.org/wiki/Greedy_embedding)** — + fallback when bloom filters haven't converged; forward to the peer that + minimizes tree distance to the destination 5. **No route** — destination unreachable; send error signal to source All multi-hop routing depends on knowing the destination's tree coordinates. @@ -414,17 +361,23 @@ These are cached at each node after being learned through discovery (LookupRequest/LookupResponse) or session establishment (SessionSetup). The coordinate cache is the critical piece that enables efficient forwarding. +![Per-hop routing decision flowchart](fips-routing-decision.svg) + ### Coordinate Caching and Discovery When a node first needs to reach an unknown destination, it sends a -LookupRequest that floods through the network guided by bloom filters. The -destination responds with its coordinates, which the source caches. Subsequent -traffic routes efficiently using the cached coordinates. +LookupRequest that propagates through the network guided by bloom filters and +loop prevention. The +destination responds with its coordinates, which the source and intermediate +nodes along the return path cache. Subsequent traffic routes efficiently using +the cached coordinates. Session establishment (SessionSetup) also carries coordinates, warming transit node caches along the path so that data packets can be forwarded without individual discovery at each hop. +![Coordinate discovery and cache warming sequence](fips-coordinate-discovery.svg) + ### Error Recovery When routing fails — because cached coordinates are stale or a path has @@ -446,13 +399,13 @@ and mesh behavior description. ## Transport Abstraction FIPS is transport-agnostic. The protocol operates identically whether peers -connect over UDP, Ethernet, LoRa radio, serial cables, or Tor hidden services. +connect over UDP, Bluetooth, or whatever transport is available. A **transport** is a physical or logical interface: a UDP socket, an Ethernet NIC, a Tor client, a radio modem. A **link** is a peer connection established over a transport. Transport addresses (IP:port, MAC address, .onion) are opaque -to all layers above FLP — they are used only to deliver datagrams and are -discarded once FLP has authenticated the peer. +to all layers above FMP — they are used only to deliver datagrams and are +discarded once FMP has authenticated the peer. A node with multiple transports automatically bridges between networks. Peers from all transports feed into a single spanning tree; the router selects the @@ -461,10 +414,9 @@ automatically routes through alternatives. | Category | Examples | Characteristics | | -------- | -------- | --------------- | -| Overlay | UDP/IP, TCP/TLS, WebSocket | Internet connectivity, NAT traversal | -| Shared medium | Ethernet, WiFi, Bluetooth, LoRa | Local discovery, broadcast | -| Point-to-point | Serial, dialup | Static config, no discovery | -| Anonymity | Tor, I2P | High latency, strong privacy | +| Overlay | UDP/IP, Tor | Internet connectivity, NAT traversal | +| Shared medium | Ethernet, WiFi, Bluetooth, Radio | Local discovery, broadcast | +| Point-to-point | Serial | Static config, no discovery | > **Implementation status**: UDP/IP is the only implemented transport. All > others are future directions. @@ -565,8 +517,8 @@ approach, enabling O(1) packet routing without relying on source addresses. | Document | Description | | -------- | ----------- | -| [fips-transport-layer.md](fips-transport-layer.md) | Transport layer: abstraction, types, services provided to FLP | -| [fips-link-layer.md](fips-link-layer.md) | FLP: peer authentication, link encryption, forwarding | +| [fips-transport-layer.md](fips-transport-layer.md) | Transport layer: abstraction, types, services provided to FMP | +| [fips-mesh-layer.md](fips-mesh-layer.md) | FMP: peer authentication, link encryption, forwarding | | [fips-session-layer.md](fips-session-layer.md) | FSP: end-to-end encryption, session lifecycle | | [fips-ipv6-adapter.md](fips-ipv6-adapter.md) | IPv6 adaptation: DNS, TUN interface, MTU enforcement | diff --git a/docs/design/fips-ipv6-adapter.md b/docs/design/fips-ipv6-adapter.md index f3d50ad..79f4b8b 100644 --- a/docs/design/fips-ipv6-adapter.md +++ b/docs/design/fips-ipv6-adapter.md @@ -155,7 +155,7 @@ transport path MTU for the IPv6 adapter is therefore: 1280 + 106 = 1386 bytes ``` -Transports with smaller MTUs (LoRa at ~250 bytes, serial at 256 bytes) cannot +Transports with smaller MTUs (radio at ~250 bytes, serial at 256 bytes) cannot support the IPv6 adapter — applications on those transports must use the native FIPS datagram API. @@ -227,7 +227,7 @@ The TUN reader receives raw IPv6 packets from applications and processes them: 4. Retrieve NodeAddr and PublicKey from cache 5. Look up or establish FSP session 6. Encrypt payload with session keys -7. Route through FLP toward destination +7. Route through FMP toward destination ### Writer Thread @@ -295,7 +295,7 @@ TUN device creation requires `CAP_NET_ADMIN`. Options: Two complementary mechanisms support full PMTUD: 1. **Proactive**: The `path_mtu` field (2 bytes) in the SessionDatagram envelope - is implemented at the FLP level. The source sets it to its outbound link MTU + is implemented at the FMP level. The source sets it to its outbound link MTU minus overhead; each transit node applies `min(current, own_outbound_mtu - overhead)`. The destination receives the forward-path minimum. PathMtuNotification is handled at the session layer; diff --git a/docs/design/fips-link-layer.md b/docs/design/fips-mesh-layer.md similarity index 91% rename from docs/design/fips-link-layer.md rename to docs/design/fips-mesh-layer.md index bdcbf45..9df825b 100644 --- a/docs/design/fips-link-layer.md +++ b/docs/design/fips-mesh-layer.md @@ -1,49 +1,49 @@ -# FIPS Link Protocol (FLP) +# FIPS Mesh Protocol (FMP) -The FIPS Link Protocol is the middle layer of the FIPS protocol stack. It sits +The FIPS Mesh Protocol is the middle layer of the FIPS protocol stack. It sits between the transport layer below and the FIPS Session Protocol (FSP) above. -FLP is where anonymous transport addresses become authenticated peers, where +FMP is where anonymous transport addresses become authenticated peers, where the mesh self-organizes, and where forwarding decisions are made. ## Role -FLP manages direct peer connections over transports. When a transport delivers -a datagram from an unknown address, FLP authenticates the sender through a +FMP manages direct peer connections over transports. When a transport delivers +a datagram from an unknown address, FMP authenticates the sender through a Noise IK handshake, establishing a cryptographic link. Once authenticated, the link carries all inter-peer communication: spanning tree gossip, bloom filter updates, coordinate discovery, and forwarded session datagrams — all encrypted per-hop. -FLP is the boundary between opaque transport addresses and identified peers. -Below FLP, everything is transport-specific addresses (IP:port, MAC, .onion). -Above FLP, everything is peers identified by public keys and routable by +FMP is the boundary between opaque transport addresses and identified peers. +Below FMP, everything is transport-specific addresses (IP:port, MAC, .onion). +Above FMP, everything is peers identified by public keys and routable by node_addr. The transport layer never sees FIPS-level structure; FSP never sees transport addresses or routing details. ## Services Provided to FSP -From the session layer's perspective, FLP is a black box providing three +From the session layer's perspective, FMP is a black box providing three services. FSP knows nothing about transports, links, peers, spanning trees, coordinates, bloom filters, hop counts, or network topology. ### Datagram Forwarding -FLP accepts a datagram addressed by source and destination node_addr and +FMP accepts a datagram addressed by source and destination node_addr and delivers it best-effort toward the destination. The datagram travels hop by -hop — at each node, FLP decrypts the link layer, reads the destination +hop — at each node, FMP decrypts the link layer, reads the destination node_addr, makes a local forwarding decision, and re-encrypts onto the next-hop link. FSP provides: source node_addr, destination node_addr, hop limit, and an opaque payload (the session-layer encrypted message). -FLP provides: best-effort delivery. No acknowledgment, no retransmission, no +FMP provides: best-effort delivery. No acknowledgment, no retransmission, no ordering guarantee. Datagrams may be dropped, duplicated, or delivered out of order. ### Error Signaling -When forwarding fails, FLP signals the source endpoint asynchronously: +When forwarding fails, FMP signals the source endpoint asynchronously: - **CoordsRequired**: A transit node lacks the destination's tree coordinates and cannot make a forwarding decision. The source should re-initiate @@ -60,21 +60,21 @@ storms during topology changes. ### Local Delivery When a datagram arrives with a destination node_addr matching the local node, -FLP delivers it up to FSP for session-layer processing. +FMP delivers it up to FSP for session-layer processing. ## Services Required from Transport Layer -FLP requires the following from each transport: +FMP requires the following from each transport: ### Datagram Delivery Send and receive raw datagrams to/from transport addresses. The transport -handles all medium-specific details. FLP sees only "send bytes to address" and +handles all medium-specific details. FMP sees only "send bytes to address" and "bytes arrived from address." ### MTU Reporting -The maximum datagram size for a given link. FLP needs this to determine how +The maximum datagram size for a given link. FMP needs this to determine how much payload fits in a single packet after link encryption overhead (37 bytes for the encrypted frame wrapper: 16-byte outer header + 5-byte inner header + 16-byte AEAD tag). @@ -82,13 +82,13 @@ for the encrypted frame wrapper: 16-byte outer header + 5-byte inner header + ### Connection Lifecycle For connection-oriented transports, the transport must establish the underlying -connection before FLP can begin the Noise IK handshake. For connectionless +connection before FMP can begin the Noise IK handshake. For connectionless transports, datagrams can flow immediately. ### Endpoint Discovery (Optional) When a transport discovers a FIPS-capable endpoint (via beacon, query, or -other transport-specific mechanism), it notifies FLP so that link setup can +other transport-specific mechanism), it notifies FMP so that link setup can be initiated. Transports without discovery support provide peer addresses through configuration. @@ -124,14 +124,14 @@ handshake completion: ### Reconnection When a Noise IK msg1 arrives from a peer that already has an authenticated -link, FLP accepts the new handshake alongside the existing session. If the new +link, FMP accepts the new handshake alongside the existing session. If the new handshake completes successfully, it replaces the old session. This handles legitimate reconnection (network change, process restart, NAT rebinding) without disrupting ongoing traffic until the new session is confirmed. ### Auto-Reconnect -When MMP's liveness detection removes a peer (dead timeout exceeded), FLP +When MMP's liveness detection removes a peer (dead timeout exceeded), FMP automatically re-initiates the connection if the peer is configured for it. The auto-reconnect path: @@ -256,7 +256,7 @@ authenticity. When an encrypted packet successfully decrypts, the sender is the authenticated peer regardless of what transport address the packet arrived -from. FLP updates the peer's current address to the packet's source address, +from. FMP updates the peer's current address to the packet's source address, and subsequent outbound packets use the updated address. This allows peers to change transport addresses (IP:port for UDP, connection @@ -294,7 +294,7 @@ Handshake initiation (msg1) is the primary attack surface for unauthenticated traffic. Each msg1 requires Noise DH operations (~200µs on modern CPUs), state allocation, and response generation. -FLP uses a global token bucket rate limiter: +FMP uses a global token bucket rate limiter: - **Burst capacity**: Handles legitimate connection storms (e.g., node restart with many configured peers) - **Sustained rate**: Limits steady-state new connections per second @@ -310,13 +310,13 @@ Additional protections: ## Disconnect -FLP supports orderly link teardown via a Disconnect message carrying a reason +FMP supports orderly link teardown via a Disconnect message carrying a reason code (shutdown, restart, protocol error, transport failure, resource exhaustion, security violation, configuration change, timeout). -On receiving Disconnect, FLP immediately cleans up state: removes the peer +On receiving Disconnect, FMP immediately cleans up state: removes the peer from the peer table, frees the session index, removes the link, and cleans up -address mappings. If the departed peer was the tree parent, FLP triggers parent +address mappings. If the departed peer was the tree parent, FMP triggers parent reselection. Disconnect is best-effort — if the transport is broken, the message won't @@ -328,7 +328,7 @@ stopped. ## Liveness Detection -FLP detects link liveness through a combination of explicit heartbeats and +FMP detects link liveness through a combination of explicit heartbeats and traffic observation. ### Heartbeat @@ -357,7 +357,7 @@ event-driven, and MMP reports require at least one side running Full mode). ## Link Message Types -FLP defines eight message types carried inside encrypted frames: +FMP defines eight message types carried inside encrypted frames: | Type | Name | Purpose | | ---- | ---- | ------- | @@ -392,7 +392,7 @@ routing layer for link-cost decisions. ### Metrics Tracked MMP computes the following metrics from the per-frame counter and timestamp -fields in the FLP wire format: +fields in the FMP wire format: - **SRTT** — Smoothed round-trip time (Jacobson/RFC 6298, α=1/8). Derived from timestamp-echo in ReceiverReports with dwell-time compensation. @@ -426,7 +426,7 @@ formula is `clamp(2 × SRTT, 100ms, 2000ms)`. ### Spin Bit and RTT -The SP (spin bit) flag in the FLP inner header follows the QUIC spin bit +The SP (spin bit) flag in the FMP inner header follows the QUIC spin bit pattern: reflected on receive, toggled on send when the reflected value matches the last sent value. The spin bit state machine runs for TX reflection, but **RTT samples from the spin bit are discarded**. In a mesh @@ -437,7 +437,7 @@ bit RTT measurements unpredictably. Timestamp-echo from ReceiverReports ### CE Echo -The CE (Congestion Experienced) echo flag (bit 1 in the FLP flags byte) is +The CE (Congestion Experienced) echo flag (bit 1 in the FMP flags byte) is reserved for ECN signaling. The transport trait does not currently expose ECN marking, so the CE echo flag is never set. One-way delay trend serves as the sole pre-loss congestion indicator. @@ -515,8 +515,8 @@ an attacker sends invalid packets to elicit responses. ## References - [fips-intro.md](fips-intro.md) — Protocol overview and architecture -- [fips-transport-layer.md](fips-transport-layer.md) — Transport layer (below FLP) -- [fips-session-layer.md](fips-session-layer.md) — FSP (above FLP) -- [fips-mesh-operation.md](fips-mesh-operation.md) — How FLP's routing and +- [fips-transport-layer.md](fips-transport-layer.md) — Transport layer (below FMP) +- [fips-session-layer.md](fips-session-layer.md) — FSP (above FMP) +- [fips-mesh-operation.md](fips-mesh-operation.md) — How FMP's routing and self-organization work in practice - [fips-wire-formats.md](fips-wire-formats.md) — Byte-level wire format reference diff --git a/docs/design/fips-mesh-operation.md b/docs/design/fips-mesh-operation.md index fb7b9d4..cef1c33 100644 --- a/docs/design/fips-mesh-operation.md +++ b/docs/design/fips-mesh-operation.md @@ -136,7 +136,7 @@ FPR calculations, and size class folding. ## Routing Decision Process -At each hop, FLP makes a local forwarding decision using the `find_next_hop()` +At each hop, FMP makes a local forwarding decision using the `find_next_hop()` priority chain. This is the core routing algorithm. ### Priority Chain @@ -585,7 +585,7 @@ recovery). ## References - [fips-intro.md](fips-intro.md) — Protocol overview -- [fips-link-layer.md](fips-link-layer.md) — FLP specification +- [fips-mesh-layer.md](fips-mesh-layer.md) — FMP specification - [fips-spanning-tree.md](fips-spanning-tree.md) — Tree algorithms and data structures - [fips-bloom-filters.md](fips-bloom-filters.md) — Filter parameters and math diff --git a/docs/design/fips-node-architecture.svg b/docs/design/fips-node-architecture.svg index e843ba6..e5b794e 100644 --- a/docs/design/fips-node-architecture.svg +++ b/docs/design/fips-node-architecture.svg @@ -1,10 +1,11 @@ - + - + FIPS Node Architecture - Application interfaces, router core, and transport abstraction layer + Application interfaces, protocol layers, and transport abstraction - + FIPS Node - - - - - + FIPS-Native API @@ -53,122 +50,111 @@ - - - Router Core - Spanning tree · Bloom filters · Greedy routing · Session management · Noise IK + + + FIPS Session Protocol (FSP) + End-to-end encryption · Session lifecycle · Path discovery · In-band metrics - + - + + + FIPS Mesh Protocol (FMP) + Link encryption · Spanning tree · Bloom filters · Routing · Peer management - - + + + + + + - + - - - - + + + - - Overlay + + Overlay - - UDP - IP + + UDP + IP - - QUIC - IP - - - WS - TCP + + Tor + .onion - - Shared Medium + + Shared Medium - - Ether - 802.3 + + Ether + 802.3 - - WiFi - 802.11 + + WiFi + 802.11 - - BT - RFCOMM + + BT + RFCOMM - - LoRa - radio + + Radio + Sat, ... - - P-to-P + + Point-to-Point - - Serial - UART + + Serial + UART - - - Anonymity - - - Tor - .onion - - - I2P - tunnel + + ... + + Internet / Overlay Peers + - - Internet Peers - + Local / Radio Peers + - - Local / Radio Peers - - - - Wired Peer - - - - Anonymous Peers - + Wired Peers + - + - - Application interface + + Application interface - - IPv6 compatibility layer + + IPv6 compatibility layer - - Router core (protocol engine) + + FSP — end-to-end session encryption - - Transport plugin + + FMP — mesh routing and link encryption - - Transport category grouping + + Transport plugin - All transports use the same Router Core interface + + Transport category + + All transports use the same FMP protocol diff --git a/docs/design/fips-osi-mapping.svg b/docs/design/fips-osi-mapping.svg new file mode 100644 index 0000000..4ef5af2 --- /dev/null +++ b/docs/design/fips-osi-mapping.svg @@ -0,0 +1,64 @@ + + + + + + + + Traditional + FIPS + Key Difference + + + + Application + Application + Same role + + + + Transport + (not present) + Datagrams, not streams + + + + Session + FIPS Session Protocol + End-to-end encryption + (FSP) + and session management + + + + Network (IP) + FIPS Mesh Protocol + Self-organizing routing + (FMP) + and forwarding + + + + Link + FMP (link encryption) + Hop-by-hop crypto + + + + Physical + Transport layer + Abstracted — all media + (UDP, radio, serial) + treated the same + + + Mapping FIPS protocol layers to the traditional networking model + diff --git a/docs/design/fips-protocol-stack.svg b/docs/design/fips-protocol-stack.svg new file mode 100644 index 0000000..ad20d4b --- /dev/null +++ b/docs/design/fips-protocol-stack.svg @@ -0,0 +1,49 @@ + + + + + + + + + Application Layer Interface + Native FIPS API — for FIPS-aware applications + IPv6 Shim — for traditional IP application backward compatibility + + + + FIPS Session Protocol (FSP) + End-to-end authenticated encryption between endpoints + Session lifecycle, path discovery, in-band metrics + Replay protection, forward secrecy, identity privacy + end-to-end + + + + FIPS Mesh Protocol (FMP) + Hop-by-hop peer authentication, link encryption, liveness detection + Spanning tree, bloom filters, routing, forwarding, repair + Link quality monitoring, maintenance, optional discovery + hop-by-hop + + + + Transport Layer + (overlay, shared medium, point-to-point) + Datagram delivery over arbitrary media + UDP, Ethernet, WiFi, Bluetooth, Tor, serial, ... + + + FIPS protocol layer stack — three layers with clean service boundaries + diff --git a/docs/design/fips-routing-decision.svg b/docs/design/fips-routing-decision.svg new file mode 100644 index 0000000..ca094fa --- /dev/null +++ b/docs/design/fips-routing-decision.svg @@ -0,0 +1,153 @@ + + + + + + + + + + + + + + Routing Decision Chain + Per-hop forwarding priority at each FMP router + + + + + + Packet arrives + + + + + + + + 1 + + Local + delivery? + + + + Yes + + Deliver to application + + + + No + + + + + 2 + + Direct + peer? + + + + Yes + + Forward to peer + + + + No + + + + + 3 + + Bloom filter + hit? + + + + Yes + + Rank candidates by + tree distance and + link performance + + + + + Forward to 'best' + + + + No + + + + + 4 + + Coords + known? + + + + Yes + + Greedy tree forward + + + + No + + + + + 5 + + No route → error signal + + + + + + + + Start / entry point + + + Routing decision (checked in priority order) + + + Forwarding action (packet delivered or sent) + + + Intermediate processing step + + + Terminal error (no route available) + + + Control flow direction + + + Each hop evaluates destinations in priority order 1–4, falling through on miss + diff --git a/docs/design/fips-session-layer.md b/docs/design/fips-session-layer.md index ddcbc80..b7ba536 100644 --- a/docs/design/fips-session-layer.md +++ b/docs/design/fips-session-layer.md @@ -1,7 +1,7 @@ # FIPS Session Protocol (FSP) The FIPS Session Protocol is the top protocol layer in the FIPS stack. It sits -above the FIPS Link Protocol (FLP) and below applications (native FIPS API or +above the FIPS Mesh Protocol (FMP) and below applications (native FIPS API or IPv6 adapter). FSP provides end-to-end authenticated, encrypted datagram delivery between any two FIPS nodes, regardless of how many intermediate hops separate them. @@ -34,7 +34,7 @@ Applications access the FIPS mesh through two interfaces, both served by FSP: Applications address destinations directly by npub or public key. The FIPS stack resolves the destination's node_addr, establishes or reuses a session, -encrypts the payload, and routes through FLP. No DNS involvement. +encrypts the payload, and routes through FMP. No DNS involvement. ### IPv6 Adapter @@ -66,21 +66,21 @@ layer. TCP over IPv6 get TCP's congestion control; native API applications must manage their own sending rate. -## Services Required from FLP +## Services Required from FMP -FSP treats FLP as a black box providing three services. FSP knows nothing about +FSP treats FMP as a black box providing three services. FSP knows nothing about transports, transport addresses, links, peers, spanning trees, coordinates, bloom filters, hop counts, or network topology. ### SessionDatagram Forwarding -FLP accepts a SessionDatagram (source node_addr, destination node_addr, TTL, +FMP accepts a SessionDatagram (source node_addr, destination node_addr, TTL, path MTU, payload) and delivers it best-effort toward the destination. Delivery may traverse multiple hops, each with independent link encryption. ### Error Signaling -FLP signals routing failures asynchronously: +FMP signals routing failures asynchronously: - **CoordsRequired**: A transit node lacks the destination's tree coordinates. FSP responds by sending a standalone CoordsWarmup (0x14) message @@ -97,7 +97,7 @@ end-to-end encrypted) because transit nodes have no session with the source. ### Local Delivery When a SessionDatagram arrives with a destination node_addr matching the local -node, FLP delivers it to FSP for session-layer processing. +node, FMP delivers it to FSP for session-layer processing. ## Session Lifecycle @@ -189,7 +189,7 @@ transport addresses or routing paths. A session survives: ### Noise IK Pattern -FSP uses the same Noise IK pattern as FLP link encryption, but with +FSP uses the same Noise IK pattern as FMP link encryption, but with independent keys and sessions. The full Noise descriptor is `Noise_IK_secp256k1_ChaChaPoly_SHA256`. @@ -386,7 +386,7 @@ Cache population mechanisms: The coordinate cache maps `NodeAddr → TreeCoordinate` and is the critical data structure that enables efficient multi-hop routing. Without cached -coordinates for a destination, FLP cannot make forwarding decisions and must +coordinates for a destination, FMP cannot make forwarding decisions and must either fall back to bloom-filter-only routing or signal CoordsRequired. ### Unified Cache @@ -506,13 +506,13 @@ MMP session metrics session=npub1tdwa...84le rtt=4.3ms loss=0.6% jitter=0.2ms go | Simultaneous initiation tie-breaker | **Implemented** | | Flush coord cache on parent change | **Implemented** | | Rekey | Planned | -| Path MTU tracking (FLP SessionDatagram field) | **Implemented** | +| Path MTU tracking (FMP SessionDatagram field) | **Implemented** | | Path MTU notification (end-to-end echo) | **Implemented** | ## References - [fips-intro.md](fips-intro.md) — Protocol overview and architecture -- [fips-link-layer.md](fips-link-layer.md) — FLP specification (below FSP) +- [fips-mesh-layer.md](fips-mesh-layer.md) — FMP specification (below FSP) - [fips-ipv6-adapter.md](fips-ipv6-adapter.md) — IPv6 adaptation layer (above FSP) - [fips-mesh-operation.md](fips-mesh-operation.md) — Routing, discovery, and error recovery diff --git a/docs/design/fips-software-architecture.md b/docs/design/fips-software-architecture.md index 5b0a477..dbfe31a 100644 --- a/docs/design/fips-software-architecture.md +++ b/docs/design/fips-software-architecture.md @@ -93,7 +93,7 @@ FIPS uses independent Noise IK encryption at two layers: | Layer | Scope | What It Protects | | ----- | ----- | ---------------- | -| FLP (link) | Hop-by-hop | All traffic on each peer link | +| FMP (mesh) | Hop-by-hop | All traffic on each peer link | | FSP (session) | End-to-end | Application payload between endpoints | **Why two layers instead of one**: @@ -163,7 +163,7 @@ MMP is instantiated at two independent layers, each with its own configuration and state: - **Link layer**: One `MmpPeerState` per `ActivePeer`. Measures per-hop - quality using the FLP counter and timestamp fields that already exist on + quality using the FMP counter and timestamp fields that already exist on every encrypted frame. No additional message overhead beyond periodic SenderReport/ReceiverReport exchanges. @@ -224,13 +224,13 @@ increase in bloom filter occupancy). ## Transport Opacity -Transport addresses are opaque byte vectors above FLP. The transport layer +Transport addresses are opaque byte vectors above FMP. The transport layer interprets them (e.g., UDP parses "ip:port" strings); all layers above treat them as handles passed back to the transport for sending. **Architectural boundary**: Adding a new transport type (e.g., BLE) requires implementing the transport trait and potentially a new `TransportHandle` -variant. No changes to FLP, FSP, or any routing logic. The transport trait +variant. No changes to FMP, FSP, or any routing logic. The transport trait defines the interface: - `send(addr, data)` — send a datagram @@ -300,7 +300,7 @@ The `TransportHandle` enum provides async dispatch for methods that need it ## References - [fips-intro.md](fips-intro.md) — Protocol overview -- [fips-link-layer.md](fips-link-layer.md) — FLP specification +- [fips-mesh-layer.md](fips-mesh-layer.md) — FMP specification - [fips-session-layer.md](fips-session-layer.md) — FSP specification - [fips-state-machines.md](fips-state-machines.md) — Phase-based state machine pattern diff --git a/docs/design/fips-transport-layer.md b/docs/design/fips-transport-layer.md index c10bc4c..abfcf51 100644 --- a/docs/design/fips-transport-layer.md +++ b/docs/design/fips-transport-layer.md @@ -8,14 +8,14 @@ session management — is built on the services the transport layer provides. ## Role A **transport** is a driver for a particular communication medium: a UDP -socket, an Ethernet interface, a LoRa radio, a serial line, a Tor circuit. +socket, an Ethernet interface, a serial line, a Tor circuit, a radio modem. The transport layer's job is simple: accept a datagram and a transport address, deliver the datagram to that address, and push inbound datagrams up -to the FIPS Link Protocol (FLP) above. +to the FIPS Mesh Protocol (FMP) above. The transport layer deals exclusively in **transport addresses** — IP:port -tuples, MAC addresses, LoRa device addresses, .onion identifiers. These are -opaque to every layer above FLP. The mapping from transport address to FIPS +tuples, MAC addresses, .onion identifiers, radio device addresses. These are +opaque to every layer above FMP. The mapping from transport address to FIPS identity happens at the link layer after the Noise IK handshake completes. The word "peer" belongs to the link layer and above; the transport layer knows only about remote endpoints identified by transport addresses. @@ -23,29 +23,29 @@ knows only about remote endpoints identified by transport addresses. A single transport instance can serve multiple remote endpoints simultaneously — a UDP socket exchanges datagrams with many remote addresses, an Ethernet interface communicates with many MAC addresses on the -same segment. Each endpoint may become a separate FLP link, but the +same segment. Each endpoint may become a separate FMP link, but the transport layer itself maintains no per-endpoint state. -## Services Provided to FLP +## Services Provided to FMP -The transport layer provides four services to the FIPS Link Protocol above: +The transport layer provides four services to the FIPS Mesh Protocol above: ### Datagram Delivery Send and receive datagrams to/from transport addresses. The transport handles all medium-specific details: socket management, framing for stream -transports, radio configuration. FLP sees only "send bytes to address" and +transports, radio configuration. FMP sees only "send bytes to address" and "bytes arrived from address." -Inbound datagrams are pushed to FLP through a channel. The transport spawns +Inbound datagrams are pushed to FMP through a channel. The transport spawns a receive task that pushes arriving datagrams (along with the source -transport address and transport identifier) onto a bounded channel. FLP +transport address and transport identifier) onto a bounded channel. FMP reads from this channel and dispatches based on the source address and packet content. ### MTU Reporting -Report the maximum datagram size for a given link. FLP needs this to +Report the maximum datagram size for a given link. FMP needs this to determine how much payload can fit in a single packet after link-layer encryption overhead. @@ -63,7 +63,7 @@ link individually. ### Connection Lifecycle For connection-oriented transports, manage the underlying connection: TCP -handshake, Tor circuit establishment, Bluetooth pairing. FLP cannot begin +handshake, Tor circuit establishment, Bluetooth pairing. FMP cannot begin the Noise IK handshake until the transport-layer connection is established. Connectionless transports (UDP, raw Ethernet) skip this — datagrams can flow @@ -71,7 +71,7 @@ immediately to any reachable address. ### Discovery (Optional) -Notify FLP when FIPS-capable endpoints are discovered on the local medium. +Notify FMP when FIPS-capable endpoints are discovered on the local medium. This is an optional capability — transports that don't support it simply don't provide discovery events. @@ -94,7 +94,6 @@ for internet connectivity: | TCP/IP | IP:port | Stream | Reliable | Requires length-prefix framing | | WebSocket | URL | Stream | Reliable | Browser-compatible | | Tor | .onion | Stream | Reliable | High latency, strong anonymity | -| I2P | Destination | ~32K | Unreliable | Datagram mode | **Shared medium transports** operate over broadcast- or multicast-capable media: @@ -105,7 +104,7 @@ media: | WiFi | MAC | 1500 | Unreliable | Infrastructure mode = Ethernet | | Bluetooth | BD_ADDR | 672–64K | Reliable | L2CAP | | BLE | BD_ADDR | 23–517 | Reliable | Negotiated ATT_MTU | -| LoRa | Device addr | 51–222 | Unreliable | Low bandwidth, long range | +| Radio | Device addr | 51–222 | Unreliable | Low bandwidth, long range | **Point-to-point transports** connect exactly two endpoints: @@ -114,9 +113,9 @@ media: | Serial | None (P2P) | 256–1500 | Reliable | SLIP/COBS framing | | Dialup | None (P2P) | 1500 | Reliable | PPP framing | -### Properties That Matter to FLP +### Properties That Matter to FMP -**MTU**: Determines how much data FLP can pack into a single datagram after +**MTU**: Determines how much data FMP can pack into a single datagram after accounting for link encryption overhead. Heterogeneous MTUs across the mesh are normal — the IPv6 minimum (1280 bytes) is the safe baseline for FIPS packet sizing. @@ -129,19 +128,19 @@ and duplication at the routing layer. **Connection model**: Connectionless transports (UDP, raw Ethernet) allow immediate datagram exchange. Connection-oriented transports (TCP, Tor, BLE) -require connection setup before FLP can begin the Noise IK handshake, +require connection setup before FMP can begin the Noise IK handshake, adding startup latency. **Stream vs. datagram**: Datagram transports have natural packet boundaries. Stream transports (TCP, WebSocket, Tor) require framing to delineate FIPS -packets within the byte stream. The FLP common prefix includes a payload +packets within the byte stream. The FMP common prefix includes a payload length field that provides this framing directly, replacing the need for a separate length-prefix layer. -**Addressing opacity**: Transport addresses are opaque byte vectors. FLP +**Addressing opacity**: Transport addresses are opaque byte vectors. FMP doesn't interpret them — it just passes them back to the transport when sending. This means adding a new transport type with a novel address format -requires no changes to FLP or FSP. +requires no changes to FMP or FSP. ## Connection Model @@ -154,13 +153,12 @@ are lightweight — a transport address is sufficient to begin communication. | --------- | ----- | | UDP/IP | Stateless datagrams; NAT state is implicit | | Ethernet | Send to MAC address directly | -| LoRa | Raw packets to device address | -| I2P | Datagram mode | +| Radio | Raw packets to device address | ### Connection-Oriented Transports Explicit connection setup is required before FIPS traffic can flow. The link -must complete transport-layer connection before FLP authentication can +must complete transport-layer connection before FMP authentication can proceed. | Transport | Connection Setup | @@ -185,7 +183,7 @@ circuit). Peer timeout configuration must account for transport-specific setup times. **Framing**: Stream transports must delimit FIPS packets within the byte -stream. The FLP common prefix includes a payload length field that provides +stream. The FMP common prefix includes a payload length field that provides integrated framing. Datagram transports preserve packet boundaries naturally. ## UDP/IP: The Primary Internet Transport @@ -248,14 +246,14 @@ discovery; a FIPS-specific announcement or response is. Discovery is an optional transport capability. Transports that don't support it (configured UDP endpoints, TCP) simply don't provide discovery events. -FLP handles both cases uniformly: with discovery, it waits for events then +FMP handles both cases uniformly: with discovery, it waits for events then initiates link setup; without discovery, it initiates link setup directly to configured addresses. ### Local/Medium Discovery *(future direction)* For transports where endpoints share a physical or link-layer medium — LAN -broadcast, LoRa, BLE — discovery uses beacon and query mechanisms: +broadcast, radio, BLE — discovery uses beacon and query mechanisms: - **Beacon**: A node periodically broadcasts its FIPS presence on the shared medium. Content is a FIPS-defined discovery frame carrying enough @@ -264,13 +262,13 @@ broadcast, LoRa, BLE — discovery uses beacon and query mechanisms: respond. Responses arrive on the same channel as beacon events. Both produce the same result: "FIPS endpoint available at transport address -X." FLP does not need to distinguish beacons from query responses. +X." FMP does not need to distinguish beacons from query responses. | Transport | Discovery | Notes | | --------- | --------- | ----- | | UDP (LAN) | Broadcast/multicast | On local network segment | | Ethernet | Broadcast | Custom EtherType, ff:ff:ff:ff:ff:ff | -| LoRa | Beacon | Shared RF channel, natural fit | +| Radio | Beacon | Shared RF channel, natural fit | | BLE | Advertising | GATT service UUID | ### Nostr Relay Discovery *(future direction)* @@ -290,7 +288,7 @@ Key properties: is authenticated - Relay selection acts as scoping — which relays a node publishes to and subscribes on determines its discovery neighborhood -- Can only advertise IP-reachable endpoints (not LoRa, BLE, serial) +- Can only advertise IP-reachable endpoints (not radio, BLE, serial) - Higher latency than local discovery (relay propagation delays) ### Current State @@ -333,7 +331,7 @@ Each inbound datagram carries: ### Transport Metadata -Transport types carry static metadata that FLP can query: +Transport types carry static metadata that FMP can query: ```text TransportType { @@ -373,7 +371,7 @@ transitions through `Starting` to `Up` (operational). `stop()` moves to | WiFi | Future direction | Infrastructure mode = Ethernet driver | | Tor | Future direction | High latency, .onion addressing | | BLE | Future direction | ATT_MTU negotiation, per-link MTU | -| LoRa | Future direction | Constrained MTU (51–222 bytes) | +| Radio | Future direction | Constrained MTU (51–222 bytes) | | Serial | Future direction | SLIP/COBS framing, point-to-point | ## Design Considerations @@ -399,7 +397,7 @@ traffic automatically routes through alternatives. A node with both UDP and Ethernet transports bridges between internet-connected and local-only networks transparently. -Multiple links to the same peer over different transports are possible. FLP +Multiple links to the same peer over different transports are possible. FMP manages these independently — each link has its own Noise session, its own MTU, and its own liveness tracking. @@ -413,7 +411,7 @@ consider transport quality. This is a potential area for future optimization. ## References - [fips-intro.md](fips-intro.md) — Protocol overview and layer architecture -- [fips-link-layer.md](fips-link-layer.md) — FLP specification (the layer above) +- [fips-mesh-layer.md](fips-mesh-layer.md) — FMP specification (the layer above) - [fips-wire-formats.md](fips-wire-formats.md) — Transport framing details - [fips-software-architecture.md](fips-software-architecture.md) — Transport trait implementation details diff --git a/docs/design/fips-wire-formats.md b/docs/design/fips-wire-formats.md index 115cb5e..13dc674 100644 --- a/docs/design/fips-wire-formats.md +++ b/docs/design/fips-wire-formats.md @@ -32,7 +32,7 @@ tag). No separate length prefix is needed. ## Link-Layer Formats -All FLP packets begin with a **4-byte common prefix** that identifies the +All FMP packets begin with a **4-byte common prefix** that identifies the protocol version, session lifecycle phase, per-packet flags, and payload length. @@ -663,11 +663,11 @@ Layer 3: Session encryption (FSP) FSP header (12 bytes) + AEAD(inner_hdr (6) + payload (1024)) + AEAD tag (16) = 1058 bytes -Layer 2: SessionDatagram envelope (FLP routing) +Layer 2: SessionDatagram envelope (FMP routing) msg_type (1) + ttl (1) + path_mtu (2) + src_addr (16) + dest_addr (16) + payload (1058) = 1094 bytes -Layer 1: Link encryption (FLP per-hop) +Layer 1: Link encryption (FMP per-hop) outer header (16) + encrypted(inner_hdr (5) + datagram (1094)) + AEAD tag (16) = 1131 bytes @@ -754,7 +754,7 @@ endpoint session keys). ## References -- [fips-link-layer.md](fips-link-layer.md) — FLP behavioral specification +- [fips-mesh-layer.md](fips-mesh-layer.md) — FMP behavioral specification - [fips-session-layer.md](fips-session-layer.md) — FSP behavioral specification - [fips-transport-layer.md](fips-transport-layer.md) — Transport framing - [fips-mesh-operation.md](fips-mesh-operation.md) — How messages work together diff --git a/src/mmp/mod.rs b/src/mmp/mod.rs index 50071bf..36141e6 100644 --- a/src/mmp/mod.rs +++ b/src/mmp/mod.rs @@ -2,7 +2,7 @@ //! //! Measures link quality between adjacent peers: RTT, loss, jitter, //! throughput, one-way delay trend, and ETX. Operates on the per-frame -//! hooks (counter, timestamp, flags) introduced by the FLP wire format +//! hooks (counter, timestamp, flags) introduced by the FMP wire format //! revision. //! //! Three operating modes trade measurement fidelity for overhead: diff --git a/src/node/handlers/rx_loop.rs b/src/node/handlers/rx_loop.rs index 432a780..b9ba1ce 100644 --- a/src/node/handlers/rx_loop.rs +++ b/src/node/handlers/rx_loop.rs @@ -2,7 +2,7 @@ use crate::node::{Node, NodeError}; use crate::transport::ReceivedPacket; -use crate::node::wire::{CommonPrefix, PHASE_ESTABLISHED, PHASE_MSG1, PHASE_MSG2, FLP_VERSION, COMMON_PREFIX_SIZE}; +use crate::node::wire::{CommonPrefix, PHASE_ESTABLISHED, PHASE_MSG1, PHASE_MSG2, FMP_VERSION, COMMON_PREFIX_SIZE}; use std::time::Duration; use tracing::{debug, info}; @@ -110,11 +110,11 @@ impl Node { None => return, // Malformed prefix }; - if prefix.version != FLP_VERSION { + if prefix.version != FMP_VERSION { debug!( version = prefix.version, transport_id = %packet.transport_id, - "Unknown FLP version, dropping" + "Unknown FMP version, dropping" ); return; } @@ -133,7 +133,7 @@ impl Node { debug!( phase = prefix.phase, transport_id = %packet.transport_id, - "Unknown FLP phase, dropping" + "Unknown FMP phase, dropping" ); } } diff --git a/src/node/session_wire.rs b/src/node/session_wire.rs index b9c063b..f4668e6 100644 --- a/src/node/session_wire.rs +++ b/src/node/session_wire.rs @@ -144,7 +144,7 @@ impl FspCommonPrefix { /// ``` /// /// The full 12-byte header is used as AAD for the AEAD construction. -/// No receiver_idx — unlike FLP, FSP is end-to-end (dispatched by src_addr +/// No receiver_idx — unlike FMP, FSP is end-to-end (dispatched by src_addr /// from the SessionDatagram envelope, not by index). #[derive(Clone, Debug)] pub struct FspEncryptedHeader { diff --git a/src/node/tests/spanning_tree.rs b/src/node/tests/spanning_tree.rs index eb5d585..d86f642 100644 --- a/src/node/tests/spanning_tree.rs +++ b/src/node/tests/spanning_tree.rs @@ -204,7 +204,7 @@ pub(super) fn print_tree_snapshot(label: &str, nodes: &[TestNode]) { /// /// Returns the number of packets processed. pub(super) async fn process_available_packets(nodes: &mut [TestNode]) -> usize { - use crate::node::wire::{CommonPrefix, FLP_VERSION, PHASE_ESTABLISHED, PHASE_MSG1, PHASE_MSG2, COMMON_PREFIX_SIZE}; + use crate::node::wire::{CommonPrefix, FMP_VERSION, PHASE_ESTABLISHED, PHASE_MSG1, PHASE_MSG2, COMMON_PREFIX_SIZE}; let mut count = 0; for node in nodes.iter_mut() { @@ -213,7 +213,7 @@ pub(super) async fn process_available_packets(nodes: &mut [TestNode]) -> usize { continue; } if let Some(prefix) = CommonPrefix::parse(&packet.data) { - if prefix.version != FLP_VERSION { + if prefix.version != FMP_VERSION { continue; } match prefix.phase { diff --git a/src/node/wire.rs b/src/node/wire.rs index 3471e07..0d7f98e 100644 --- a/src/node/wire.rs +++ b/src/node/wire.rs @@ -1,6 +1,6 @@ //! Wire Format Parsing and Serialization //! -//! Defines the FIPS link-layer wire format (FLP) for packet dispatch. +//! Defines the FIPS mesh-layer wire format (FMP) for packet dispatch. //! All packets begin with a 4-byte common prefix followed by phase-specific fields. //! //! ## Common Prefix (4 bytes) @@ -24,8 +24,8 @@ use crate::noise::{HANDSHAKE_MSG1_SIZE, HANDSHAKE_MSG2_SIZE, TAG_SIZE}; // Constants // ============================================================================ -/// FLP protocol version (4 high bits of byte 0). -pub const FLP_VERSION: u8 = 0; +/// FMP protocol version (4 high bits of byte 0). +pub const FMP_VERSION: u8 = 0; /// Phase value for established (encrypted) frames. pub const PHASE_ESTABLISHED: u8 = 0x0; @@ -70,7 +70,7 @@ pub const FLAG_SP: u8 = 0x04; // Common Prefix // ============================================================================ -/// Parsed common packet prefix (first 4 bytes of every FLP packet). +/// Parsed common packet prefix (first 4 bytes of every FMP packet). /// /// Wire format: /// ```text @@ -156,7 +156,7 @@ impl EncryptedHeader { let version = data[0] >> 4; let phase = data[0] & 0x0F; - if version != FLP_VERSION || phase != PHASE_ESTABLISHED { + if version != FMP_VERSION || phase != PHASE_ESTABLISHED { return None; } @@ -222,7 +222,7 @@ impl Msg1Header { let version = data[0] >> 4; let phase = data[0] & 0x0F; - if version != FLP_VERSION || phase != PHASE_MSG1 { + if version != FMP_VERSION || phase != PHASE_MSG1 { return None; } @@ -278,7 +278,7 @@ impl Msg2Header { let version = data[0] >> 4; let phase = data[0] & 0x0F; - if version != FLP_VERSION || phase != PHASE_MSG2 { + if version != FMP_VERSION || phase != PHASE_MSG2 { return None; } @@ -317,7 +317,7 @@ pub fn build_msg1(sender_idx: SessionIndex, noise_msg1: &[u8]) -> Vec { let payload_len = (4 + noise_msg1.len()) as u16; // sender_idx + noise_msg1 let mut packet = Vec::with_capacity(MSG1_WIRE_SIZE); - packet.push(CommonPrefix::ver_phase_byte(FLP_VERSION, PHASE_MSG1)); + packet.push(CommonPrefix::ver_phase_byte(FMP_VERSION, PHASE_MSG1)); packet.push(0x00); // flags must be zero packet.extend_from_slice(&payload_len.to_le_bytes()); packet.extend_from_slice(&sender_idx.to_le_bytes()); @@ -334,7 +334,7 @@ pub fn build_msg2(sender_idx: SessionIndex, receiver_idx: SessionIndex, noise_ms let payload_len = (4 + 4 + noise_msg2.len()) as u16; // sender + receiver + noise let mut packet = Vec::with_capacity(MSG2_WIRE_SIZE); - packet.push(CommonPrefix::ver_phase_byte(FLP_VERSION, PHASE_MSG2)); + packet.push(CommonPrefix::ver_phase_byte(FMP_VERSION, PHASE_MSG2)); packet.push(0x00); // flags must be zero packet.extend_from_slice(&payload_len.to_le_bytes()); packet.extend_from_slice(&sender_idx.to_le_bytes()); @@ -353,7 +353,7 @@ pub fn build_established_header( payload_len: u16, ) -> [u8; ESTABLISHED_HEADER_SIZE] { let mut header = [0u8; ESTABLISHED_HEADER_SIZE]; - header[0] = CommonPrefix::ver_phase_byte(FLP_VERSION, PHASE_ESTABLISHED); + header[0] = CommonPrefix::ver_phase_byte(FMP_VERSION, PHASE_ESTABLISHED); header[1] = flags; header[2..4].copy_from_slice(&payload_len.to_le_bytes()); header[4..8].copy_from_slice(&receiver_idx.to_le_bytes()); diff --git a/src/noise/mod.rs b/src/noise/mod.rs index fe0f8c6..ac6d548 100644 --- a/src/noise/mod.rs +++ b/src/noise/mod.rs @@ -268,7 +268,7 @@ impl CipherState { /// Encrypt plaintext with Additional Authenticated Data (AAD). /// - /// The AAD is authenticated but not encrypted. Used for the FLP + /// The AAD is authenticated but not encrypted. Used for the FMP /// established frame format where the 16-byte outer header is /// bound to the AEAD tag. pub fn encrypt_with_aad( diff --git a/src/noise/session.rs b/src/noise/session.rs index c43ff62..0c4a19d 100644 --- a/src/noise/session.rs +++ b/src/noise/session.rs @@ -118,7 +118,7 @@ impl NoiseSession { /// Decrypt with explicit counter, replay protection, and AAD. /// - /// This is the primary decryption method for the FLP transport phase + /// This is the primary decryption method for the FMP transport phase /// with AAD binding. The AAD (typically the 16-byte outer header) must /// match what was used during encryption. pub fn decrypt_with_replay_check_and_aad( diff --git a/src/protocol/session.rs b/src/protocol/session.rs index 8d69d89..ef0ff78 100644 --- a/src/protocol/session.rs +++ b/src/protocol/session.rs @@ -565,7 +565,7 @@ impl SessionAck { /// Session-layer sender report (msg_type 0x11). /// -/// Mirrors the FLP `SenderReport` fields but carried as an FSP session +/// Mirrors the FMP `SenderReport` fields but carried as an FSP session /// message inside the AEAD envelope. The msg_type is in the FSP inner /// header, so the body starts with reserved bytes. /// @@ -634,7 +634,7 @@ impl SessionSenderReport { /// Session-layer receiver report (msg_type 0x12). /// -/// Mirrors the FLP `ReceiverReport` fields but carried as an FSP session +/// Mirrors the FMP `ReceiverReport` fields but carried as an FSP session /// message inside the AEAD envelope. /// /// ## Wire Format (66 bytes body, after inner header stripped) diff --git a/src/upper/icmp.rs b/src/upper/icmp.rs index aca3985..d6a29fb 100644 --- a/src/upper/icmp.rs +++ b/src/upper/icmp.rs @@ -69,22 +69,22 @@ const MAX_ORIGINAL_PACKET: usize = MIN_IPV6_MTU - IPV6_HEADER_LEN - ICMPV6_HEADE /// Breakdown (traced through the actual send path): /// /// ```text -/// FLP outer header (cleartext AAD) 16 +/// FMP outer header (cleartext AAD) 16 /// common prefix (4) + receiver_idx (4) + counter (8) -/// FLP AEAD ciphertext: -/// timestamp (4) + msg_type (1) 5 [FLP inner header] +/// FMP AEAD ciphertext: +/// timestamp (4) + msg_type (1) 5 [FMP inner header] /// ttl (1) + path_mtu (2) + src (16) + dst (16) 35 [SessionDatagram body] /// FSP header (4 prefix + 8 counter) 12 [cleartext AAD] /// FSP AEAD ciphertext: /// timestamp (4) + msg_type (1) + flags (1) 6 [FSP inner header] /// /// Poly1305 tag 16 [FSP AEAD] -/// FLP Poly1305 tag 16 [FLP AEAD] +/// FMP Poly1305 tag 16 [FMP AEAD] /// ──── /// 106 /// ``` /// -/// Note: the FLP inner header msg_type byte IS the SessionDatagram msg_type +/// Note: the FMP inner header msg_type byte IS the SessionDatagram msg_type /// byte (shared, not double-counted). The "35 bytes" is the SessionDatagram /// body after msg_type is consumed by the dispatch layer. pub const FIPS_OVERHEAD: u16 = 16 + 16 + 5 + 35 + 12 + 6 + 16; // 106 bytes