mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-22 07:48:26 +00:00
cf62cff5f4
Make the FIPS core build and run as an embedded Android library. The host app owns the TUN (e.g. an Android VpnService) and FIPS performs no system-TUN or CAP_NET_ADMIN operations. Squashed from the following changes: - gate desktop transports/TUN by target_os, not features: a plain `cargo build` now compiles for every target with no flags. Ethernet (raw AF_PACKET / BPF) is gated to linux/macos, so Android (target_os = "android", not "linux") self-excludes it as Windows already did; real system-TUN ops are gated per linux/macos and Android gets a no-op stub; the ipi6_ifindex cast handles it being i32 on Android vs u32 on macOS. No Cargo features are introduced; desktop builds are unchanged. - app-owned TUN seam: Node::enable_app_owned_tun() lets an embedder that owns the TUN fd exchange IPv6 packet bytes with FIPS over channels instead of FIPS creating a system TUN device. It returns (app_outbound_tx, app_inbound_rx): the embedder pushes packets read from its fd into the outbound sender (app -> mesh) and pulls packets destined for its fd from the inbound receiver (mesh -> app). start() gates system-TUN creation on tun_tx being unset, so with the channels pre-installed it skips device creation and does no system-TUN ops; both directions reuse the existing inbound-shim and run_rx_loop wiring. Packets entering via app_outbound_tx bypass handle_tun_packet, so the embedder must push only fd00::/8-destined packets and clamp TCP MSS on outbound SYNs; the rustdoc and the IPv6-adapter design doc spell this out. - keep the android target warning-clean so the cross-compile check passes clippy -D warnings. - add an Android cross-compile CI check: cross-compile the library for aarch64-linux-android via cargo-ndk and run clippy -D warnings. Android ships as an embedded library (the host app owns the TUN), so there is no daemon binary to package; this is a check job, not a packaging one. - docs: list Android as a supported platform. Tests: app_owned_tun_seam_wires_channels covers the channel round-trip and the Active state; start_skips_system_tun_when_app_owned runs start() and asserts no named system device is created.
FIPS Design
Architectural and protocol-level explanations for FIPS — the why and the how behind the wire and the system. For wire formats and configuration keys, see reference/. For task recipes, see how-to/. For end-to-end lessons, see tutorials/.
Reading Order
Start with fips-concepts.md for the novice-friendly framing of what FIPS is and why, then move to fips-architecture.md for the protocol stack, identity model, and two-layer encryption walkthrough. From there, follow the protocol stack from bottom to top. After the stack, fips-mesh-operation.md explains how the pieces work together at runtime. Cross-cutting and supporting documents cover specific subsystems in detail.
Foundations
| Document | Description |
|---|---|
| fips-concepts.md | What FIPS is, why it exists, mental model |
| fips-architecture.md | Protocol stack, identity, two-layer encryption |
| fips-prior-work.md | Designs and protocols FIPS builds on |
Protocol Stack
| Document | Description |
|---|---|
| fips-transport-layer.md | Transport layer: datagram delivery over arbitrary media |
| fips-mesh-layer.md | FIPS Mesh Protocol (FMP): peer authentication, link encryption, forwarding |
| fips-session-layer.md | FIPS Session Protocol (FSP): end-to-end encryption, sessions |
| fips-ipv6-adapter.md | IPv6 adaptation: TUN interface, DNS, MTU enforcement |
Cross-Cutting
| Document | Description |
|---|---|
| fips-mmp.md | Metrics Measurement Protocol (link + session) |
| fips-mtu.md | Path MTU model, encapsulation overhead, PMTUD |
| fips-security.md | fips0 interface threat model and default-deny baseline |
Mesh Behavior
| Document | Description |
|---|---|
| fips-mesh-operation.md | How the mesh operates: routing, discovery, error recovery |
| fips-nostr-discovery.md | Optional Nostr-mediated peer discovery and UDP NAT hole-punch |
| port-advertisement-and-nat-traversal.md | Nostr-signaled port advertisement and UDP NAT-traversal protocol; generic, with FIPS as an example implementation |
Deeper Dives
| Document | Description |
|---|---|
| fips-spanning-tree.md | Spanning tree algorithms: root discovery, parent selection, coordinates |
| fips-bloom-filters.md | Bloom filter properties: FPR analysis, size classes, split-horizon |
| spanning-tree-dynamics.md | Spanning tree walkthroughs: convergence scenarios, worked examples |
Adjacent Components
| Document | Description |
|---|---|
| fips-gateway.md | fips-gateway service: outbound (LAN-to-mesh) DNS-proxy + virtual-IP NAT and inbound (mesh-to-LAN) port-forwarding, sharing one nftables table |