laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-07-22 07:48:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Session 40: Reconcile design docs with protocol flow decisions

Browse Source 
Align terminology and cross-references across all FIPS design documents
based on decisions made in fips-protocol-flow.md (Session 39).

Key changes:
- Distinguish "Routing Session" (hop-by-hop cache) from "Crypto Session"
  (end-to-end Noise KK encryption) throughout all docs
- Add handshake_payload field to SessionSetup/SessionAck for combined
  establishment of routing and crypto sessions
- Update fips-design.md encryption section to reference Noise KK
- Add SessionSetup (0x06), SessionAck (0x07), CoordsRequired (0x08)
  message types
- Add Crypto Session Management config section to fips-architecture.md
- Add cross-references to fips-protocol-flow.md in all design docs
- Update reconciliation tracking in protocol-flow.md §7
This commit is contained in:
Johnathan Corgan
2026-01-31 18:28:14 +00:00
parent 5d190885ec
commit b54c347e76
4 changed files with 108 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/design/fips-architecture.md
View File

@@ -791,7 +791,12 @@ the limit but need not enforce it strictly.
The discovery cache stores coordinates learned from LookupResponses for destinations
this node wants to reach. This is the primary cache for endpoint nodes.
### Session Management
### Routing Session Management
> **Terminology note**: These parameters configure *routing sessions*—hop-by-hop
> cached state at intermediate routers. For *crypto session* (end-to-end
> encryption) parameters, see the Crypto Session section below. See
> [fips-protocol-flow.md](fips-protocol-flow.md) §5 for the distinction.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
@@ -805,6 +810,22 @@ this node as a transit router. Larger than discovery cache since routers see tra
for many destinations. Both caches are part of Node.coord_cache; these parameters
configure the same underlying cache but are grouped by purpose.
### Crypto Session Management
> **Note**: Crypto sessions provide end-to-end authenticated encryption using
> Noise KK. See [fips-protocol-flow.md](fips-protocol-flow.md) §6 for details.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `crypto.session.max_entries` | u32 | 10000 | Max concurrent crypto sessions |
| `crypto.session.idle_timeout` | duration | 3600s | Expire idle sessions |
| `crypto.session.rekey_interval` | duration | 86400s | Rekey after this interval |
| `crypto.session.rekey_bytes` | u64 | 0 | Rekey after N bytes (0 = disabled) |
Crypto sessions are keyed by remote npub and survive transport changes. The
handshake is carried within SessionSetup/SessionAck messages (combined
establishment).
### Peer Defaults
| Parameter | Type | Default | Description |
@@ -888,6 +909,7 @@ configure the same underlying cache but are grouped by purpose.
## References
- [fips-design.md](fips-design.md) — Overall FIPS protocol design
- [fips-protocol-flow.md](fips-protocol-flow.md) — Traffic flow, session terminology, crypto sessions
- [fips-transports.md](fips-transports.md) — Transport protocol characteristics
- [fips-routing.md](fips-routing.md) — Routing, Bloom filters, discovery
- [spanning-tree-dynamics.md](spanning-tree-dynamics.md) — Tree protocol dynamics

35
docs/design/fips-design.md
View File

@@ -123,6 +123,13 @@ adversary claims to be a node it doesn't control.
> without built-in encryption or key exchange (radio links, serial connections).
> On transports that provide identity-binding encryption, this protocol may be
> skipped if the transport key is bound to the peer's npub.
>
> **Terminology note**: *Peer authentication* (this section) is hop-by-hop—it
> verifies that a direct peer is who they claim to be. This is distinct from
> *crypto sessions* (see [fips-protocol-flow.md](fips-protocol-flow.md) §6),
> which provide end-to-end authenticated encryption between source and
> destination using Noise KK. Both layers are necessary: peer auth secures the
> local link; crypto sessions secure the full path.
```text
Initiator (A) Responder (B)
@@ -591,9 +598,15 @@ A single node may have multiple transports of different types:
| 0x03 | Lookup | Destination lookup request |
| 0x04 | LookupResponse | Coordinates for requested key |
| 0x05 | PathBroken | Route failure notification |
| 0x06 | SessionSetup | Routing session + crypto handshake init |
| 0x07 | SessionAck | Routing session ack + crypto response |
| 0x08 | CoordsRequired | Router cache miss notification |
| 0x10 | Traffic | Encrypted application data |
| 0x11 | TrafficAck | Delivery acknowledgement |
See [fips-routing.md](fips-routing.md) Part 4 for routing session details and
[fips-protocol-flow.md](fips-protocol-flow.md) §5-6 for combined establishment.
### TreeAnnounce
```
@@ -673,7 +686,17 @@ LookupResponse {
- QUIC: Built-in TLS
- Radio: Pre-shared key or public-key encryption
**End-to-end encryption**: Application layer uses NIP-44 or similar for payload encryption.
**End-to-end encryption**: FIPS provides a crypto session layer using the Noise
Protocol Framework with secp256k1. The Noise KK pattern provides mutual
authentication and forward secrecy in a single round-trip, since both parties
know each other's npub before initiating. Session keys are used with
ChaCha20-Poly1305 AEAD for all data packets; no per-packet signatures are
required (AEAD tag provides integrity and authenticity). See
[fips-protocol-flow.md](fips-protocol-flow.md) §6 for crypto session details.
> **Note**: Applications may use additional encryption (NIP-44) for
> application-layer privacy, but FIPS-layer encryption protects against
> intermediate router observation.
---
@@ -704,6 +727,16 @@ LookupResponse {
## References
### FIPS Design Documents
- [fips-protocol-flow.md](fips-protocol-flow.md) — Traffic flow, session terminology, crypto sessions
- [fips-routing.md](fips-routing.md) — Bloom filters, discovery, routing sessions
- [fips-architecture.md](fips-architecture.md) — Software architecture, configuration
- [fips-transports.md](fips-transports.md) — Transport protocol characteristics
- [spanning-tree-dynamics.md](spanning-tree-dynamics.md) — Tree protocol dynamics
### External References
- [Yggdrasil Network](https://yggdrasil-network.github.io/)
- [Yggdrasil v0.5 Release Notes](https://yggdrasil-network.github.io/2023/10/22/upcoming-v05-release.html)
- [Ironwood Routing Library](https://github.com/Arceliar/ironwood)

31
docs/design/fips-protocol-flow.md
View File

@@ -685,17 +685,34 @@ this should be updated to reflect AEAD-only authentication.
This section tracks items that need reconciliation with existing design docs
or earlier sections of this document.
### 7.1 Pending Updates
### 7.1 Completed Updates (Session 40)
| Location | Status | Notes |
|----------|--------|-------|
| §3.1 | ✓ Done | Updated to AEAD authentication |
| fips-routing.md §Part 4 | Pending | Clarify "Session" → "Routing Session" per §5.4 |
| fips-routing.md Part 4 | ✓ Done | Renamed to "Routing Session Establishment", added terminology note |
| fips-routing.md SessionSetup/Ack | ✓ Done | Added `handshake_payload` for crypto handshake |
| fips-design.md §7 Encryption | ✓ Done | Updated to reference Noise KK instead of NIP-44 |
| fips-design.md §6 Messages | ✓ Done | Added SessionSetup, SessionAck, CoordsRequired types |
| fips-design.md §1 Peer Auth | ✓ Done | Added terminology note distinguishing peer auth from crypto sessions |
| fips-architecture.md Config | ✓ Done | Renamed to "Routing Session", added "Crypto Session" section |
### 7.2 Design Doc Alignment
### 7.2 Cross-References Added
The following decisions in this document affect existing design docs:
All design docs now reference fips-protocol-flow.md in their References sections:
1. **fips-routing.md**: "Session" → "Routing Session" terminology
2. **Combined establishment** (§5.5): SessionSetup carries crypto handshake
3. **Noise KK**: Replaces any unspecified handshake references
- fips-design.md
- fips-routing.md
- fips-architecture.md
### 7.3 Design Doc Alignment Summary
The following decisions from this document have been propagated:
1. **Session terminology** (§5.4): "Routing Session" vs "Crypto Session" distinction
now consistent across all docs
2. **Combined establishment** (§5.5): SessionSetup/SessionAck carry optional
`handshake_payload` for Noise KK handshake
3. **Noise KK** (§6): fips-design.md encryption section updated, new config
parameters added to fips-architecture.md
4. **Peer auth vs crypto session**: fips-design.md §1 clarifies the distinction

36
docs/design/fips-routing.md
View File

@@ -343,14 +343,20 @@ No global routing tables. Each node makes purely local decisions.
---
## Part 4: Session Establishment
## Part 4: Routing Session Establishment
### Session Purpose
> **Terminology note**: This section describes *routing sessions*—hop-by-hop
> cached state at intermediate routers. FIPS also has *crypto sessions*—end-to-end
> authenticated encryption between source and destination. See
> [fips-protocol-flow.md](fips-protocol-flow.md) §5 for the distinction and §6
> for crypto session details.
### Routing Session Purpose
Establish cached coordinate state along a path so that subsequent data packets
can omit coordinates, minimizing per-packet overhead.
### Session Lifecycle
### Routing Session Lifecycle
```text
┌─────────────────────────────────────────────────────────────────┐
@@ -362,16 +368,20 @@ can omit coordinates, minimizing per-packet overhead.
└─────────────────────────────────────────────────────────────────┘
```
### Session Message Formats
### Routing Session Message Formats
```rust
/// Establishes cached state along path
/// Establishes cached state along path; optionally carries crypto handshake
struct SessionSetup {
src_addr: Ipv6Addr,
dest_addr: Ipv6Addr,
src_coords: Vec<NodeId>, // For return path caching
dest_coords: Vec<NodeId>, // For forward path routing
flags: SessionFlags,
// Crypto session establishment (see fips-protocol-flow.md §6)
// Opaque to routers; only processed by destination
handshake_payload: Option<Vec<u8>>, // Noise KK message 1
}
struct SessionFlags {
@@ -379,11 +389,14 @@ struct SessionFlags {
bidirectional: bool, // Set up both directions
}
/// Confirms session establishment
/// Confirms session establishment; optionally carries crypto response
struct SessionAck {
src_addr: Ipv6Addr,
dest_addr: Ipv6Addr,
src_coords: Vec<NodeId>, // Acknowledger's coords (for return caching)
// Crypto session response (see fips-protocol-flow.md §6)
handshake_payload: Option<Vec<u8>>, // Noise KK message 2
}
/// Minimal data packet
@@ -416,7 +429,7 @@ struct CoordsRequired {
Comparable to IPv6 (40 bytes). No coordinates in data packets.
### Session Setup Flow
### Routing Session Setup Flow
```text
S R1 R2 D
@@ -544,11 +557,15 @@ impl Sender {
| FilterAnnounce | Bloom filter propagation | ~4.1 KB | Topology changes |
| LookupRequest | Discover coordinates | ~300 bytes | First contact with distant node |
| LookupResponse | Return coordinates | ~400 bytes | Reply to discovery |
| SessionSetup | Warm router caches | ~400-600 bytes | Before data transfer |
| SessionAck | Confirm session | ~300 bytes | Optional confirmation |
| SessionSetup | Warm router caches + crypto init | ~400-700 bytes | Before data transfer |
| SessionAck | Confirm session + crypto response | ~300-500 bytes | Session confirmation |
| DataPacket | Application data | 36 bytes + payload | Bulk of traffic |
| CoordsRequired | Request retransmit | ~50 bytes | Cache miss recovery |
> **Note**: SessionSetup/SessionAck sizes vary based on coordinate depth and
> whether they carry crypto handshake payloads (combined establishment per
> [fips-protocol-flow.md](fips-protocol-flow.md) §5.5).
---
## Part 6: Traffic Analysis
@@ -604,5 +621,6 @@ When nodes join/leave:
## References
- [fips-design.md](fips-design.md) — Overall FIPS architecture
- [fips-protocol-flow.md](fips-protocol-flow.md) — Traffic flow, crypto sessions, terminology
- [fips-transports.md](fips-transports.md) — Transport protocol characteristics
- [spanning-tree-dynamics.md](spanning-tree-dynamics.md) — Tree protocol details