mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-10 00:26:59 +00:00
Johnathan Corgan
a8115f7622
Design change: Session layer now uses Noise IK pattern (previously KK), matching the link layer. Rationale: initiator knows destination npub, responder learns initiator identity from handshake - same asymmetry as link connections. Document consistency fixes: - Auth* events → Noise IK msg1/msg2 terminology in state machines - PeerId → NodeId in routing code examples - BloomUpdate → FilterAnnounce terminology - Updated cross-references and tables
61 lines
3.4 KiB
Markdown
61 lines
3.4 KiB
Markdown
# FIPS Design Documents
|
|
|
|
Protocol design specifications and analysis for the Federated Interoperable Peering System.
|
|
|
|
## Suggested Reading Order
|
|
|
|
Start with the high-level architecture, then work through session flow, routing
|
|
concepts, and finally the wire-level protocol details.
|
|
|
|
### 1. Introduction and Overview
|
|
|
|
| Document | Description |
|
|
|------------------------------------------|-------------------------------------------------------------|
|
|
| [fips-intro.md](fips-intro.md) | Protocol introduction: goals, concepts, architecture |
|
|
|
|
### 2. Protocol Flow (How Traffic Works)
|
|
|
|
| Document | Description |
|
|
|------------------------------------------------------|-----------------------------------------------------------|
|
|
| [fips-session-protocol.md](fips-session-protocol.md) | End-to-end session flow, Noise IK encryption, terminology |
|
|
|
|
### 3. Routing (How Packets Find Their Way)
|
|
|
|
| Document | Description |
|
|
|--------------------------------------------------------|-------------------------------------------------------------|
|
|
| [fips-routing.md](fips-routing.md) | Routing concepts: bloom filters, discovery, greedy routing |
|
|
| [spanning-tree-dynamics.md](spanning-tree-dynamics.md) | Tree protocol behavior: convergence, partitions, recovery |
|
|
| [fips-gossip-protocol.md](fips-gossip-protocol.md) | Wire formats: TreeAnnounce, FilterAnnounce, Lookup messages |
|
|
|
|
### 4. Link Layer (How Peer Connections Work)
|
|
|
|
| Document | Description |
|
|
|------------------------------------------------|---------------------------------------------------------------|
|
|
| [fips-wire-protocol.md](fips-wire-protocol.md) | Transport layer: Noise IK, session indices, roaming, security |
|
|
| [fips-transports.md](fips-transports.md) | Transport-specific: UDP, Ethernet, Tor, radio characteristics |
|
|
|
|
## Implementation
|
|
|
|
| Document | Description |
|
|
|--------------------------------------------------|------------------------------------------------------------------|
|
|
| [fips-architecture.md](fips-architecture.md) | Software architecture: entities, state machines, configuration |
|
|
| [fips-tun-driver.md](fips-tun-driver.md) | TUN interface driver: reader/writer threads, ICMPv6, packet flow |
|
|
| [fips-state-machines.md](fips-state-machines.md) | Phase-based state machine pattern: peer lifecycle, transitions |
|
|
|
|
## Document Cross-References
|
|
|
|
```text
|
|
fips-intro.md
|
|
│
|
|
┌────────────┴────────────┐
|
|
▼ ▼
|
|
fips-session-protocol.md fips-architecture.md
|
|
│ │
|
|
┌─────────┴─────────┐ ▼
|
|
▼ ▼ fips-transports.md
|
|
fips-routing.md fips-wire-protocol.md
|
|
│ │
|
|
▼ ▼
|
|
spanning-tree-dynamics.md ←→ fips-gossip-protocol.md
|
|
```
|