WireGuard «Required key not available»: 4 cause e soluzioni

In dmesg o journalctl -k:

wireguard: wg0: Receiving handshake initiation from peer ... (invalid)
wireguard: wg0: Invalid handshake initiation from 203.0.113.7:51820
wireguard: wg0: Packet has unallowed src IP from peer

oppure, la forma più citata:

Required key not available

Il kernel sta dicendo una cosa precisa: un pacchetto è arrivato su un'interfaccia WireGuard e nessuna chiave configurata è riuscita a decifrarlo. La rete ha funzionato. La crittografia no.

Questa distinzione restringe enormemente il problema, ed è il motivo per cui i soliti riflessi, controllare il firewall o la porta, qui non aiutano quasi mai. Se la porta fosse chiusa non vedresti proprio nulla.

Perché il messaggio non nomina alcun peer, e non lo farà mai

Un pacchetto WireGuard che il kernel non riesce a decifrare è, dal suo punto di vista, indistinguibile dal rumore. Non c'è alcun campo mittente in chiaro da leggere. Nominare un peer richiederebbe di tirare a indovinare, e il protocollo è progettato per non indovinare, ed è anche ciò che rende WireGuard muto davanti ai port scanner.

Il messaggio quindi è onesto, e da solo inutile. L'informazione sta altrove.

I tre comandi che la trovano

wg show

Leggi la riga latest handshake di ogni peer. Un peer senza alcun handshake non ne ha mai completato uno, e questo punta alle chiavi. Un peer con un handshake vecchio e contatori transfer in crescita è un problema diverso.

journalctl -k --since "10 minutes ago" | grep -i wireguard

Confronta i timestamp con i tuoi tentativi di connessione. Le righe che compaiono solo quando provi a connetterti sono tue. Le righe che arrivano di continuo, a gocce, sono Internet, e sono rumore.

wg show wg0 public-key

Su entrambe le macchine. È il controllo che risolve la causa più comune, qui sotto.

Causa 1: una chiave pubblica che non è quella che pensi

È di gran lunga la più frequente. Il server conserva una chiave che non è quella del client, oppure il client conserva quella vecchia del server.

La trappola ha una forma precisa: PublicKey in un blocco peer deve essere la chiave pubblica dell'ALTRA macchina, mai la tua. Copiare una configurazione tra due client dimenticando di cambiare quella riga produce una voce peer che punta a sé stessa, e ogni pacchetto fallisce.

Verifica confrontando direttamente:

wg show wg0 public-key

Eseguilo sul server e confronta il risultato con la PublicKey nel blocco [Peer] del client, carattere per carattere. Poi al contrario. Le stringhe Base64 differiscono di un solo carattere più spesso di quanto chiunque si aspetti, soprattutto dopo una copia passata per un client di chat che ha gentilmente tagliato qualcosa.

Causa 2: una preshared key da un solo lato

PresharedKey viene mescolata nell'handshake. Presente su un lato e assente sull'altro, oppure presente su entrambi con valori diversi, e le chiavi derivate non corrispondono più.

Il sintomo è identico a quello di una chiave pubblica sbagliata, ed è per questo che si passa un'ora sulla causa 1 prima di trovare questa. Se hai aggiunto di recente una preshared key, controlla entrambi i lati prima di qualsiasi altra cosa. Il meccanismo, e come aggiungerne una senza chiuderti fuori, è nella guida alla preshared key di WireGuard.

Causa 3: la chiave privata è stata rigenerata

Tutto ciò che ricrea la coppia di chiavi invalida ogni voce peer che faceva riferimento alla vecchia chiave pubblica: reinstallare il client, ripristinare un container da un'immagine, eseguire wg genkey in uno script che era già stato eseguito una volta.

L'indizio è che ieri funzionava e nella configurazione non è cambiato nulla. Nel file non è cambiato nulla, ma la chiave dietro di esso sì. Un server che viene ricostruito di continuo, una macchina di casa reinstallata dopo un guasto del disco o un container ricreato da un'immagine, è la fonte abituale; un piccolo VPS con un IPv4 pubblico fisso e gli snapshot mantiene la stessa chiave sullo stesso host. Un Cloud VPS Contabo (link di affiliazione) costa 5.50 € al mese con un impegno di 24 mesi e uno snapshot incluso (verificato il 17 ottobre 2026), e Ultahost VPS Basic (link di affiliazione) costa 5.52 $ al mese con un impegno di 24 mesi, un IPv4 dedicato e una garanzia soddisfatti o rimborsati di 30 giorni (verificato il 21 ottobre 2026).

Se devi comunque ricostruire la coppia, genera entrambi i lati dalla stessa fonte. Il nostro generatore di configurazioni WireGuard gratuito crea ogni coppia di chiavi nel tuo browser e scrive i blocchi [Peer] del server e ogni file client a partire dallo stesso materiale, quindi la chiave pubblica che il server conserva per un client è, per costruzione, quella che deriva dalla chiave privata di quel client. Inserisci il nuovo blocco [Peer] nel server in esecuzione con wg set o wg syncconf, come descritto in aggiungere un peer WireGuard, e il silenzio della vecchia voce finisce. Il generatore è gratuito fino a 10 dispositivi; oltre, WireGuard Pro (il nostro prodotto, 9 EUR una tantum, nessun abbonamento) porta il limite a 250 e aggiunge un unico ZIP con ogni .conf client e il relativo codice QR in PNG, comodo per configurare un intero ufficio o una famiglia in un colpo solo.

Causa 4: non è affatto il tuo traffico

Un server in ascolto su una porta UDP pubblica riceve pacchetti non richiesti. Gli scanner li inviano di continuo, e ognuno produce una riga.

È normale e non richiede alcun intervento. È rumore di fondo, e diventa un segnale solo quando coincide con i tuoi tentativi. Se il volume ti dà fastidio, cambiare la porta di ascolto lo riduce, ma silenziare quella categoria di log eliminerebbe l'unica diagnostica che hai quando un peer reale fallisce.

L'ordine che la trova più in fretta

1. wg show su entrambi i lati. L'assenza totale di handshake conferma un problema di chiavi e non di routing.
2. Confronta direttamente le chiavi pubbliche con wg show wg0 public-key, in entrambe le direzioni.
3. Controlla se PresharedKey esiste su un lato e non sull'altro.
4. Guarda i timestamp. Se le righe compaiono senza che tu faccia nulla, sono scanner.

Se l'interfaccia non si è mai attivata e la chiave è stata rifiutata prima di qualsiasi tentativo di handshake, il problema è la forma della chiave e non il suo valore: si tratta di key is not the correct length or format, un errore di parsing con cause del tutto diverse.

Se l'handshake si completa e il traffico continua a non passare, questo è l'articolo sbagliato: si tratta dell'MTU quando le pagine si bloccano, oppure di AllowedIPs quando il routing è sbagliato. La checklist più ampia è nella guida alla risoluzione dei problemi di handshake.

Tieni l'essenziale a portata di mano: il WireGuard Cheat Sheet gratuito (PDF di 4 pagine, paghi quanto vuoi, 0 USD accettati) contiene le tabelle di keepalive e MTU, i comandi wg genkey/wg pubkey/wg genpsk e i quattro controlli del server, una riga ciascuno, da eseguire per primi quando un tunnel non fa passare traffico. Il WireGuard Self-Hosting Kit a pagamento (9 USD) aggiunge una checklist di risoluzione dei problemi con 12 cause e 11 modelli di configurazione.