wolfssl/wolfguardModulo kernel VPN e strumento utente conformi a FIPS 140-3, sostituto drop-in per WireGuard con crittografia AES-256-GCM, SHA2-256 e SECP256R1 per tunneling sicuro.
# WolfGuard VPN con crittografia FIPS 140-3 WolfGuard è il refactoring conforme a FIPS di wolfSSL del kernel Linux basato su [WireGuard](https://www.wireguard.com/), originariamente progettato e creato da Jason Donenfeld. L'utilizzo è essenzialmente identico. WolfGuard ha due componenti principali: il modulo kernel `wolfguard.ko` e lo strumento di configurazione `wg-fips`. `wolfguard.ko` dipende dal modulo kernel `libwolfssl.ko` e `wg-fips` dipende dalla libreria `libwolfssl.so` — queste dipendenze sono costruite dalla stessa fonte [wolfSSL](https://github.com/wolfssl/wolfssl), rispettivamente con configurazione per modulo kernel e libreria utente. Lo script `wg-fips-quick` funziona esattamente come `wg-quick` in WireGuard, ma con script di configurazione in `/etc/wolfguard` contenenti chiavi pubbliche e private SECP256R1. I collegamenti simbolici vengono installati nella directory bin di installazione da `wg` a `wg-fips` e da `wg-quick` a `wg-fips-quick`, per una sostituzione trasparente di WireGuard. Se durante l'installazione vengono trovati eseguibili di WireGuard, vengono rinominati in `wg-wireguard` e `wg-wireguard-quick`, con `wg-wireguard-quick` modificato per chiamare `wg-wireguard` e con una copia di sicurezza lasciata in `wg-wireguard-quick.unpatched`. WolfGuard rimappa la crittografia di WireGuard come segue: | Categoria algoritmo | WireGuard | WolfGuard | | :----------- | :-------- | :-------- | | ECDH | Curve25519 | SECP256R1 | | AEAD | XChaCha20-Poly1305 | AES-256-GCM | | digest | Blake2s | SHA2-256 | | digest di autenticazione | Blake2s-HMAC | SHA2-256-HMAC | | hash interno | SipHash | SHA2-256 | | DRBG | ChaCha20 DRBG | SHA2-256 Hash-DRBG | Nota che WolfGuard e WireGuard possono coesistere sullo stesso sistema, stabilendo simultaneamente tunnel WolfGuard e WireGuard. Se `libwolfssl.ko` è configurato con `--enable-intelasm`, le prestazioni di WolfGuard eguagliano o superano quelle di WireGuard accelerato via CPU, grazie all'accelerazione CPU delle operazioni AES-256-GCM e SHA2-256. Senza `--enable-intelasm`, WolfGuard è leggermente più lento di WireGuard accelerato via CPU, ma è comunque in grado di saturare una gigabit ethernet su CPU moderne. ## Compilazione e installazione Di seguito sono riportate due serie di istruzioni: la prima per la compilazione da fonti non-FIPS, e la seconda per la compilazione da fonti certificate FIPS. In entrambi i casi, lo strumento utente e lo script WolfGuard sono denominati `wg-fips` e `wg-fips-quick`, a testimonianza del loro utilizzo di algoritmi approvati FIPS indipendentemente dallo stato di certificazione FIPS. Le versioni certificate e non certificate di WolfGuard sono completamente interoperabili tra loro, ma non possono interoperare con WireGuard. L'opzione `--enable-intelasm` dovrebbe essere utilizzata solo con target CPU x86 e, per FIPS, solo su fonti FIPS che la supportano. Contattaci a <[email protected]> per maggiori informazioni. L'opzione `--enable-wolfguard` abilita il set minimo di funzionalità della libreria/modulo richiesto per WolfGuard. Per un set di funzionalità più completo, usa invece `--enable-all-crypto`. I comandi preceduti da `$` devono essere eseguiti da un utente non privilegiato, mentre quelli con `#` vanno eseguiti con privilegi di root, ma nello stesso contesto della directory di lavoro stabilita. Nota che se si utilizza un archivio di rilascio wolfSSL invece dei sorgenti `git`, la versione deve essere 5.8.4 o successiva. ### Compilazione e installazione di sorgenti `git` non-FIPS (1) **Crea una directory di primo livello per i sorgenti e popolala**: ``` $ mkdir wolf-sources $ cd wolf-sources $ git clone https://github.com/wolfssl/wolfssl --branch nightly-snapshot $ git clone https://github.com/wolfssl/wolfguard $ (cd wolfssl && ./autogen.sh) ``` (2) **Compila e installa la libreria utente libwolfssl**: Nota: questo passaggio è opzionale su Linux, dove per impostazione predefinita `wg-fips` scarica le operazioni di generazione e conversione delle chiavi sul modulo kernel, invece di eseguirle internamente. ``` $ cd wolfssl $ ./configure --quiet --enable-wolfguard --enable-all-asm $ make -j $ ./wolfcrypt/test/testwolfcrypt # make install $ cd .. ``` (3) **Compila e installa lo strumento utente `wg-fips`** -- nota: l'installazione sposterà gli eseguibili e le pagine man esistenti di WireGuard `wg` e `wg-quick` nelle directory di destinazione (se presenti) rispettivamente in `wg-wireguard` e `wg-wireguard-quick`, e installerà collegamenti simbolici per `wg` e `wg-quick` che puntano alle versioni WolfGuard. ``` $ cd wolfguard/user-src $ make -j # make install $ cd ../.. ``` Per forzare l'uso delle operazioni chiave interne su Linux, invece del default di scarico sul modulo kernel, sostituisci `make -j` con `make -j NO_IPC_LLCRYPTO=1`. È disponibile il supporto per chiavi pubbliche compresse, le cui lunghezze esportate in base64 sono le stesse delle chiavi pubbliche Curve25519 di WireGuard. Ciò può essere abilitato sostituendo ``` $ make -j EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION ``` nel comando sopra. Nota, tuttavia, che WolfGuard con `WG_USE_PUBLIC_KEY_COMPRESSION` è incompatibile con le impostazioni predefinite di WolfGuard -- quando è impostato, le chiavi pubbliche compresse vengono fornite e attese, sia nella configurazione locale che nelle negoziazioni di rete. (4) **Compila e installa il modulo kernel libwolfssl.** Sostituisci `/usr/src/linux` con il percorso del tuo albero dei sorgenti del kernel target, che deve essere completamente configurato e compilato, e corrispondere esattamente al kernel che avvierai sul tuo sistema target. Il `modprobe` alla fine presuppone che tu stia puntando al sistema nativo in esecuzione. ``` $ cd wolfssl $ ./configure --quiet --enable-wolfguard --enable-cryptonly --enable-intelasm \ --enable-linuxkm --with-linux-source=/usr/src/linux \ --prefix=$(pwd)/linuxkm/build $ make -j module # make install # modprobe libwolfssl ``` Prima di mettere in produzione il modulo kernel libwolfssl, dovresti compilarlo e caricarlo con l'auto-test esteso abilitato. Sostituisci la ricetta `./configure` sopra con la seguente: ``` $ ./configure --quiet --enable-wolfguard --enable-cryptonly --enable-intelasm \ --enable-linuxkm --with-linux-source=/usr/src/linux \ --prefix=$(pwd)/linuxkm/build --enable-crypttests \ CFLAGS=-DWOLFSSL_LINUXKM_VERBOSE_DEBUG ``` Le opzioni extra non sono appropriate per la produzione, ma un modulo configurato con esse dovrebbe essere caricato in un ambiente runtime rappresentativo per confermare che tutti gli algoritmi funzionino correttamente. (5) **Compila e installa il modulo kernel WolfGuard.** Ancora, sostituisci `/usr/src/linux` con il percorso del tuo albero dei sorgenti del kernel target, e sostituisci `6.16.5-gentoo` con il valore effettivo restituito da `uname -r` sul sistema target. E ancora, il `modprobe` dopo la compilazione presuppone che tu stia puntando al sistema nativo in esecuzione. ``` $ cd ../wolfguard/kernel-src $ make -j KERNELDIR=/usr/src/linux KERNELRELEASE=6.16.5-gentoo # make install # modprobe wolfguard $ ../user-src/wg-fips genkey | ../user-src/wg-fips pubkey ``` Il valore `KERNELRELEASE` è, di fatto, il nome esatto della directory sotto `/lib/modules/` dove sono installati i moduli del kernel target. Le operazioni `genkey` e `pubkey` nell'ultima riga sono test di funzionalità di base. Se tutto è a posto, avranno successo e stamperanno una chiave pubblica casuale. Come per la compilazione di `wg-fips` sopra, il supporto per chiavi pubbliche compresse può essere abilitato aggiungendo `EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION` alla ricetta `make` sopra. L'impostazione `WG_USE_PUBLIC_KEY_COMPRESSION` deve essere corrispondente in tutto l'ecosistema. Se tutto quanto sopra ha successo, allora sei ora pronto per attivare i tunnel WolfGuard. I playbook e gli script esistenti per WireGuard possono essere usati direttamente, a patto che si sostituisca `/etc/wolfguard` a `/etc/wireguard` e si generino tutte le chiavi usando lo strumento WolfGuard `wg-fips` (`wg` a questo punto sarà un collegamento a `wg-fips`). ### Compilazione e installazione di sorgenti FIPS Le versioni certificate FIPS dell'archivio sorgente wolfssl sono fornite separatamente. Contatta <[email protected]>. (1) **Crea una directory di primo livello per i sorgenti e popolala.** Questa procedura presuppone un archivio wolfssl in formato `7z` -- sostituisci `tar -xf` se l'archivio è un `.tar.gz`. In entrambi i casi, regola la ricetta `ln -s` per assicurarti che `wolfssl` sia un collegamento simbolico alla directory wolfssl estratta. Nota anche che gli archivi del modulo kernel FIPS sono distinti dagli archivi non kernel, sebbene siano sicuri da usare per compilare la libreria utente FIPS, come mostrato di seguito. ``` $ mkdir wolf-sources $ cd wolf-sources $ 7z x ~/Downloads/wolfssl-X-fips-linuxvX-kernel.7z $ ln -s wolfssl-X-fips-linuxvX-kernel wolfssl $ git clone https://github.com/wolfssl/wolfguard ``` (2) **Compila e installa la libreria utente libwolfssl.** Nota: questo passaggio è opzionale su Linux, dove per impostazione predefinita `wg-fips` scarica le operazioni di generazione e conversione delle chiavi sul modulo kernel, invece di eseguirle internamente. ``` $ cd wolfssl $ ./configure --quiet --enable-fips=vX --enable-wolfguard $ make -j $ ./fips-hash.sh $ make -j $ ./wolfcrypt/test/testwolfcrypt # make install $ cd .. ``` Nota: l'argomento per `--enable-fips` deve corrispondere alla variante FIPS dell'archivio. Attualmente gli argomenti più adatti per l'uso con WolfGuard sono `v5.2.4` e `v6`. (3) **Compila e installa lo strumento utente `wg-fips`** -- nota: l'installazione sposterà gli eseguibili e le pagine man esistenti di WireGuard `wg` e `wg-quick` nelle directory di destinazione (se presenti) rispettivamente in `wg-wireguard` e `wg-wireguard-quick`, e installerà collegamenti simbolici per `wg` e `wg-quick` che puntano alle versioni WolfGuard. ``` $ cd wolfguard/user-src $ make -j # make install $ cd ../.. ``` Per forzare l'uso delle operazioni chiave interne su Linux, invece del default di scarico sul modulo kernel, sostituisci `make -j` con `make -j NO_IPC_LLCRYPTO=1`. (4) **Compila e installa il modulo kernel libwolfssl.** Sostituisci `/usr/src/linux` con il percorso del tuo albero dei sorgenti del kernel target, che deve essere completamente configurato e compilato, e corrispondere esattamente al kernel che avvierai sul tuo sistema target. Questo è un processo in due fasi. Prima compilerai e installerai il modulo con un hash di integrità errato. Poi lo caricherai per catturare l'hash corretto, che uscirà presto con un errore previsto "Operation canceled". Poi ricompilerai e caricherai il modulo con l'hash corretto. Nota che queste istruzioni presuppongono di puntare al sistema nativo. Nota anche che la versione FIPS di libwolfssl più bassa compatibile con la modalità kernel Linux è `v5.2.4`. ``` $ cd wolfssl $ ./configure --quiet --enable-fips=vX --enable-wolfguard --enable-cryptonly \ --enable-linuxkm --with-linux-source=/usr/src/linux \ --prefix=$(pwd)/linuxkm/build $ make -j module # make install # modprobe libwolfssl ``` (Aspettati un'uscita anticipata del `modprobe` sopra, con un messaggio "Operation canceled".) ``` $ NEWHASH=$(dmesg | awk '{if (match($0, " new hash \"([^\"]+)\" ", hash_a)) { hash = hash_a[1]; }} END {print hash}') $ sed --in-place=.bak "s/^\".*\";/\"${NEWHASH}\";/" wolfcrypt/src/fips_test.c $ make -j module # make install # modprobe libwolfssl ``` Se il secondo `modprobe` fallisce come il primo, con un altro messaggio "Update verifyCore[] in fips_test.c with new hash ..." nel log del kernel, allora la tua toolchain e/o la configurazione del kernel target stanno impedendo una build riproducibile. In tal caso, dovresti usare questa strategia alternativa, sostituendo i passaggi dopo il comando `NEWHASH=` sopra: ``` $ make module-update-fips-hash FIPS_HASH="$NEWHASH" # make install # modprobe libwolfssl ``` Prima di mettere in produzione il modulo kernel libwolfssl, dovresti compilarlo e caricarlo con l'auto-test esteso abilitato. Per fare ciò, sostituisci la ricetta `./configure` sopra con la seguente: ``` $ ./configure --quiet --enable-fips=vX --enable-wolfguard --enable-cryptonly \ --enable-linuxkm --with-linux-source=/usr/src/linux \ --prefix=$(pwd)/linuxkm/build --enable-crypttests \ CFLAGS=-DWOLFSSL_LINUXKM_VERBOSE_DEBUG ``` Le opzioni extra non sono appropriate per la produzione, ma un modulo configurato con esse dovrebbe essere caricato in un ambiente runtime rappresentativo per confermare che tutti gli algoritmi funzionino correttamente. (5) **Compila e installa il modulo kernel WolfGuard.** Ancora, sostituisci `/usr/src/linux` con il percorso del tuo albero dei sorgenti del kernel target, e sostituisci `6.16.5-gentoo` con il valore effettivo restituito da `uname -r` sul sistema target. ``` $ cd ../wolfguard/kernel-src $ make -j KERNELDIR=/usr/src/linux KERNELRELEASE=6.16.5-gentoo # make install # modprobe wolfguard $ ../user-src/wg-fips genkey | ../user-src/wg-fips pubkey ``` Le operazioni `genkey` e `pubkey` nell'ultima riga sono test di funzionalità di base. Se tutto è a posto, avranno successo e stamperanno una chiave pubblica casuale. Come per la procedura non certificata FIPS, se tutto quanto sopra ha successo, allora sei ora pronto per attivare i tunnel WolfGuard. I playbook e gli script esistenti per WireGuard possono essere usati direttamente, a patto che si sostituisca `/etc/wolfguard` a `/etc/wireguard` e si generino tutte le chiavi usando lo strumento WolfGuard `wg-fips` (`wg` a questo punto sarà un collegamento a `wg-fips`). Tuttavia, nota che alcune applicazioni client e framework di automazione WireGuard si aspettano che le chiavi pubbliche WireGuard siano esportate con esattamente 44 caratteri di base64. Le chiavi pubbliche WolfGuard sono approssimativamente il doppio di quella lunghezza, a meno che non siano compilate con `WG_USE_PUBLIC_KEY_COMPRESSION`, che attualmente non è supportato in FIPS v5, ma è supportato in FIPS v6 e successive.
