diff --git a/docs/design/fips-architecture.md b/docs/design/fips-architecture.md index aece3c3..05a4c42 100644 --- a/docs/design/fips-architecture.md +++ b/docs/design/fips-architecture.md @@ -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 diff --git a/docs/design/fips-design.md b/docs/design/fips-design.md index 260ed14..39196c4 100644 --- a/docs/design/fips-design.md +++ b/docs/design/fips-design.md @@ -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) diff --git a/docs/design/fips-protocol-flow.md b/docs/design/fips-protocol-flow.md index ed434f5..73a4621 100644 --- a/docs/design/fips-protocol-flow.md +++ b/docs/design/fips-protocol-flow.md @@ -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 diff --git a/docs/design/fips-routing.md b/docs/design/fips-routing.md index 9968061..df3ce18 100644 --- a/docs/design/fips-routing.md +++ b/docs/design/fips-routing.md @@ -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, // For return path caching dest_coords: Vec, // 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>, // 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, // Acknowledger's coords (for return caching) + + // Crypto session response (see fips-protocol-flow.md §6) + handshake_payload: Option>, // 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