Spec couche 2 — `air-wireguard` (VPN WireGuard, patron sans-IO)

Spécification technique — Version 0.1 (proposition). Couche 2 « Frameworks système » (crate) + daemon couche 5.

Cadrage. air-wireguard implémente WireGuard (Noise IK, whitepaper Donenfeld 2017). Maison, pur Rust, zéro-C, zéro unsafe ; crypto via air-crypto. Crate-lib (cœur sans-IO) + daemon .airservice (note réseau §1 : WireGuard = L2/L5, UDP, Noise). WireGuard est moderne par conception (aucun legacy à omettre).

Position et méthode

Protocole filaire → cœur sans-IO (les 9 composants) + pilote I/O (air-socket UDP + interface TUN). Le daemon crée l’interface tunnel et route le trafic. Consomme air-runtime, air-netlink (config interface/routes), air-base-core.

Périmètre — moderne only (par construction)

Handshake Noise IKpsk2 : Curve25519 (ECDH), BLAKE2s (hash/MAC/KDF), ChaCha20Poly1305 (AEAD transport), HKDF-via-HMAC-BLAKE2s. Un seul jeu d’algos (pas de négociation → pas de downgrade — force de WireGuard).
Résistance DoS : mécanisme cookie (MAC1/MAC2) sous charge ; replay window (compteur + fenêtre glissante).
Rekey temporel/volumétrique ; keepalive ; 1.5-RTT handshake.

Anatomie : les 9 composants

#	Composant	`air-wireguard`	Pur ?
1	Framer	`WgMessageFramer` — 4 types (Handshake Init/Response, Cookie, Transport Data) sur UDP	✅
2	Codec	`WgMessageCodec` — champs fixes bornés	✅
3	StateMachine	`PeerStateMachine` — Handshake→Transport, rekey (whitepaper §6.2)	✅
4	Handshaker	`NoiseIk` — Noise IKpsk2 (X25519+BLAKE2s), MAC1/MAC2 ; consomme `air-crypto`	✅ + air-crypto
5	Flow Controller	`// NO : pas de fenêtrage applicatif (VPN = paquets IP encapsulés)`	—
6	Multiplexer	`PeerTable` — routage par clé publique de pair (cryptokey routing)	✅
7	Timer Manager	`WgTimers` — rekey, keepalive, handshake-retry (whitepaper timers) ; horloge injectée	✅
8	Session Context	`TransportKeys` (send/recv, `zeroize`) + `ReplayWindow` + compteurs	✅
9	Extension hooks	cookie/DoS ; `// pas d'extensions négociées (par conception)`	✅

Inventaire — ~15 objets

Surface (~7) : WireGuardTunnel, Peer/PeerConfig (clé publique, endpoint, allowed-ips, psk, keepalive), WireGuardConfig (clé privée, port), TunnelEvent, WgError, AllowedIps. Cœur sans-IO (~8) : WgMessageFramer, WgMessageCodec, PeerStateMachine, NoiseIk, PeerTable (cryptokey routing), WgTimers, TransportKeys, ReplayWindow.

#![allow(unused)]
fn main() {
pub enum TunnelEvent { HandshakeComplete(PeerId), DecryptedPacket(PeerId), WantsTransmit, PeerExpired }
impl WireGuardTunnel {
    pub fn new(config: WireGuardConfig) -> AirResult<Self>;
    pub fn recv_udp(&mut self, now: AirInstant, from: SocketAddr, dg: &[u8]) -> AirResult<Vec<TunnelEvent>>;
    pub fn encapsulate(&mut self, now: AirInstant, ip_packet: &[u8]) -> AirResult<Option<(SocketAddr, Vec<u8>)>>;
    pub fn poll_transmit(&mut self, now: AirInstant) -> Option<(SocketAddr, Vec<u8>)>;
    pub fn handle_timeout(&mut self, now: AirInstant) -> AirResult<Vec<TunnelEvent>>;
}
}

Dépendances

air-crypto (L1 — X25519 ✓, ChaCha20Poly1305 ✓ ; additif BLAKE2s ci-dessous), air-socket (L1, UDP), air-netlink (L1, interface/routes), air-runtime/ air-base-core (L1). Interface TUN : additif couche 0 tun_set_iff (TUNSETIFF) instruit (ADR-083). Zéro-C, zéro tierce.

Additifs air-crypto — INSTRUITS (ADR-082). (1) BLAKE2s (blake2, pur Rust zéro-C ≠ blake3-qui-tire-cc) — hash + MAC keyed (MAC1/MAC2) + HMAC-BLAKE2s (KDF Noise). (2) lowlevel::AirAeadExplicitNonce — le transport WireGuard chiffre avec ChaCha20-Poly1305 à nonce = compteur (déterministe), donc via l’AEAD à nonce explicite, pas la façade à nonce aléatoire. X25519/ChaCha20-Poly1305 déjà présents.

Sécurité & tests

Replay window (anti-rejeu), cookie MAC2 (anti-DoS sous charge), constant-time (hérité air-crypto/subtle), secrets zeroize. Pas de négociation ⇒ pas de downgrade.
Tests : Framer/Codec fuzzés ; NoiseIk vecteurs whitepaper + négatifs (MAC invalide, replay rejeté) ; interop kernel WireGuard/wireguard-go en loopback.

Travail à reprendre

Additifs air-crypto — instruits (ADR-082) : BLAKE2s (+ HMAC-BLAKE2s) + lowlevel::AirAeadExplicitNonce (transport à nonce compteur).
Interface TUN — additif couche 0 tun_set_iff instruit (ADR-083).
Daemon .airservice (L5) ; roaming d’endpoint ; ABI C différée.

Licence : MPL 2.0. Statut : spec air-wireguard (L2, daemon L5) v0.1 — WireGuard maison, Noise IK, sans-IO ; crypto via air-crypto (additif BLAKE2s requis).

Keyboard shortcuts

Air — Documentation de conception