SessionDatagram redesign: add src_addr, reclassify error signals

Add src_addr to SessionDatagram envelope (34-byte header: msg_type +
src_addr + dest_addr + hop_limit) so transit routers can route error
signals back to the packet's originator.

Reclassify CoordsRequired/PathBroken as link-layer error signals
(plaintext inside SessionDatagram) rather than e2e encrypted session
messages. Transit routers generate these when forwarding fails and
route them to src_addr; if source is also unreachable, drop silently.

Remove redundant src_addr/dest_addr/hop_limit from SessionSetup,
SessionAck, and DataPacket (now in envelope). DataPacket header
reduced from 36 to 4 bytes. Remove PathBroken.original_src.

Fix routing loop vulnerability: gate bloom filter path on having
cached dest_coords to prevent blind forwarding between peers.
Simplify select_best_candidate() to require coordinates.

Fix gossip protocol type codes (0x11->0x20, 0x12->0x30, 0x13->0x31)
for consistency across all design docs.

All 5 design docs updated and cross-checked for consistency.
335 tests pass, zero warnings.
This commit is contained in:
Johnathan Corgan
2026-02-12 11:32:45 +00:00
parent 2f8e97c0ab
commit d41009b778
9 changed files with 535 additions and 349 deletions
+173 -86
View File
@@ -423,26 +423,39 @@ handshakes succeed regardless of the responder's actual key parity. See
### 6.4 Handshake Integration with SessionSetup
The Noise handshake messages embed in SessionSetup/SessionAck:
The Noise handshake messages embed in SessionSetup/SessionAck, which are
carried inside a SessionDatagram envelope that provides addressing:
```text
SessionSetup {
// Routing portion (processed by routers)
src_coords: Vec<NodeAddr>,
dest_coords: Vec<NodeAddr>,
src_addr: Ipv6Addr,
dest_addr: Ipv6Addr,
SessionDatagram {
// Addressing (used by routers for forwarding and error routing)
src_addr: NodeAddr,
dest_addr: NodeAddr,
hop_limit: u8,
// Crypto portion (opaque to routers, processed by destination)
handshake_payload: Vec<u8>, // Noise IK message 1
// Payload: SessionSetup
payload: SessionSetup {
// Routing portion (processed by routers for cache warming)
src_coords: Vec<NodeAddr>,
dest_coords: Vec<NodeAddr>,
// Crypto portion (opaque to routers, processed by destination)
handshake_payload: Vec<u8>, // Noise IK message 1
}
}
SessionAck {
// Routing portion
src_coords: Vec<NodeAddr>, // Responder's coordinates
SessionDatagram {
src_addr: NodeAddr, // Responder
dest_addr: NodeAddr, // Original sender
hop_limit: u8,
// Crypto portion
handshake_payload: Vec<u8>, // Noise IK message 2
payload: SessionAck {
// Routing portion
src_coords: Vec<NodeAddr>, // Responder's coordinates
// Crypto portion
handshake_payload: Vec<u8>, // Noise IK message 2
}
}
```
@@ -529,44 +542,97 @@ for TreeAnnounce and FilterAnnounce wire formats.
## 8. Session Layer Wire Format
Session layer messages are carried inside `SessionDatagram` (type 0x40) at the
link layer. The session datagram is encrypted hop-by-hop with link keys, but
the inner payload is encrypted end-to-end with session keys.
link layer. The session datagram provides source and destination addressing for
multi-hop forwarding: it is encrypted hop-by-hop with link keys, and the inner
payload is either encrypted end-to-end with session keys (for data traffic) or
plaintext (for link-layer error signals from transit routers).
### 8.1 Message Type Codes
### 8.0 SessionDatagram Envelope
The SessionDatagram is a link-layer message (type 0x40) that carries all
routable traffic through the mesh. It provides the source and destination
addresses that transit routers use for forwarding decisions.
```text
┌─────────────────────────────────────────────────────────────────────────────┐
│ SESSION DATAGRAM (0x40) │
├────────┬──────────────────┬───────────┬─────────────────────────────────────┤
│ Offset │ Field │ Size │ Description │
├────────┼──────────────────┼───────────┼─────────────────────────────────────┤
│ 0 │ msg_type │ 1 byte │ 0x40 (link-layer SessionDatagram) │
│ 1 │ src_addr │ 16 bytes │ Source node_addr │
│ 17 │ dest_addr │ 16 bytes │ Destination node_addr │
│ 33 │ hop_limit │ 1 byte │ Decremented each hop │
│ 34 │ payload │ variable │ Session-layer message (see §8.1) │
└────────┴──────────────────┴───────────┴─────────────────────────────────────┘
Fixed header: 34 bytes
```
**src_addr**: The originator of the datagram. For data traffic, this is the
source endpoint. For error signals (CoordsRequired, PathBroken), this is the
transit router that generated the error. Transit routers use `src_addr` to
route error signals back to the packet's originator.
**dest_addr**: The intended recipient. Transit routers use this for next-hop
selection via `find_next_hop()`.
**hop_limit**: Decremented at each forwarding hop. When it reaches zero, the
datagram is dropped silently. This prevents infinite forwarding loops. Initial
value is configurable (default 64).
### 8.1 Payload Message Types
The SessionDatagram payload begins with a message type byte, followed by the
message-specific content.
**Session-layer messages** (end-to-end encrypted with session keys):
| Type Code | Message | Direction | Purpose |
|-----------|----------------|-----------|-----------------------------------|
| 0x00 | SessionSetup | S → D | Establish session + warm caches |
| 0x01 | SessionAck | D → S | Confirm session establishment |
| 0x10 | DataPacket | Both | Application data |
**Link-layer error signals** (plaintext, generated by transit routers):
| Type Code | Message | Direction | Purpose |
|-----------|----------------|-----------|-----------------------------------|
| 0x20 | CoordsRequired | R → S | Router cache miss |
| 0x21 | PathBroken | R → S | Greedy routing failed |
> **Address terminology**: The `src_addr` and `dest_addr` fields in session packet
> headers are node_addrs (16-byte truncated SHA-256 hashes of pubkeys). These are visible to
> intermediate routers for routing decisions. The actual FIPS addresses (pubkeys/npubs)
> are exchanged only during the Noise IK handshake and never appear in packet
> headers—routers cannot determine endpoint identities from the node_addrs they see.
Error signals are generated by transit router R and sent back to the source S
inside a *new* SessionDatagram with `src_addr=R, dest_addr=S`. They are
plaintext (not end-to-end encrypted) because the transit router has no session
with the source. Link-layer encryption protects them hop-by-hop.
> **Address terminology**: The `src_addr` and `dest_addr` fields in the
> SessionDatagram header are node_addrs (16-byte truncated SHA-256 hashes of
> pubkeys). These are visible to intermediate routers for routing decisions. The
> actual FIPS addresses (pubkeys/npubs) are exchanged only during the Noise IK
> handshake and never appear in packet headers—routers cannot determine endpoint
> identities from the node_addrs they see.
### 8.2 SessionSetup (0x00)
Establishes a crypto session and warms router coordinate caches along the path.
The `src_addr` and `dest_addr` are carried in the enclosing SessionDatagram
envelope (§8.0); the SessionSetup payload carries only coordinates and the
Noise handshake.
```text
┌─────────────────────────────────────────────────────────────────────────────┐
SESSION SETUP PACKET
│ SESSION SETUP PAYLOAD (inside SessionDatagram)
├────────┬──────────────────┬───────────┬─────────────────────────────────────┤
│ Offset │ Field │ Size │ Description │
├────────┼──────────────────┼───────────┼─────────────────────────────────────┤
│ 0 │ msg_type │ 1 byte │ 0x00 │
│ 1 │ flags │ 1 byte │ Bit 0: REQUEST_ACK │
│ │ │ │ Bit 1: BIDIRECTIONAL │
│ 2 │ src_addr 16 bytes │ Source node_addr
18dest_addr │ 16 bytes │ Destination node_addr
│ 34 │ src_coords_count │ 2 bytes │ u16 LE, number of src coord entries │
│ 36 │ src_coords │ 16 × n │ NodeAddr array (self → root) │
│ 2 │ src_coords_count2 bytes u16 LE, number of src coord entries
4src_coords │ 16 × n │ NodeAddr array (self → root)
│ ... │ dest_coords_count│ 2 bytes │ u16 LE, number of dest coord entries│
│ ... │ dest_coords │ 16 × m │ NodeAddr array (dest → root)
│ ... │ dest_coords │ 16 × m │ NodeAddr array (dest → root) │
│ ... │ handshake_len │ 2 bytes │ u16 LE, Noise payload length │
│ ... │ handshake_payload│ variable │ Noise IK msg1 (82 bytes typical) │
└────────┴──────────────────┴───────────┴─────────────────────────────────────┘
@@ -575,33 +641,32 @@ Establishes a crypto session and warms router coordinate caches along the path.
**Example** (depth 3 source, depth 4 destination, with Noise handshake):
```text
┌──────┬───────┬──────────────────┬──────────────────┬───────┬─────────────┐
│ 0x00 │ 0x01 │ src_addr │ dest_addr │ 0x03 │ src_coords │
type │ flags │ 16 bytes │ 16 bytes │ count │ 3 × 16 bytes
├──────┴───────┴──────────────────┴──────────────────┴───────┴─────────────┤
│ 0x04 │ dest_coords │ 0x52 │ handshake_payload │
│ count │ 4 × 16 bytes │ len=82│ 82 bytes (Noise IK msg1) │
└───────┴───────────────┴───────┴──────────────────────────────────────────┘
SessionDatagram { src: S, dest: D, hop_limit: 64 } +
┌──────┬───────┬───────┬─────────────┬───────┬───────────────┬───────┬───────┐
0x00 │ 0x01 │ 0x03 │ src_coords │ 0x04 │ dest_coords │ 0x52 │ noise
│ type │ flags │ count │ 3 × 16 bytes│ count │ 4 × 16 bytes │ len=82│ msg1 │
└──────┴───────┴───────┴─────────────┴───────┴───────────────┴───────┴───────┘
Total: 1 + 1 + 16 + 16 + 2 + 48 + 2 + 64 + 2 + 82 = 234 bytes
SessionDatagram header: 34 bytes
SessionSetup payload: 1 + 1 + 2 + 48 + 2 + 64 + 2 + 82 = 202 bytes
Total: 236 bytes
```
### 8.3 SessionAck (0x01)
Confirms session establishment and completes the Noise handshake.
Confirms session establishment and completes the Noise handshake. Addressing
is in the enclosing SessionDatagram envelope.
```text
┌─────────────────────────────────────────────────────────────────────────────┐
SESSION ACK PACKET
│ SESSION ACK PAYLOAD (inside SessionDatagram)
├────────┬──────────────────┬───────────┬─────────────────────────────────────┤
│ Offset │ Field │ Size │ Description │
├────────┼──────────────────┼───────────┼─────────────────────────────────────┤
│ 0 │ msg_type │ 1 byte │ 0x01 │
│ 1 │ flags │ 1 byte │ Reserved │
│ 2 │ src_addr │ 16 bytes │ Acknowledger's node_addr
18dest_addr │ 16 bytesOriginal sender's node_addr
│ 34 │ src_coords_count │ 2 bytes │ u16 LE │
│ 36 │ src_coords │ 16 × n │ Acknowledger's coords (for caching) │
│ 2 │ src_coords_count │ 2 bytesu16 LE
4src_coords │ 16 × n Acknowledger's coords (for caching)
│ ... │ handshake_len │ 2 bytes │ u16 LE, Noise payload length │
│ ... │ handshake_payload│ variable │ Noise IK msg2 (33 bytes typical) │
└────────┴──────────────────┴───────────┴─────────────────────────────────────┘
@@ -609,79 +674,90 @@ Confirms session establishment and completes the Noise handshake.
### 8.4 DataPacket (0x10)
Carries encrypted application data (typically IPv6 payloads).
Carries encrypted application data (typically IPv6 payloads). Addressing and
hop limit are in the enclosing SessionDatagram envelope.
```text
┌─────────────────────────────────────────────────────────────────────────────┐
DATA PACKET (Minimal Header)
│ DATA PACKET (Minimal Header, inside SessionDatagram)
├────────┬──────────────────┬───────────┬─────────────────────────────────────┤
│ Offset │ Field │ Size │ Description │
├────────┼──────────────────┼───────────┼─────────────────────────────────────┤
│ 0 │ msg_type │ 1 byte │ 0x10 │
│ 1 │ flags │ 1 byte │ Bit 0: COORDS_PRESENT │
│ 2 │ hop_limit │ 1 byte │ Decremented each hop
3reserved │ 1 byte │ Alignment padding
│ 4 │ payload_length │ 2 bytes │ u16 LE │
│ 6 │ src_addr │ 16 bytes │ Source node_addr │
│ 22 │ dest_addr │ 16 bytes │ Destination node_addr │
│ 38 │ payload │ variable │ Encrypted application data │
│ 2 │ payload_length │ 2 bytes │ u16 LE
4payload │ variable │ Encrypted application data
└────────┴──────────────────┴───────────┴─────────────────────────────────────┘
Minimal header: 38 bytes
Minimal header: 4 bytes (+ 34 SessionDatagram header = 38 bytes total)
```
When `COORDS_PRESENT` flag is set (route warming after CoordsRequired):
```text
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA PACKET (With Coordinates)
│ DATA PACKET (With Coordinates, inside SessionDatagram)
├────────┬──────────────────┬───────────┬─────────────────────────────────────┤
│ Offset │ Field │ Size │ Description │
├────────┼──────────────────┼───────────┼─────────────────────────────────────┤
│ 0 │ msg_type │ 1 byte │ 0x10 │
│ 1 │ flags │ 1 byte │ 0x01 (COORDS_PRESENT) │
│ 2 │ hop_limit │ 1 byte │ Decremented each hop
3reserved │ 1 byte │ Alignment padding
4payload_length │ 2 bytes u16 LE
│ 6 │ src_addr │ 16 bytes │ Source node_addr │
│ 22 │ dest_addr │ 16 bytes │ Destination node_addr │
│ 38 │ src_coords_count │ 2 bytes │ u16 LE │
│ 40 │ src_coords │ 16 × n │ Source coordinates │
│ 2 │ payload_length │ 2 bytes │ u16 LE
4src_coords_count │ 2 bytes │ u16 LE
6src_coords │ 16 × n │ Source coordinates
│ ... │ dest_coords_count│ 2 bytes │ u16 LE │
│ ... │ dest_coords │ 16 × m │ Destination coordinates │
│ ... │ payload │ variable │ Encrypted application data │
└────────┴──────────────────┴───────────┴─────────────────────────────────────┘
With depth-4 coords both directions: 38 + 2 + 64 + 2 + 64 = 170 bytes header
With depth-4 coords both directions:
DataPacket: 4 + 2 + 64 + 2 + 64 = 136 bytes header
+ SessionDatagram: 34 bytes
Total: 170 bytes header
```
### 8.5 CoordsRequired (0x20)
Sent by an intermediate router when it cannot forward a DataPacket due to
coordinate cache miss.
Sent by an intermediate router when it cannot forward a SessionDatagram due to
coordinate cache miss for the destination. This is a **link-layer error signal**:
the transit router generates a new SessionDatagram addressed back to the
original source, with the CoordsRequired payload in plaintext (not end-to-end
encrypted, since the transit router has no session with the source).
**Error routing**: Router R receives a SessionDatagram `{src: S, dest: D}` but
cannot route to D. R creates a new SessionDatagram `{src: R, dest: S}` carrying
a CoordsRequired payload, and calls `find_next_hop(S)` to route it back to S.
If R also cannot route to S, the error is dropped silently (no cascading errors).
**CoordsRequired payload** (inside SessionDatagram):
```text
┌─────────────────────────────────────────────────────────────────────────────┐
│ COORDS REQUIRED PACKET
│ COORDS REQUIRED PAYLOAD
├────────┬──────────────────┬───────────┬─────────────────────────────────────┤
│ Offset │ Field │ Size │ Description │
├────────┼──────────────────┼───────────┼─────────────────────────────────────┤
│ 0 │ msg_type │ 1 byte │ 0x20 │
│ 1 │ flags │ 1 byte │ Reserved │
│ 2 │ dest_addr │ 16 bytes │ The node_addr we couldn't route
│ 2 │ dest_addr │ 16 bytes │ The node_addr we couldn't route to
│ 18 │ reporter │ 16 bytes │ NodeAddr of reporting router │
└────────┴──────────────────┴───────────┴─────────────────────────────────────┘
Total: 34 bytes
Payload: 34 bytes
Wrapped in SessionDatagram: 34 + 34 = 68 bytes total
```
### 8.6 PathBroken (0x21)
Sent when greedy routing fails (no peer is closer to destination).
Sent when greedy routing fails (no peer is closer to destination). Like
CoordsRequired, this is a **link-layer error signal** carried inside a new
SessionDatagram addressed back to the original source.
**PathBroken payload** (inside SessionDatagram):
```text
┌─────────────────────────────────────────────────────────────────────────────┐
│ PATH BROKEN PACKET
│ PATH BROKEN PAYLOAD
├────────┬──────────────────┬───────────┬─────────────────────────────────────┤
│ Offset │ Field │ Size │ Description │
├────────┼──────────────────┼───────────┼─────────────────────────────────────┤
@@ -714,34 +790,45 @@ A DataPacket from source S to destination D, transiting router R:
│ │ Decrypt with S↔R link keys │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ LINK MESSAGE (plaintext for R) │ │
│ ├───────────┬───────────────────────────────────────────────────────────┤ │
│ │ 0x40 │ SessionDatagram payload │ │
│ │ msg_type │ (routable by R, encrypted end-to-end) │ │
│ └───────────┴───────────────────────────────────────────────────────────┘ │
│ │ SESSION DATAGRAM (0x40) — plaintext for R │ │
│ ├───────────┬────────────────────────────────────────────────────────┤ │
│ │ 0x40 │ src_addr │ dest_addr │ hop_limit│ payload │ │
│ │ msg_type │ S (16 bytes) │ D (16 bytes) │ 64 │ (session msg) │ │
│ └───────────┴────────────────────────────────────────────────────────┘ │
│ │ │
│ │ R reads src_addr + dest_addr for routing │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ SESSION LAYER (S↔D encrypted) │ │
│ │ SESSION LAYER PAYLOAD (S↔D encrypted) │ │
│ ├───────────┬───────┬──────────┬──────────┬─────────────────────────────┤ │
│ │ 0x10 │ flags │ hop_limit│ pay_len │ src_addr │ dest_addr │ │
│ │ DataPacket│ 0x00 │ 64 │ 1400 │ 16 bytes │ 16 bytes │ │
───────────┴───────┴──────────┴──────────┴────────────────────────────
│ │ │ │
│ │ ENCRYPTED PAYLOAD (S↔D session keys) │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ IPv6 packet or application data │ │ │
│ │ │ (+ 16-byte AEAD tag) │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │ 0x10 │ flags │ reserved │ pay_len │ encrypted application data │ │
│ │ DataPacket│ 0x00 │ 0x00 │ 1400 │ (S↔D session keys + tag) │ │
───────────┴───────┴──────────┴──────────┴────────────────────────────
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Router R can see: dest_addr (for routing decision)
Router R cannot see: payload contents (encrypted with S↔D keys)
Router R can see: src_addr, dest_addr, hop_limit (for routing/error signaling)
Router R cannot see: payload contents (encrypted with S↔D session keys)
```
### 8.7.1 Error Routing Example
When router R cannot forward a SessionDatagram from S to D:
```text
1. R receives SessionDatagram { src: S, dest: D, payload: DataPacket{...} }
2. R has no cached coordinates for D and no bloom filter hit
3. R creates NEW SessionDatagram:
{ src: R, dest: S, hop_limit: 64,
payload: CoordsRequired { dest: D, reporter: R } }
4. R calls find_next_hop(S) to route the error back
5. If R can also not route to S: drop silently (no cascading errors)
```
This avoids the need for transit routers to have end-to-end sessions with
the source. The `src_addr` field in the original SessionDatagram tells the
transit router where to send the error.
### 8.8 Encoding Rules
- All multi-byte integers are **little-endian**