WireGuard: come funziona il cryptokey routing
Scopri perché AllowedIPs è insieme tabella di routing e ACL, come funzionano handshake Noise e rotazione delle chiavi, e come leggere ogni wg0.conf.
Come funziona WireGuard, in un'unica idea
WireGuard associa ogni pacchetto a una chiave pubblica. Questo meccanismo si chiama cryptokey routing e costituisce l'intero modello di progettazione: la riga AllowedIPs accanto a un peer è la tabella di routing per i pacchetti in uscita dal computer e l'elenco di controllo degli accessi per i pacchetti in arrivo da quel peer. Una sola impostazione svolge due funzioni. Interpretate AllowedIPs in questo modo e ogni file di configurazione di WireGuard diventa leggibile.
Non esiste una tabella delle sessioni indicizzata per indirizzo IP e non esiste un database degli utenti. Un peer è una chiave pubblica associata all'insieme degli indirizzi che quella chiave può utilizzare. L'handshake e i timer servono a mantenere valida questa associazione mentre cambia la rete sottostante. Se volete prima realizzare un tunnel funzionante e approfondire poi la teoria, createne uno seguendo questa guida per un VPN WireGuard self-hosted sul vostro VPS, quindi tornate qui quando una riga della configurazione vi sembra insolita.
AllowedIPs è una tabella di routing e un elenco di controllo degli accessi
Consideriamo prima la direzione in uscita. Il kernel instrada il pacchetto verso il dispositivo wg0 nel modo consueto, tramite la tabella di routing principale. WireGuard confronta quindi l'indirizzo di destinazione del pacchetto con una tabella che contiene tutti i prefissi consentiti dei peer, verificandoli dal prefisso più lungo a quello più breve. Una corrispondenza identifica un peer, che a sua volta identifica una chiave pubblica, una chiave di sessione e un endpoint UDP. Il pacchetto viene cifrato per quel peer e inviato all'endpoint.
Se il AllowedIPs di alcun peer non copre la destinazione, non viene inviato nulla, perché non esiste alcuna chiave con cui inviarlo.
ping: sendmsg: Required key not availableQuesto errore ha una sola spiegazione: l'indirizzo che si è tentato di raggiungere non è elencato per alcun peer. Un errore diverso, ping: sendmsg: Destination address required, indica che è stato trovato un peer corrispondente, ma WireGuard non dispone di un endpoint per quel peer, perché non ne è stato configurato uno e non ne è stato ancora appreso alcuno.
Passiamo ora alla direzione in ingresso. Un pacchetto UDP arriva sulla porta di ascolto. WireGuard individua la sessione usando il receiver index nell'header, quindi decifra e autentica il payload e verifica il contatore rispetto a una finestra scorrevole anti-replay. Solo a questo punto legge il pacchetto interno; una ricerca del prefisso più lungo dell'indirizzo di origine deve identificare il peer mittente autenticato. In caso contrario, il pacchetto viene scartato. Con il debug dinamico abilitato, il kernel stampa il motivo in una riga come questa:
wg0: Packet has unallowed src IP (10.8.0.9) from peer 2 (203.0.113.10:51820)Per questo un peer sul server riceve un /32. Un peer configurato con AllowedIPs = 10.8.0.2/32 può inviare pacchetti da 10.8.0.2 e da nessun altro indirizzo. Sostituire quel valore con 0.0.0.0/0 consente invece al client di dichiarare qualsiasi indirizzo sorgente IPv4 la cui corrispondenza con il prefisso più lungo lo selezioni, ma non un indirizzo assegnato a un altro peer tramite un prefisso più specifico.
I prefissi sovrapposti vengono risolti in base alla specificità, perché la ricerca usa la corrispondenza con il prefisso più lungo. I prefissi identici configurati su due peer si comportano in modo diverso: la voce viene assegnata al peer configurato per ultimo e il primo peer smette di ricevere quel traffico senza che venga stampato alcun errore. wg show wg0 allowed-ips stampa la tabella effettivamente presente nel kernel, che è quella rilevante quando il file su disco e lo stato in esecuzione non sono più sincronizzati.
Leggere un file di configurazione considerando il routing tramite chiavi crittografiche
Lato server:
[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = <server private key>
[Peer]
PublicKey = <laptop public key>
AllowedIPs = 10.8.0.2/32Lato client:
[Interface]
Address = 10.8.0.2/32
PrivateKey = <laptop private key>
[Peer]
PublicKey = <server public key>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25La stessa parola chiave ha un significato opposto nei due lati. Sul client indica «invia ogni destinazione a questo peer». Sul server indica «accetta da questo peer solo questo indirizzo». L’asimmetria dipende dai valori, non dal ruolo.
Metà di queste chiavi non appartiene affatto al protocollo. Address, DNS, MTU, PostUp e SaveConfig appartengono a wg-quick, lo script shell che porta l’interfaccia nello stato operativo. Non sono impostazioni del protocollo WireGuard; wg-quick le gestisce separatamente. wg-quick strip wg0 stampa la configurazione ridotta che lo strumento wg carica effettivamente. È il modo più rapido per vedere questa separazione.
Cosa fa effettivamente l'handshake
L'handshake di WireGuard è Noise_IKpsk2, appartenente al Noise Protocol Framework. La parte IK è quella più utile per un sysadmin: la chiave pubblica statica del responder è già nota all'initiator, perché è la PublicKey nel blocco [Peer]; l'initiator invia la propria chiave pubblica statica all'interno del primo messaggio, in forma crittografata. Non è quindi previsto alcuno scambio di certificati né un round trip per verificare l'identità. Un osservatore passivo non può sapere quale chiave sta effettuando la chiamata, a meno che non disponga della chiave privata del responder.
Il costo è un round trip. Il messaggio di initiation è di 148 byte, la response è di 92 byte e i dati iniziano a transitare subito dopo. Ogni lato genera una nuova coppia di chiavi effimere Curve25519 per ogni handshake; le chiavi di sessione derivano da una catena di risultati Diffie-Hellman che combina le chiavi statiche e quelle effimere. Le chiavi private effimere vengono poi eliminate. Questo garantisce la forward secrecy: se qualcuno registra il traffico oggi e ruba la chiave privata del server l'anno prossimo, non può comunque leggere i dati registrati.
L'handshake initiation contiene un timestamp TAI64N. Ogni peer memorizza il timestamp più recente ricevuto dall'altro, quindi un initiation riprodotto viene rifiutato. I pacchetti dati contengono un contatore a 64 bit usato come nonce. Il destinatario mantiene una sliding window dei contatori ricevuti più di recente, quindi gestisce replay e riordini estesi senza mantenere uno stato della connessione come quello di TCP.
Le chiavi di sessione non durano a lungo e i timer sono definiti in fase di compilazione, non configurabili.
I dati alla base di questo grafico
[
{
"label": "REKEY_TIMEOUT",
"seconds": 5,
"notes": "resend a handshake initiation that got no answer, plus up to 333 ms of random jitter"
},
{
"label": "KEEPALIVE_TIMEOUT",
"seconds": 10,
"notes": "send a keepalive after receiving data and sending none back"
},
{
"label": "REKEY_ATTEMPT_TIME",
"seconds": 90,
"notes": "stop retrying the handshake and drop the packets queued for that peer"
},
{
"label": "REKEY_AFTER_TIME",
"seconds": 120,
"notes": "the peer that initiated the current session begins a fresh handshake when it next sends"
},
{
"label": "REJECT_AFTER_TIME",
"seconds": 180,
"notes": "the old session key is refused and traffic stops"
}
]Questi sono valori costanti definiti dalla specifica del protocollo, non misurazioni. Questi 5 timer contribuiscono alla gestione del ciclo di vita della sessione. Quando una chiave di sessione raggiunge 120 secondi di vita, il peer che ha avviato quell'handshake ne avvia uno nuovo alla successiva trasmissione; il responder non esegue il rekey in base a questo timer. Dopo 180 secondi, la vecchia chiave viene rifiutata senza eccezioni e il traffico si interrompe finché non viene completato un nuovo handshake. Un initiation che non riceve risposta viene ritrasmesso dopo 5 secondi, con un jitter casuale fino a un terzo di secondo; i tentativi terminano dopo circa 90 secondi. Per questo wg show stampa latest handshake come età relativa e un tunnel attivo e funzionante mantiene questo valore basso. Se l'età aumenta mentre si sta inviando traffico, gli handshake stanno fallendo; non significa che il tunnel sia inattivo.
Perché un peer non ha un ruolo client o server
Entrambi i lati eseguono lo stesso codice e usano lo stesso formato di configurazione. Non esiste una modalità server. L'asimmetria percepita dipende da Endpoint, mentre Endpoint è facoltativo.
Un peer con un endpoint configurato può avviare un handshake. Un peer senza endpoint resta in attesa, quindi apprende l'indirizzo e la porta dell'altro lato dal primo pacchetto autenticato correttamente. L'endpoint appreso viene memorizzato e aggiornato ogni volta che arriva un pacchetto valido da un nuovo indirizzo. Questo è il funzionamento del roaming: un laptop che passa dal Wi-Fi alla rete mobile mantiene lo stesso tunnel, perché una sessione viene identificata tramite chiave e indice, non tramite indirizzo IP. Non viene ristabilita alcuna connessione, perché in senso TCP non era mai stata instaurata una connessione.
Lo stesso meccanismo porta a un dato utile da conoscere: il peer con l'indirizzo pubblico conserva l'ultimo IP pubblico noto dell'altro lato e wg show lo visualizza.
Primitivi fissi, senza negoziazione
In WireGuard non esiste un elenco di ciphersuite. ChaCha20-Poly1305 per la cifratura autenticata, Curve25519 per l'accordo delle chiavi, BLAKE2s per l'hashing, HKDF per la derivazione delle chiavi. Tutte le implementazioni usano questi primitivi, quindi non esiste una fase di negoziazione da analizzare né un percorso di downgrade verso un'opzione più debole. Il compromesso è concreto: se uno di questi primitivi viene compromesso, occorrono una nuova versione dell'intero protocollo e un aggiornamento su entrambe le estremità, non una modifica della configurazione. Questa scelta elimina gran parte del codice e delle modalità di errore presenti in un tunnel basato su TLS. È soprattutto questo il punto del confronto in WireGuard rispetto a OpenVPN.
Perché la porta non risponde a uno scanner
I messaggi di avvio e risposta dell'handshake contengono un campo denominato mac1; le risposte con cookie non lo contengono. Si tratta di un MAC (codice di autenticazione del messaggio) calcolato sul messaggio usando una chiave derivata dalla chiave pubblica statica del destinatario. Un mittente che non conosce tale chiave pubblica non può generare un mac1 valido, quindi il destinatario scarta il pacchetto senza inviare alcuna risposta. Non viene restituito alcun errore, reset o messaggio ICMP.
Il risultato visibile è una scansione UDP che non riceve alcuna risposta.
sudo nmap -sU -p 51820 vpn.example.comnmap restituisce open|filtered, la stessa risposta che fornisce quando un firewall scarta silenziosamente i pacchetti destinati a una porta. Una porta UDP non filtrata sulla quale non è in ascolto alcun servizio restituisce normalmente un errore ICMP di porta non raggiungibile; nmap lo riporta invece come closed.
Un secondo campo, mac2, gestisce la pressione dovuta agli attacchi di tipo denial of service. Quando il destinatario è sotto carico, risponde a un messaggio di avvio o di risposta con un mac1 valido, ma senza un mac2 valido, insieme a una risposta con cookie di 64 byte associata all'indirizzo di origine del mittente. Il destinatario rifiuta di eseguire le costose operazioni con la chiave pubblica finché il mittente non usa quel cookie per calcolare un mac2 valido. In questo modo dimostra che l'indirizzo di origine è raggiungibile prima di eseguire operazioni costose con la chiave pubblica. Questa protezione si attiva solo sotto carico.
Perché 0.0.0.0/0 trasforma un peer nella route predefinita
Poiché AllowedIPs è la tabella di routing, AllowedIPs = 0.0.0.0/0, ::/0 seleziona quel peer per le destinazioni non coperte da un prefisso più specifico assegnato a un altro peer. Questa è tutta la configurazione del full tunnel.
Il routing che lo fa funzionare è più interessante della riga in sé. Una route predefinita semplice attraverso wg0 entrerebbe in loop, perché anche il pacchetto UDP cifrato che trasporta il traffico deve uscire dalla macchina e corrisponderebbe alla propria route predefinita. wg-quick evita questo problema con il policy routing. Contrassegna con un fwmark i pacchetti in uscita generati da WireGuard, inserisce la route predefinita del tunnel in una tabella di routing separata e aggiunge regole che consentono di raggiungerla soltanto al traffico senza mark. Esegui ip rule show per vedere il risultato:
32764: from all lookup main suppress_prefixlength 0
32765: not from all fwmark 0xca6c lookup 51820
32766: from all lookup main0xca6c è 51820 in formato esadecimale e 51820 è anche il numero della tabella. La regola suppress_prefixlength 0 fa sì che la tabella principale ignori la propria route predefinita. In questo modo le route specifiche, ad esempio quella della subnet locale, hanno ancora la precedenza, mentre tutto il resto passa alla tabella del tunnel. Un split tunnel non richiede nulla di tutto questo: un elenco più ristretto, come AllowedIPs = 10.8.0.0/24, 10.20.0.0/16, diventa un insieme di route ordinarie nella tabella principale.
Un full tunnel non risolve automaticamente la risoluzione dei nomi, perché il resolver appreso dal client tramite la rete locale di solito resta in uso e la sua route è più specifica. Si tratta di un'attività separata, descritta in DNS che fuoriesce dal tunnel WireGuard.
A cosa serve realmente PersistentKeepalive
WireGuard non invia nulla quando non c'è traffico. Nessun heartbeat, nessun aggiornamento della sessione, nulla sulla rete. Questo silenzio riduce il consumo della batteria, agevola il caso dello scanner descritto sopra, ma interrompe una configurazione specifica.
Un peer dietro NAT (network address translation) o un firewall stateful è raggiungibile dall'esterno solo mentre nel dispositivo esiste un mapping, creato da un pacchetto in uscita. I mapping UDP hanno spesso una durata iniziale di circa 30 secondi. Quando il mapping scade, il middlebox scarta i pacchetti provenienti dal lato pubblico e il tunnel appare inattivo finché il peer dietro NAT non invia qualcosa. PersistentKeepalive = 25 invia un pacchetto autenticato vuoto ogni volta che trascorrono 25 secondi senza che un pacchetto autenticato attraversi il tunnel da o verso quel peer. Il traffico reale azzera il conto alla rovescia, quindi in un tunnel trafficato il pacchetto vuoto viene inviato raramente, mentre in uno inattivo l'intervallo non supera mai la durata minima comunemente osservata e il mapping resta aperto.
Impostalo sul peer dietro NAT. Un server con un indirizzo pubblico e una porta UDP aperta non ne ha bisogno; impostarlo su quel lato aggiunge soltanto traffico. Non confonderlo con il keepalive automatico, che scatta 10 secondi dopo che un peer riceve dati e non ha nulla di proprio da inviare. Questo meccanismo è sempre attivo e non è configurabile.
Instradare la LAN attraverso il tunnel non è una funzionalità di WireGuard
Supponiamo che il peer B si trovi sulla rete domestica 192.168.50.0/24 e che il peer A debba raggiungerla. Devono essere configurati correttamente due sistemi distinti, e solo uno dei due è WireGuard.
La parte di WireGuard consiste nell’aggiungere 192.168.50.0/24 a AllowedIPs di B su A. In questo modo A seleziona B per quel prefisso e accetta da B i pacchetti con quegli indirizzi sorgente, tranne nei casi in cui un prefisso più specifico selezioni un altro peer. Senza questa configurazione, il routing tramite chiavi crittografiche non dispone di una chiave per la destinazione e non autorizza l’indirizzo sorgente.
La parte gestita dal kernel è la seguente: su B, net.ipv4.ip_forward deve essere impostato su 1, altrimenti il kernel scarta ogni pacchetto decrittografato che non è indirizzato direttamente a B. La catena forward del firewall di B deve consentire il traffico. Gli host della LAN devono disporre di una route di ritorno verso 10.8.0.0/24, oppure B deve applicare il NAT d’origine affinché le risposte ritornino attraverso B.
Il compito di WireGuard termina quando consegna il pacchetto decrittografato al kernel. Tutto ciò che avviene dopo è il normale routing e filtraggio di Linux. Per questo il problema compare nei contatori nft list ruleset o in ip -s link show wg0, non in wg show. Se preferisci gestire i peer tramite un’interfaccia web, eseguire wg-easy in Docker genera automaticamente le configurazioni dei peer, ma l’inoltro dipende comunque dal supporto del kernel e del firewall dell’host. La stessa separazione vale quando un livello di coordinamento distribuisce il prefisso al posto tuo: pubblicizzare una rete privata da un VPS con un router subnet Tailscale sostituisce la modifica manuale di AllowedIPs su ogni peer, ma devi comunque abilitare l’inoltro IP sul router; Tailscale gestisce per impostazione predefinita le proprie regole del firewall.
Perché WireGuard risiede nel kernel
wg0 è un driver per dispositivi di rete. I pacchetti lo raggiungono tramite il normale stack di routing, vengono cifrati dai worker del kernel e lasciano il sistema tramite un socket UDP senza mai passare nello userspace. WireGuard è stato integrato nel kernel Linux mainline 5.6 a marzo 2020. Ubuntu 24.04 e Debian 13 lo includono, quindi manca soltanto il pacchetto wireguard-tools.
L'uso di un'interfaccia normale ha conseguenze pratiche. tcpdump -ni wg0 mostra i pacchetti interni in chiaro, mentre tcpdump -ni eth0 udp port 51820 mostra quelli esterni cifrati; il confronto indica immediatamente la direzione in cui si verifica il problema. netfilter e il traffic shaping trattano wg0 come qualsiasi altro collegamento. Quando il modulo del kernel non è disponibile, ad esempio nella virtualizzazione dei container che condivide il kernel dell'host, wireguard-go implementa lo stesso protocollo nello userspace tramite un dispositivo TUN, con una riduzione effettiva del throughput perché ogni pacchetto attraversa due volte il confine del kernel.
Da cosa non ti protegge WireGuard
Il modello di minaccia è volutamente limitato e un protocollo così silenzioso invita a facili illusioni. Diciamolo chiaramente.
- Non nasconde l'utilizzo di WireGuard. I messaggi di handshake hanno dimensioni fisse, il primo byte indica il tipo di messaggio e il trasporto avviene via UDP. Il deep packet inspection lo riconosce facilmente e una rete che non gradisce le VPN può bloccarlo. L'offuscamento è stato escluso per scelta progettuale.
- Non nasconde il volume o la tempistica del traffico. I payload sono riempiti (padded) solo fino a un limite di 16 byte, quindi un osservatore può comunque vedere quando invii dati e approssimativamente in che quantità.
- Mantiene l'ultimo endpoint noto. Il peer con l'indirizzo pubblico memorizza l'attuale IP pubblico della controparte e
wg showlo visualizza. Insieme a un indirizzo del tunnel fisso nella configurazione, questo costituisce un identificatore stabile che segue l'utente tra diverse reti. Sul proprio VPS questo non è un problema. È anche il motivo per cui i servizi commerciali aggiungono un livello sopra il protocollo. - Autentica una chiave, non una persona. Chiunque possieda il file della chiave privata è il peer. Mantieni
/etc/wireguardcon permessi 700 e i file delle chiavi con 600. - Non esiste una lista di revoca né una scadenza. L'accesso termina quando elimini la voce del peer da ogni server che la contiene, e le chiavi statiche restano valide finché non le rimuovi.
Niente di tutto questo rende WireGuard debole. Lo rende piccolo, ed è proprio la dimensione ridotta lo scopo: autentica e cifra, lasciando la gestione dell'identità e l'assegnazione degli indirizzi a ciò che costruisci sopra di esso. Un livello di coordinamento del tipo descritto in WireGuard a confronto con Tailscale esiste per colmare esattamente questa lacuna, utilizzando lo stesso data plane di cui hai appena letto. Una volta implementato tale livello, la decisione successiva riguarda chi può raggiungere un servizio che esegui all'interno del tunnel, che è ciò che la scelta tra Tailscale serve e funnel risolve per una singola porta.
FAQ
Che cos'è il cryptokey routing in WireGuard?
Il cryptokey routing è la regola che associa ogni pacchetto a una chiave pubblica. Ogni voce peer contiene un elenco di prefissi in AllowedIPs. In uscita, WireGuard seleziona il peer confrontando la destinazione del pacchetto con l'elenco di ogni peer e scegliendo prima il prefisso più specifico; l'elenco funziona quindi come una tabella di routing. In ingresso, dopo aver decrittografato e autenticato un pacchetto, una ricerca del prefisso più specifico sull'indirizzo sorgente interno deve selezionare lo stesso peer. In caso contrario, il pacchetto viene scartato, quindi l'elenco funziona come una lista di controllo degli accessi. WireGuard non dispone di una configurazione di routing separata né di un firewall interno separato, perché lo stesso elenco svolge entrambe le funzioni.
Devo impostare PersistentKeepalive su entrambi i peer?
No. Impostalo sul lato che si trova dietro NAT (network address translation) o dietro un firewall stateful, che di solito è il client. WireGuard non invia dati quando è inattivo, quindi il mapping che consente al lato remoto di raggiungere quel peer scade, spesso entro un minuto, e il tunnel sembra quindi non funzionare in una direzione. PersistentKeepalive = 25 invia un pacchetto vuoto autenticato ogni volta che trascorrono 25 secondi senza traffico autenticato da o verso quel peer, mantenendo aperto il mapping. Un peer con un indirizzo pubblico e una porta UDP aperta non ne ha bisogno.
Perché il ping attraverso il tunnel restituisce "Required key not available"?
Perché l'indirizzo di destinazione non rientra in alcun AllowedIPs dei peer. Il cryptokey routing non ha quindi trovato una chiave con cui cifrare il pacchetto e il kernel ne ha rifiutato l'invio. Esegui wg show wg0 allowed-ips e confronta l'output con l'indirizzo verso cui stai inviando il ping. L'errore simile Destination address required indica un problema diverso: è stato trovato un peer corrispondente, ma WireGuard non dispone di un endpoint per quel peer, perché non ne è stato configurato alcuno e da quel peer non è ancora arrivato alcun pacchetto autenticato.
Un firewall può rilevare e bloccare WireGuard?
Sì. WireGuard autentica e cifra il traffico e non tenta di mascherarsi. I messaggi di avvio e risposta dell'handshake hanno dimensioni fisse di 148 e 92 byte, le risposte ai cookie hanno una dimensione di 64 byte, il primo byte di ogni messaggio ne identifica il tipo e il trasporto usa UDP. L'ispezione approfondita dei pacchetti può quindi identificare il protocollo senza difficoltà. Le reti che bloccano UDP o che identificano i protocolli tramite fingerprinting lo impediranno. Per nascondere il tunnel è necessario incapsularlo in qualcos'altro. Si tratta di uno strumento separato, non di un'impostazione di WireGuard.