docs: add PRD for hard NAT traversal (port prediction + birthday attack)
4-phase design: A. Port allocation pattern detection (sequential vs random) B. Sequential port prediction (~80% success, <2s) C. Birthday attack for random NATs (98% success, ~10s) D. Hybrid waterfall with background relay-to-direct upgrade Taskmaster tasks #84-87 added. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
220
docs/PRD-hard-nat.md
Normal file
220
docs/PRD-hard-nat.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# PRD: Hard NAT Traversal (Port Prediction + Birthday Attack)
|
||||
|
||||
> Phase: Design
|
||||
> Status: Not started
|
||||
> Crate: wzp-client, wzp-proto
|
||||
|
||||
## Problem
|
||||
|
||||
When both peers are behind **symmetric NATs** (endpoint-dependent mapping), standard hole-punching fails because the external port changes per destination. Our Phase 8.2 port mapping (NAT-PMP/PCP/UPnP) solves this when the router supports it (~70% of consumer routers), but the remaining ~30% — plus corporate firewalls, cloud NATs (AWS/Azure), and carrier-grade NATs — fall back to relay.
|
||||
|
||||
Tailscale tackles this with two techniques:
|
||||
1. **Port prediction** for NATs with sequential allocation patterns
|
||||
2. **Birthday attack** for NATs with random allocation
|
||||
|
||||
Both are viable when **at least one peer has a predictable NAT** (easy+hard pair). When **both** peers have fully random symmetric NATs, even Tailscale falls back to relay.
|
||||
|
||||
## Background: How Symmetric NATs Allocate Ports
|
||||
|
||||
| Pattern | Behavior | Prevalence | Traversal |
|
||||
|---------|----------|------------|-----------|
|
||||
| **Sequential** | port N, N+1, N+2... per new flow | ~40% of symmetric NATs (home routers) | Port prediction viable |
|
||||
| **Random** | truly random port per flow | ~50% (enterprise, cloud, CGNAT) | Birthday attack only |
|
||||
| **Port-preserving** | same as source port when possible | ~10% (behaves like cone NAT) | Standard hole-punch works |
|
||||
|
||||
## Solution Overview
|
||||
|
||||
### Phase A: NAT Port Allocation Pattern Detection
|
||||
|
||||
Before attempting hard NAT traversal, detect whether the NAT allocates ports sequentially or randomly. This determines which strategy to use.
|
||||
|
||||
**Method**: Send 5 STUN Binding Requests from the same source socket to 5 different STUN servers. Collect the 5 observed external ports. Analyze:
|
||||
|
||||
```
|
||||
Ports: [40001, 40002, 40003, 40004, 40005] → Sequential (delta=1)
|
||||
Ports: [40001, 40003, 40005, 40007, 40009] → Sequential (delta=2)
|
||||
Ports: [40001, 52847, 19432, 61203, 8847] → Random
|
||||
Ports: [4433, 4433, 4433, 4433, 4433] → Port-preserving (cone-like)
|
||||
```
|
||||
|
||||
Classification:
|
||||
- All same port → `PortPreserving` (use standard hole-punch)
|
||||
- Consistent delta between consecutive ports → `Sequential { delta: i16 }`
|
||||
- No pattern → `Random`
|
||||
|
||||
**New struct**:
|
||||
```rust
|
||||
pub enum PortAllocation {
|
||||
PortPreserving,
|
||||
Sequential { delta: i16 },
|
||||
Random,
|
||||
Unknown,
|
||||
}
|
||||
```
|
||||
|
||||
Add to `NetcheckReport` and `NatDetection`.
|
||||
|
||||
### Phase B: Port Prediction (Sequential NATs)
|
||||
|
||||
When the NAT is sequential, we can **predict** the next external port:
|
||||
|
||||
1. Client sends a STUN probe → observes external port P
|
||||
2. Client knows the NAT will assign P+delta for the next outbound flow
|
||||
3. Client tells peer (via relay or chat): "dial me at `my_ip:(P + delta * N)`" where N is the number of flows the client will open before the peer's packet arrives
|
||||
4. Client opens a QUIC connection to the peer's predicted port at the same time
|
||||
5. If the prediction lands within a small window, the QUIC handshake succeeds
|
||||
|
||||
**Timing is critical**: both peers must probe, predict, and dial within a tight window (~500ms) so the port prediction doesn't drift.
|
||||
|
||||
**Coordination via relay** (or out-of-band chat):
|
||||
```
|
||||
SignalMessage::HardNatProbe {
|
||||
call_id: String,
|
||||
/// My observed port sequence (last 3 ports, most recent first)
|
||||
port_sequence: Vec<u16>,
|
||||
/// My detected allocation pattern
|
||||
allocation: PortAllocation,
|
||||
/// Timestamp (ms since epoch) — for synchronization
|
||||
probe_time_ms: u64,
|
||||
/// My external IP (from STUN)
|
||||
external_ip: String,
|
||||
}
|
||||
```
|
||||
|
||||
Both peers exchange `HardNatProbe`, then simultaneously:
|
||||
1. Each predicts the other's next port: `peer_ip:(peer_last_port + peer_delta * offset)`
|
||||
2. Each opens N parallel QUIC connections to predicted port range: `[predicted - 2, predicted + 2]`
|
||||
3. First successful handshake wins
|
||||
|
||||
**Expected success rate**: ~80% for sequential NATs with consistent delta, within 2-3 seconds.
|
||||
|
||||
### Phase C: Birthday Attack (Random NATs)
|
||||
|
||||
When the NAT is random, port prediction is impossible. Instead, exploit the **birthday paradox**:
|
||||
|
||||
**Math**: With N ports open on side A and M probes from side B into a 65536-port space:
|
||||
- N=256, M=256: P(collision) ≈ 1 - e^(-256*256/65536) ≈ 63%
|
||||
- N=256, M=512: P(collision) ≈ 1 - e^(-256*512/65536) ≈ 87%
|
||||
- N=256, M=1024: P(collision) ≈ 1 - e^(-256*1024/65536) ≈ 98%
|
||||
|
||||
**Implementation**:
|
||||
|
||||
1. **Acceptor side** (easy NAT or the side with more ports available):
|
||||
- Open 256 UDP sockets bound to random ports
|
||||
- For each socket, send one STUN probe to learn its external port
|
||||
- Report all 256 external ports to the peer
|
||||
|
||||
2. **Dialer side** (hard NAT):
|
||||
- Send 1024 QUIC Initial packets to random ports on the Acceptor's external IP
|
||||
- Rate: 100-200 packets/sec to avoid triggering rate limits
|
||||
- Duration: ~5-10 seconds
|
||||
|
||||
3. **Collision detection**:
|
||||
- When one of the Dialer's packets hits one of the Acceptor's open ports, the QUIC handshake begins
|
||||
- The Acceptor sees an incoming Initial on one of its 256 sockets
|
||||
|
||||
**Problem for VoIP**: This takes 5-10 seconds even at high probe rates. For a phone call, this means a long "connecting..." phase. Acceptable as a last resort before relay fallback.
|
||||
|
||||
### Phase D: Hybrid Strategy
|
||||
|
||||
Combine all techniques in a waterfall:
|
||||
|
||||
```
|
||||
1. Port mapping (NAT-PMP/PCP/UPnP) → <100ms [Phase 8.2, done]
|
||||
↓ failed
|
||||
2. Standard hole-punch (cone NAT) → <500ms [Phase 3-6, done]
|
||||
↓ failed (symmetric NAT detected)
|
||||
3. Port prediction (sequential NAT) → <2s [Phase A+B, new]
|
||||
↓ failed (random NAT detected)
|
||||
4. Birthday attack (one side random) → <10s [Phase C, new]
|
||||
↓ failed (both sides random)
|
||||
5. Relay fallback → always [Phase 1, done]
|
||||
```
|
||||
|
||||
The relay path starts **immediately in parallel** with all direct attempts (existing 500ms head-start architecture). The user hears audio via relay while the harder traversal techniques probe in the background. If a direct path is found, the call seamlessly upgrades (using the Phase 8.3 transport hot-swap mechanism).
|
||||
|
||||
## QUIC-Specific Challenges
|
||||
|
||||
### 1. Connection ID Mismatch
|
||||
QUIC's Initial packet contains a random Destination Connection ID. When birthday-attack probes land on the Acceptor's socket, the CID won't match any expected value. Quinn handles this via its `Endpoint` which accepts any incoming Initial — but we need to ensure the Endpoint is in server mode on all 256 ports.
|
||||
|
||||
**Solution**: Use quinn's `Endpoint` with a server config on each socket. Quinn's accept logic handles unknown CIDs correctly.
|
||||
|
||||
### 2. Probe Packet Format
|
||||
Birthday attack probes must be valid QUIC Initial packets (not raw UDP). Quinn's `Endpoint::connect()` sends a proper Initial, so each probe is a real connection attempt. Failed probes time out naturally.
|
||||
|
||||
### 3. Stateful Connections
|
||||
Unlike WireGuard (stateless), each QUIC probe creates connection state. With 1024 probes, that's 1024 half-open connections. Must aggressively abort losers once one succeeds.
|
||||
|
||||
**Solution**: Use `JoinSet` (existing pattern in `dual_path.rs`) and `abort_all()` on first success.
|
||||
|
||||
### 4. NAT Pinhole Lifetime
|
||||
QUIC Initial retransmission timer (1s default) may exceed the NAT pinhole lifetime on aggressive NATs. One probe per port may not be enough.
|
||||
|
||||
**Solution**: Send 2-3 Initials per predicted port, 200ms apart.
|
||||
|
||||
## Signal Protocol
|
||||
|
||||
New variants:
|
||||
|
||||
```rust
|
||||
/// Hard NAT probe coordination — exchanged before birthday attack.
|
||||
HardNatProbe {
|
||||
call_id: String,
|
||||
/// Last 5 observed external ports (most recent first).
|
||||
port_sequence: Vec<u16>,
|
||||
/// Detected allocation pattern.
|
||||
allocation: String, // "sequential:1", "sequential:2", "random", "preserving"
|
||||
/// Probe timestamp for synchronization (ms since epoch).
|
||||
probe_time_ms: u64,
|
||||
/// External IP from STUN.
|
||||
external_ip: String,
|
||||
}
|
||||
|
||||
/// Hard NAT birthday attack coordination.
|
||||
HardNatBirthdayStart {
|
||||
call_id: String,
|
||||
/// Number of ports opened by the acceptor side.
|
||||
acceptor_port_count: u16,
|
||||
/// External ports the acceptor has open (for targeted probing).
|
||||
/// Only sent if port_count is small enough to enumerate.
|
||||
acceptor_ports: Vec<u16>,
|
||||
/// "start probing now" timestamp.
|
||||
start_at_ms: u64,
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with Existing Architecture
|
||||
|
||||
- **Netcheck**: `NetcheckReport` gains `port_allocation: PortAllocation` field
|
||||
- **IceAgent**: `gather()` includes port allocation detection; `re_gather()` re-probes on network change
|
||||
- **dual_path**: `race()` extended with hard-NAT probe phase between standard hole-punch timeout and relay commitment
|
||||
- **Desktop**: `place_call` / `answer_call` exchange `HardNatProbe` when both sides report `SymmetricPort` NAT type
|
||||
|
||||
## Effort Estimate
|
||||
|
||||
| Phase | Scope | Effort |
|
||||
|-------|-------|--------|
|
||||
| A | Port allocation pattern detection | 1 day |
|
||||
| B | Sequential port prediction + coordination | 2 days |
|
||||
| C | Birthday attack (256 sockets + 1024 probes) | 3 days |
|
||||
| D | Hybrid waterfall + background upgrade | 2 days |
|
||||
|
||||
**Total**: ~8 days. Recommend starting with Phase A (detection) which is useful for netcheck even without the attack. Phase B (sequential prediction) covers ~40% of hard NATs with minimal complexity. Phase C (birthday) is the most complex and lowest ROI.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Port allocation detection correctly classifies sequential vs random on test routers
|
||||
- Sequential port prediction achieves >70% direct connection rate on sequential-NAT routers
|
||||
- Birthday attack achieves >90% within 10 seconds when one peer has cone NAT
|
||||
- Relay-to-direct upgrade is seamless (no audio gap) via Phase 8.3 transport hot-swap
|
||||
- No regression in call setup time for cone-NAT pairs (the common case)
|
||||
|
||||
## References
|
||||
|
||||
- [Tailscale: How NAT traversal works](https://tailscale.com/blog/how-nat-traversal-works)
|
||||
- [Tailscale: NAT traversal improvements pt.1](https://tailscale.com/blog/nat-traversal-improvements-pt-1)
|
||||
- [Tailscale: NAT traversal improvements pt.2 — cloud environments](https://tailscale.com/blog/nat-traversal-improvements-pt-2-cloud-environments)
|
||||
- RFC 4787: NAT Behavioral Requirements for Unicast UDP
|
||||
- RFC 5245: ICE (Interactive Connectivity Establishment)
|
||||
- Birthday problem: P(collision) = 1 - e^(-n²/2m) where n=probes, m=port space
|
||||
Reference in New Issue
Block a user