mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-10 16:43:12 +00:00
Johnathan Corgan
00e26765bd
Wire format diagrams: - Add 24 SVG diagrams covering every FMP and FSP wire format: common prefix, established frame headers, Noise IK handshake messages, handshake flow, TreeAnnounce, AncestryEntry, FilterAnnounce, LookupRequest/Response, SessionDatagram, Disconnect, SenderReport, ReceiverReport, FSP complete message, SessionSetup/Ack/Msg3, PathMtuNotification, CoordsRequired, PathBroken, and MtuExceeded - Replace ASCII art in fips-wire-formats.md with SVG references - Apply text edits to fips-mesh-layer.md, fips-mesh-operation.md, fips-transport-layer.md, and fips-ipv6-adapter.md Spanning tree dynamics: - Add 12 topology SVG diagrams: node join (overview + 3-panel steps), three-node convergence (4-panel), link addition with depth labels, link removal, partition formation, and 6 real-world example diagrams (office, mixed-link, two-site WAN topologies) - Rewrite all code blocks to narrative prose with diagram references - Add inline prior art attributions distinguishing Yggdrasil-derived concepts from FIPS-novel contributions - Add 3 new references (De Couto ETX, IEEE 802.1D, RFC 2328 OSPF) and Prior Art summary - Remove outdated sections: indirect partition note, integration test gaps, DHT-based lookup reference - Change "must elect a new root" to "must rediscover its new root" Spanning tree design review (fips-spanning-tree.md): - Rename "Root Election" to "Root Discovery" across docs - Add "What Is a Spanning Tree?" introductory section - Add parent selection intro explaining self-organization role - Fix tree distance example: 4 hops, not 2 - Clarify timestamp field as advisory only - Remove unimplemented ROOT_TIMEOUT and TREE_ENTRY_TTL from timing parameters and implementation status tables Bloom filter design review (fips-bloom-filters.md): - Add "What Is a Bloom Filter?" intro section - Rewrite Purpose section to frame filters as routing path identification - Correct FPR analysis (old values were 3-50x overstated) - Add Filter Occupancy Model based on network size and tree position - Fix filter expiration to describe actual MMP-based cleanup - Combine Scale Considerations with Size Classes after Wire Format - Fix stale FPR values in src/bloom/mod.rs comments Session layer review (fips-session-layer.md): - Add inline prior art attributions: Noise Protocol Framework, WireGuard, DTLS (RFC 6347), IKEv2 (RFC 7296), RFC 1191 PMTUD, Yggdrasil, NIP-44 - Replace warmup state machine ASCII art with SVG diagram - Convert CoordsWarmup wire format code block to prose - Add External References section with full citations Level 5 implementation doc cleanup: - Delete fips-software-architecture.md (redundant with protocol layer docs) - Delete fips-state-machines.md (Rust tutorial, not protocol design) - Add fipsctl command reference to README.md - Update cross-references in fips-intro.md, docs/design/README.md, fips-transport-layer.md, fips-configuration.md Fixes: - Correct fd::/8 to fd00::/8 in fips-session-layer.md, fips-identity-derivation.svg, and fips-node-architecture.svg - Fix config example MTU: 1197 → 1472 in fips-configuration.md File organization: - Move all SVG diagrams into docs/design/diagrams/ subdirectory - Update all diagram references to use new paths
117 lines
3.7 KiB
Markdown
117 lines
3.7 KiB
Markdown
# FIPS: Free Internetworking Peering System
|
|
|
|
A distributed, decentralized network routing protocol for mesh nodes
|
|
connecting over arbitrary transports.
|
|
|
|
> **Status: Experimental / Pre-release**
|
|
>
|
|
> FIPS is under active development. The protocol and APIs are not stable.
|
|
> Expect breaking changes.
|
|
|
|
## Overview
|
|
|
|
FIPS is a self-organizing mesh network that operates natively over a variety
|
|
of physical and logical media — local area networks, Bluetooth, serial links,
|
|
radio, or the existing internet as an overlay. Nodes generate their own
|
|
identities, discover each other, and route traffic without any central
|
|
authority or global topology knowledge.
|
|
|
|
FIPS uses Nostr keypairs (secp256k1/schnorr) as native node identities,
|
|
making every Nostr user a potential network participant. Nodes address each
|
|
other by npub, and the same cryptographic identity used in the Nostr ecosystem
|
|
serves as both the routing address and the basis for end-to-end encrypted
|
|
sessions across the mesh.
|
|
|
|
## Features
|
|
|
|
- **Self-organizing mesh routing** — spanning tree coordinates and bloom
|
|
filter candidate selection, no global routing tables
|
|
- **Multi-transport** — UDP/IP overlay today; designed for Ethernet,
|
|
Bluetooth, serial, radio, and Tor
|
|
- **Noise encryption** — hop-by-hop link encryption plus independent
|
|
end-to-end session encryption
|
|
- **Nostr-native identity** — secp256k1 keypairs as node addresses, no
|
|
registration or central authority
|
|
- **IPv6 adaptation** — TUN interface maps npubs to fd00::/8 addresses for
|
|
unmodified IP applications
|
|
- **Metrics Measurement Protocol** — per-link RTT, loss, jitter, and goodput
|
|
measurement
|
|
- **Operator visibility** — `fipsctl` control socket interface for runtime
|
|
inspection of peers, links, sessions, tree state, and metrics
|
|
- **Zero configuration** — sensible defaults; a node can run with no config
|
|
file
|
|
|
|
## Quick Start
|
|
|
|
### Requirements
|
|
|
|
- Rust 1.85+ (edition 2024)
|
|
- Linux (TUN interface requires `CAP_NET_ADMIN` or root)
|
|
|
|
### Build
|
|
|
|
```
|
|
git clone https://github.com/jmcorgan/fips.git
|
|
cd fips
|
|
cargo build --release
|
|
```
|
|
|
|
### Run
|
|
|
|
```
|
|
# With default configuration (ephemeral identity, default ports):
|
|
sudo ./target/release/fips
|
|
|
|
# With a configuration file:
|
|
sudo ./target/release/fips -c fips.yaml
|
|
```
|
|
|
|
See [docs/design/fips-configuration.md](docs/design/fips-configuration.md) for
|
|
the full configuration reference.
|
|
|
|
### Inspect
|
|
|
|
While a node is running, use `fipsctl` to inspect its state:
|
|
|
|
```
|
|
fipsctl show status # Node status overview
|
|
fipsctl show peers # Authenticated peers
|
|
fipsctl show links # Active links
|
|
fipsctl show tree # Spanning tree state
|
|
fipsctl show sessions # End-to-end sessions
|
|
fipsctl show bloom # Bloom filter state
|
|
fipsctl show mmp # MMP metrics summary
|
|
fipsctl show cache # Coordinate cache stats
|
|
fipsctl show connections # Pending handshake connections
|
|
fipsctl show transports # Transport instances
|
|
fipsctl show routing # Routing table summary
|
|
```
|
|
|
|
`fipsctl` communicates with the node via a Unix domain control socket
|
|
(enabled by default). All queries are read-only. Use `-s <path>` to
|
|
override the socket path.
|
|
|
|
### Multi-node Testing
|
|
|
|
See [testing/](testing/) for Docker-based integration test harnesses including
|
|
static topology tests and stochastic chaos simulation.
|
|
|
|
## Documentation
|
|
|
|
Protocol design documentation is in [docs/design/](docs/design/), organized as
|
|
a layered protocol specification. Start with
|
|
[fips-intro.md](docs/design/fips-intro.md) for the full protocol overview.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/ Rust source (library + fips/fipsctl binaries)
|
|
docs/design/ Protocol design specifications
|
|
testing/ Docker-based integration test harnesses
|
|
benches/ Criterion benchmarks
|
|
```
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|