mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-05 11:08:25 +00:00
Johnathan Corgan
f0ee81ec7c
Move the staged changelog entries under a 0.5.1 heading dated 2026-09-06, and add an entry for the deb-install hang: the suite started a oneshot unit that requires the daemon, so a daemon that could not execute left the start job undispatched and the suite reported nothing at all. That is the whole class of fault the suite exists to find, and it protects the run that gates artifact publication, so it is owed an entry. Add the release notes and mirror them to the root file. The notes lead with who should upgrade and who is unaffected, because for most users this release changes nothing and for Debian 12 and Ubuntu 22.04 users the daemon has never run at all. They state what was measured and what was not, and give an objdump line that reads the floor of a binary already installed: 2.34 from this release, 2.39 from any earlier one. The root mirror is not byte-identical to the versioned copy and cannot be. The two files sit at different depths, so a link that resolves in one breaks in the other; the mirror is content-identical with the relative link paths rewritten, and the check is a diff whose every hunk is a link path. Here that is two hunks, both confirmed to resolve. The currency audit found five stale version sites and two claims that do not match the tree, all corrected here. The status badge, the release-notes link and the status sentence in the README follow the release, as they did at v0.4.2. The FreeBSD install line gave a filename that does not exist, since the tree is 0.5.1-dev; it now takes a version placeholder so it stops going stale at every bump, and the example above it keeps a concrete name. The design document recorded the first lookup fix and not the second: it still said a returning copy is dropped as a duplicate, which the next commit in this release exists to stop doing. It now names the counter that actually receives the drop. The README claimed the .deb is exercised per release. The install suite is real and covers the five distributions it names, but it runs on push and pull request, not at a tag, and no workflow installs the published artifact. The sentence now says that, so the released package being checked by hand is written down rather than assumed. Getting-started gains the statement this release should have produced: which distributions are supported and why the binaries run on all of them. Until now the policy and the floor lived only in the build environment file, so an operator had nowhere to read either.
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 |
| fips-native-api.md | Native datagram API: pubkey-addressed flows over FSP, and what it is instead of the TUN path |
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 |