laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-10-05 19:18:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
5a5faa0857b6cf5e8e585b5fb65e7474b8f667e5
fips/docs/design/diagrams/fips-architecture-overview.svg
T
Johnathan Corgan 00e26765bd Design documentation illustration and review pass 
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
2026-02-24 17:32:37 +00:00

114 lines
6.2 KiB
XML
Raw Blame History

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 455" font-family="monospace" font-size="13">
<style>
rect.node { fill: #1a1a2e; stroke: #e0e0e0; stroke-width: 1.5; rx: 4; }
rect.app { fill: #1a3a2a; stroke: #40a060; stroke-width: 1; rx: 2; }
rect.fips { fill: #2e3a5e; stroke: #5080c0; stroke-width: 1; rx: 2; }
rect.xport { fill: #2a1a1a; stroke: #c06040; stroke-width: 1; rx: 2; }
text { fill: #e0e0e0; }
text.label { font-size: 15px; font-weight: bold; }
text.role { font-size: 11px; fill: #90a0b0; }
text.layer { font-size: 12px; }
text.caption { font-size: 13px; fill: #808090; font-style: italic; }
path.link { fill: none; stroke: #5080c0; stroke-width: 2; }
text.link-label { font-size: 12px; fill: #5080c0; font-weight: bold; }
text.link-enc { font-size: 10px; fill: #5080c0; }
line.session { stroke: #d0a040; stroke-width: 2; stroke-dasharray: 8,4; }
text.session-label { font-size: 13px; fill: #d0a040; }
text.legend { font-size: 12px; }
</style>
<!-- Background -->
<rect width="880" height="420" fill="#0d1117" rx="8"/>
<!-- ============ NODES ============ -->
<!-- Node A (source) -->
<text x="100" y="30" text-anchor="middle" class="label">Node A</text>
<text x="100" y="46" text-anchor="middle" class="role">(source)</text>
<rect x="50" y="56" width="100" height="130" class="node"/>
<rect x="60" y="66" width="80" height="28" class="app"/>
<text x="100" y="85" text-anchor="middle" class="layer">App</text>
<rect x="60" y="102" width="80" height="28" class="fips"/>
<text x="100" y="121" text-anchor="middle" class="layer">FIPS</text>
<rect x="60" y="138" width="80" height="28" class="xport"/>
<text x="100" y="157" text-anchor="middle" class="layer">WiFi</text>
<!-- Node B (transit) -->
<text x="280" y="30" text-anchor="middle" class="label">Node B</text>
<text x="280" y="46" text-anchor="middle" class="role">(transit)</text>
<rect x="230" y="56" width="100" height="130" class="node"/>
<rect x="240" y="102" width="80" height="28" class="fips"/>
<text x="280" y="121" text-anchor="middle" class="layer">FIPS</text>
<rect x="240" y="138" width="36" height="28" class="xport"/>
<text x="258" y="157" text-anchor="middle" class="layer">WiFi</text>
<rect x="284" y="138" width="36" height="28" class="xport"/>
<text x="302" y="157" text-anchor="middle" class="layer">Eth</text>
<!-- Node C (transit) -->
<text x="460" y="30" text-anchor="middle" class="label">Node C</text>
<text x="460" y="46" text-anchor="middle" class="role">(transit)</text>
<rect x="410" y="56" width="100" height="130" class="node"/>
<rect x="420" y="102" width="80" height="28" class="fips"/>
<text x="460" y="121" text-anchor="middle" class="layer">FIPS</text>
<rect x="420" y="138" width="36" height="28" class="xport"/>
<text x="438" y="157" text-anchor="middle" class="layer">Eth</text>
<rect x="464" y="138" width="36" height="28" class="xport"/>
<text x="482" y="157" text-anchor="middle" class="layer">UDP</text>
<!-- Node D (transit) -->
<text x="640" y="30" text-anchor="middle" class="label">Node D</text>
<text x="640" y="46" text-anchor="middle" class="role">(transit)</text>
<rect x="590" y="56" width="100" height="130" class="node"/>
<rect x="600" y="102" width="80" height="28" class="fips"/>
<text x="640" y="121" text-anchor="middle" class="layer">FIPS</text>
<rect x="600" y="138" width="36" height="28" class="xport"/>
<text x="618" y="157" text-anchor="middle" class="layer">UDP</text>
<rect x="644" y="138" width="36" height="28" class="xport"/>
<text x="662" y="157" text-anchor="middle" class="layer">Tor</text>
<!-- Node E (destination) -->
<text x="800" y="30" text-anchor="middle" class="label">Node E</text>
<text x="800" y="46" text-anchor="middle" class="role">(destination)</text>
<rect x="750" y="56" width="100" height="130" class="node"/>
<rect x="760" y="66" width="80" height="28" class="app"/>
<text x="800" y="85" text-anchor="middle" class="layer">App</text>
<rect x="760" y="102" width="80" height="28" class="fips"/>
<text x="800" y="121" text-anchor="middle" class="layer">FIPS</text>
<rect x="760" y="138" width="80" height="28" class="xport"/>
<text x="800" y="157" text-anchor="middle" class="layer">Tor</text>
<!-- ============ LINK CONNECTIONS (U-shaped, all same depth) ============ -->
<!-- WiFi: A ↔ B -->
<path d="M 100 186 L 100 240 L 258 240 L 258 186" class="link"/>
<text x="179" y="256" text-anchor="middle" class="link-label">WiFi</text>
<text x="179" y="268" text-anchor="middle" class="link-enc">encrypted FMP link</text>
<!-- Ethernet: B ↔ C -->
<path d="M 302 186 L 302 240 L 438 240 L 438 186" class="link"/>
<text x="370" y="256" text-anchor="middle" class="link-label">Ethernet</text>
<text x="370" y="268" text-anchor="middle" class="link-enc">encrypted FMP link</text>
<!-- UDP/IP: C ↔ D -->
<path d="M 482 186 L 482 240 L 618 240 L 618 186" class="link"/>
<text x="550" y="256" text-anchor="middle" class="link-label">UDP/IP</text>
<text x="550" y="268" text-anchor="middle" class="link-enc">encrypted FMP link</text>
<!-- Tor: D ↔ E -->
<path d="M 662 186 L 662 240 L 800 240 L 800 186" class="link"/>
<text x="731" y="256" text-anchor="middle" class="link-label">Tor</text>
<text x="731" y="268" text-anchor="middle" class="link-enc">encrypted FMP link</text>
<!-- ============ END-TO-END SESSION (below links, no intersection) ============ -->
<line x1="100" y1="305" x2="800" y2="305" class="session"/>
<text x="450" y="298" text-anchor="middle" class="session-label">End-to-end FSP session encryption (A ↔ E)</text>
<!-- ============ LEGEND ============ -->
<line x1="60" y1="345" x2="120" y2="345" class="session"/>
<text x="132" y="349" class="legend" fill="#d0a040">FSP session encryption (end-to-end)</text>
<path d="M 60 370 L 60 380 L 120 380 L 120 370" class="link"/>
<text x="132" y="381" class="legend" fill="#5080c0">FMP link encryption (hop-by-hop)</text>
<!-- Caption -->
<text x="440" y="443" text-anchor="middle" class="caption">Multi-transport architecture — each link encrypted independently, session spans the full path</text>
</svg>
Reference in New Issue View Git Blame Copy Permalink