NAT_TRAVERSAL_old.md
1 # NAT Traversal & Perfect Forward Secrecy 2 3 Technical deep-dive into Abzu's network traversal and cryptographic key exchange systems. 4 5 --- 6 7 ## 1. Sovereign STUN Server 8 9 Abzu includes a **zero-log STUN server** that enables nodes to discover their public-facing address without relying on external infrastructure. 10 11 ### Architecture 12 13 ``` 14 ┌─────────────────┐ UDP :3478 ┌──────────────────┐ 15 │ Abzu Client │ ────────────────────► │ Abzu Daemon │ 16 │ (behind NAT) │ ◄──────────────────── │ (STUN Server) │ 17 │ │ XorMappedAddress │ │ 18 └─────────────────┘ └──────────────────┘ 19 ``` 20 21 ### Location 22 23 - **Module**: `abzu-daemon/src/stun.rs` 24 - **Binding**: UDP port 3478 (RFC 5389 default) 25 - **Startup**: Concurrent with daemon's main event loop 26 27 ### Protocol Flow 28 29 1. Client sends `BindingRequest` with random 96-bit transaction ID 30 2. Server parses request via `stun_proto` crate 31 3. Server responds with `XorMappedAddress` containing client's observed IP:port 32 4. Client now knows its public endpoint 33 34 ### Zero-Log Policy 35 36 The STUN server implements strict privacy: 37 38 ```rust 39 // No source IP logging 40 // No transaction ID logging 41 // No timestamps 42 // Stateless operation - no binding tables 43 ``` 44 45 ### Code Highlights 46 47 ```rust 48 pub fn build_binding_response( 49 source: SocketAddr, 50 transaction_id: TransactionId, 51 ) -> Option<Vec<u8>> { 52 let mtype = MessageType::new(BINDING, Class::Success); 53 let mut builder = Message::builder(mtype, transaction_id, MessageWriteVec::new()); 54 55 // XOR masking per RFC 5389 - prevents ALG interference 56 let xma = XorMappedAddress::new(source, transaction_id); 57 builder.add_attribute(&xma).ok()?; 58 59 Some(builder.into_owned().to_vec()) 60 } 61 ``` 62 63 --- 64 65 ## 2. NAT Type Detection 66 67 Before establishing peer connections, Abzu determines the NAT type to select the appropriate traversal strategy. 68 69 ### NAT Classification 70 71 | Type | Behavior | Traversability | 72 |------|----------|----------------| 73 | **Full Cone** | Any external host can send to mapped port | ✅ Easy | 74 | **Restricted Cone** | Only hosts the client contacted can reply | ⚠️ Moderate | 75 | **Port Restricted** | Only exact IP:port pairs can reply | ⚠️ Hard | 76 | **Symmetric** | Different mapping per destination | ❌ Relay needed | 77 78 ### Detection Algorithm 79 80 ``` 81 ┌──────────────────────────────────────────────────────────────┐ 82 │ NAT Detection Flow │ 83 ├──────────────────────────────────────────────────────────────┤ 84 │ │ 85 │ 1. Query STUN Server A ──► Get mapped address X:P1 │ 86 │ │ 87 │ 2. Query STUN Server B ──► Get mapped address Y:P2 │ 88 │ │ 89 │ 3. Compare results: │ 90 │ • X:P1 == Y:P2 → Cone NAT (predictable) │ 91 │ • X:P1 != Y:P2 → Symmetric NAT (unpredictable) │ 92 │ │ 93 └──────────────────────────────────────────────────────────────┘ 94 ``` 95 96 ### Configuration 97 98 ```rust 99 pub struct NatConfig { 100 pub stun_servers: Vec<String>, // Prioritizes localhost:3478 101 pub timeout: Duration, // Default: 3s 102 pub retries: u32, // Default: 3 103 } 104 ``` 105 106 ### Retry Logic 107 108 Exponential backoff with jitter prevents thundering herd: 109 110 ```rust 111 let delay = base_timeout * 2^attempt + random_jitter(0..100ms) 112 ``` 113 114 --- 115 116 ## 3. Hole Punching 117 118 For nodes behind NAT, Abzu performs coordinated hole punching to establish direct connections. 119 120 ### Rendezvous Protocol 121 122 ``` 123 Node A Relay Node B 124 │ │ │ 125 │── Announce(A_pub) ────►│ │ 126 │ │◄── Announce(B_pub) ────│ 127 │◄── PeerInfo(B_pub) ────│ │ 128 │ │──── PeerInfo(A_pub) ──►│ 129 │ │ │ 130 │◄═══════════════════════ Simultaneous Open ═════════════════════►│ 131 │ │ │ 132 ``` 133 134 ### Address Exchange Wire Format 135 136 ```rust 137 AbzuFrame::Announce { 138 peer_id: [u8; 32], // Ed25519 public key 139 addresses: Vec<String>, // Candidate addresses 140 nat_type: NatType, // Detected NAT classification 141 timestamp: u64, // Unix epoch, validated ±5 min 142 } 143 ``` 144 145 ### Timestamp Validation 146 147 Announcements are rejected if older than 5 minutes to prevent replay attacks: 148 149 ```rust 150 let age = now.saturating_sub(announce.timestamp); 151 if age > 300 { 152 return Err(TransportError::StaleAnnouncement); 153 } 154 ``` 155 156 --- 157 158 ## 4. Perfect Forward Secrecy 159 160 Every FakeTLS connection performs **ephemeral X25519 key exchange**, ensuring that compromise of the pre-shared key (PSK) doesn't expose past sessions. 161 162 ### Cryptographic Stack 163 164 | Layer | Algorithm | Purpose | 165 |-------|-----------|---------| 166 | Key Agreement | X25519 | Ephemeral Diffie-Hellman | 167 | Key Derivation | HKDF-SHA256 | Session key extraction | 168 | Encryption | ChaCha20-Poly1305 | Authenticated encryption | 169 170 ### Module Structure 171 172 ``` 173 abzu-transport/src/ 174 ├── key_exchange.rs # EphemeralKeypair, derive_session_key() 175 └── transports/ 176 └── fake_tls.rs # connect_pfs(), accept_pfs() 177 ``` 178 179 ### Handshake Sequence 180 181 ``` 182 Client Server 183 │ │ 184 │ 1. Generate ephemeral X25519 keypair │ 185 │ 2. Embed public key in ClientHello │ 186 │ │ 187 │──────── ClientHello [client_pub] ───────────►│ 188 │ │ 189 │ 3. Extract client_pub │ 190 │ 4. Generate server keypair 191 │ 5. Compute DH shared secret 192 │ 6. Derive session key │ 193 │ │ 194 │◄─────── ServerHello [server_pub] ────────────│ 195 │ │ 196 │ 7. Extract server_pub │ 197 │ 8. Compute DH shared secret │ 198 │ 9. Derive session key │ 199 │ │ 200 │◄═══════ Encrypted with session_key ═════════►│ 201 ``` 202 203 ### Session Key Derivation 204 205 The session key binds both ephemeral secrecy and authentication: 206 207 ```rust 208 pub fn derive_session_key( 209 dh_shared: &[u8; 32], // X25519 shared secret 210 psk: Option<&[u8; 32]>, // Pre-shared key for authentication 211 salt: Option<&[u8]>, // Optional additional context 212 ) -> [u8; 32] { 213 // Combine DH secret with PSK 214 let mut ikm = dh_shared.to_vec(); 215 if let Some(key) = psk { 216 ikm.extend_from_slice(key); 217 } 218 219 // HKDF extraction and expansion 220 let hk = Hkdf::<Sha256>::new(salt, &ikm); 221 let mut session_key = [0u8; 32]; 222 hk.expand(b"abzu-session-v1", &mut session_key).unwrap(); 223 224 session_key 225 } 226 ``` 227 228 ### Key Security Properties 229 230 | Property | Mechanism | Guarantee | 231 |----------|-----------|-----------| 232 | **Forward Secrecy** | Ephemeral X25519 | Past sessions safe if PSK leaks | 233 | **Authentication** | PSK binding | Only nodes with PSK derive same key | 234 | **Key Separation** | HKDF context | Each session has unique key material | 235 | **No Key Reuse** | Fresh keypairs | Every connection isolated | 236 237 ### TLS Camouflage Integration 238 239 Public keys are embedded in the `key_share` extension of the fake TLS handshake: 240 241 ``` 242 ClientHello structure: 243 ┌─────────────────────────────────────────┐ 244 │ TLS Record Header (5 bytes) │ 245 │ Handshake Header (4 bytes) │ 246 │ Client Version (2 bytes) │ 247 │ Random (32 bytes) │ 248 │ Session ID (variable) │ 249 │ Cipher Suites (variable) │ 250 │ Extensions: │ 251 │ ├─ server_name (SNI) │ 252 │ ├─ supported_versions (TLS 1.3) │ 253 │ └─ key_share ◄── X25519 public key │ 254 │ └─ 32 bytes at offset 79 │ 255 └─────────────────────────────────────────┘ 256 ``` 257 258 ### Connection Methods 259 260 ```rust 261 // Client initiates PFS connection 262 let stream = FakeTlsStream::connect_pfs( 263 "relay.example.com:443", 264 Some(&psk), // Optional PSK for authentication 265 ).await?; 266 267 // Server accepts PFS connection 268 let stream = FakeTlsStream::accept_pfs( 269 tcp_stream, 270 Some(&psk), 271 ).await?; 272 ``` 273 274 --- 275 276 ## 5. Session Key Rotation 277 278 For long-lived connections, Abzu performs **periodic key rotation** to limit cryptographic exposure. Rotation uses the existing `Hello`/`HelloAck` wire frames for in-band rekeying. 279 280 ### Rotation Thresholds 281 282 | Trigger | Threshold | Rationale | 283 |---------|-----------|----------| 284 | **Bytes transferred** | 1 GB | Limit nonce reuse risk | 285 | **Time elapsed** | 1 hour | Bound temporal exposure | 286 | **Messages sent** | 1 million | AEAD safety margin | 287 288 ### Rekey Protocol 289 290 ``` 291 Initiator Responder 292 │ │ 293 │ 1. Detect threshold met (needs_rotation) │ 294 │ 2. Generate fresh X25519 keypair │ 295 │ │ 296 │──────── Hello [new_pub] ─────────────────────►│ 297 │ │ 298 │ 3. Generate fresh keypair 299 │ 4. Compute new DH secret 300 │ 5. Derive new session key 301 │ 6. Replace cipher atomically 302 │ 7. Reset nonce counter │ 303 │ │ 304 │◄─────── HelloAck [resp_pub, confirm] ────────│ 305 │ │ 306 │ 8. Compute new DH secret │ 307 │ 9. Derive new session key │ 308 │ 10. Replace cipher atomically │ 309 │ 11. Reset nonce counter │ 310 │ │ 311 │◄═════ Encrypted with NEW session_key ════════►│ 312 ``` 313 314 ### Implementation 315 316 ```rust 317 // Check if rotation needed 318 if stream.needs_rotation() { 319 stream.rotate_key().await?; 320 } 321 322 // Thresholds checked automatically in send()/recv() 323 pub fn needs_rotation(&self) -> bool { 324 let bytes = self.bytes_this_key.load(Ordering::Relaxed); 325 let msgs = self.messages_this_key.load(Ordering::Relaxed); 326 let elapsed = self.key_established_at.elapsed().as_secs(); 327 328 bytes >= ROTATION_BYTES_THRESHOLD // 1 GB 329 || msgs >= ROTATION_MESSAGE_THRESHOLD // 1M 330 || elapsed >= ROTATION_TIME_SECS // 1 hour 331 } 332 ``` 333 334 ### Atomic Key Replacement 335 336 The cipher is wrapped in `Arc<RwLock<ChaCha20Poly1305>>` allowing: 337 338 - **Concurrent reads** during normal encryption/decryption 339 - **Exclusive write** during key rotation 340 - **Zero message loss** — rotation completes between frames 341 342 ### Nonce Reset 343 344 After rotation, the nonce counter resets to `0`. This is safe because: 345 346 1. New key = new keystream 347 2. Nonce-key pairs never repeat 348 3. Each rotation creates fresh cryptographic context 349 350 --- 351 352 ## 6. Threat Model 353 354 ### Attacks Mitigated 355 356 | Attack | Mitigation | 357 |--------|------------| 358 | **Passive eavesdropping** | ChaCha20-Poly1305 encryption | 359 | **Key compromise (future)** | Ephemeral X25519 per-connection | 360 | **Replay attacks** | Timestamp validation, unique nonces | 361 | **Traffic analysis** | TLS 1.3 camouflage, cover traffic | 362 | **STUN server logging** | Zero-log policy, self-hosted | 363 364 ### Trust Boundaries 365 366 ``` 367 ┌─────────────────────────────────────────────────────────┐ 368 │ Trusted Zone │ 369 │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 370 │ │ Your Node │────│ Relay │────│ Peer Node │ │ 371 │ │ (PSK holder)│ │ (PSK holder)│ │ (PSK holder)│ │ 372 │ └─────────────┘ └─────────────┘ └─────────────┘ │ 373 └─────────────────────────────────────────────────────────┘ 374 ▲ ▲ ▲ 375 │ End-to-end encryption with PFS │ 376 └───────────────────────────────────────┘ 377 ``` 378 379 --- 380 381 ## 7. Dependencies 382 383 | Crate | Version | Purpose | 384 |-------|---------|---------| 385 | `x25519-dalek` | 2.0 | Elliptic curve Diffie-Hellman | 386 | `hkdf` | 0.12 | Key derivation function | 387 | `sha2` | 0.10 | SHA-256 for HKDF | 388 | `stun-proto` | 1.0 | STUN message parsing | 389 | `chacha20poly1305` | 0.10 | AEAD encryption | 390 391 --- 392 393 ## 8. Testing 394 395 ```bash 396 # Run all key exchange tests 397 cargo test -p abzu-transport key_exchange 398 399 # Full workspace verification 400 cargo test --workspace 401 # Result: 106 passed, 0 failed, 2 ignored 402 ``` 403 404 ### Test Coverage 405 406 - `ephemeral_keypair_roundtrip` — Key generation and DH agreement 407 - `derive_session_key_deterministic` — Same inputs = same output 408 - `derive_session_key_psk_affects_output` — PSK changes derived key 409 - `key_share_embed_extract_roundtrip` — TLS extension manipulation 410 - `extract_key_share_short_message` — Handles malformed input 411 - `full_pfs_handshake_derives_same_key` — End-to-end simulation