WolfGuard VPN avec cryptographie FIPS 140-3

WolfGuard est le remaniement conforme FIPS de WireGuard basé sur le noyau Linux, conçu et développé à l'origine par Jason Donenfeld. L'utilisation est essentiellement identique. WolfGuard se compose de deux composants principaux : le module noyau wolfguard.ko et l'outil de configuration wg-fips. wolfguard.ko dépend du module noyau libwolfssl.ko, et wg-fips dépend de la bibliothèque libwolfssl.so — ces dépendances sont construites à partir de la même source wolfSSL, respectivement avec une configuration de module noyau et de bibliothèque utilisateur. Le script wg-fips-quick fonctionne exactement comme wg-quick dans WireGuard, mais avec des scripts de configuration dans /etc/wolfguard contenant des clés publiques et privées SECP256R1.

Des liens symboliques sont installés dans le répertoire bin d'installation de wg vers wg-fips, et de wg-quick vers wg-fips-quick, pour un remplacement transparent de WireGuard. Si des exécutables WireGuard sont trouvés lors de l'installation, ils sont renommés en wg-wireguard et wg-wireguard-quick, avec wg-wireguard-quick modifié pour appeler wg-wireguard, et une copie de sécurité laissée sous wg-wireguard-quick.unpatched.

WolfGuard remappe la cryptographie de WireGuard comme suit :

Notez que WolfGuard et WireGuard peuvent coexister sur le même système, en établissant simultanément des tunnels WolfGuard et WireGuard.

Si libwolfssl.ko est configuré avec --enable-intelasm, les performances de WolfGuard égalent ou dépassent celles de WireGuard accéléré par le CPU, grâce à l'accélération CPU des opérations AES-256-GCM et SHA2-256. Sans --enable-intelasm, WolfGuard est légèrement plus lent que WireGuard accéléré par le CPU, mais reste capable de saturer un réseau gigabit Ethernet sur des CPU modernes.

Construction et Installation

Vous trouverez ci-dessous deux séries d'instructions, la première pour la construction à partir de sources non-FIPS, et la seconde pour la construction à partir de sources certifiées FIPS. Dans les deux cas, l'outil utilisateur et le script WolfGuard sont nommés wg-fips et wg-fips-quick, reflétant leur utilisation d'algorithmes approuvés FIPS, quel que soit le statut de certification FIPS. Les constructions certifiées et non certifiées FIPS de WolfGuard sont entièrement interopérables entre elles, mais ne peuvent pas interopérer avec WireGuard.

L'option --enable-intelasm ne doit être utilisée qu'avec des cibles CPU x86, et pour FIPS, uniquement sur des sources FIPS qui la supportent. Contactez-nous à [email protected] pour plus d'informations.

L'option --enable-wolfguard active l'ensemble minimal de fonctionnalités de la bibliothèque/module requis pour WolfGuard. Pour un ensemble de fonctionnalités plus complet, utilisez plutôt --enable-all-crypto.

Les commandes précédées de $ doivent être exécutées par un utilisateur non privilégié, tandis que celles avec # doivent être exécutées avec les privilèges root, mais dans le même contexte de répertoire de travail établi.

Notez que si une archive de version wolfSSL est utilisée à la place des sources git, la version doit être la 5.8.4 ou plus récente.

Construction et installation des sources git non-FIPS

(1) Créez un répertoire de premier niveau pour les sources et remplissez-le :

$ 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) Construisez et installez la bibliothèque utilisateur libwolfssl :

Notez que cette étape est facultative sous Linux, où par défaut wg-fips délègue les opérations de génération et de conversion de clés au module noyau, plutôt que de les effectuer en interne.

$ cd wolfssl
$ ./configure --quiet --enable-wolfguard --enable-all-asm
$ make -j
$ ./wolfcrypt/test/testwolfcrypt
# make install
$ cd ..

(3) Construisez et installez l'outil utilisateur wg-fips — notez que l'installation déplacera les exécutables et pages de man WireGuard existants wg et wg-quick dans les répertoires de destination (s'ils sont présents) vers wg-wireguard et wg-wireguard-quick respectivement, et installera des liens symboliques pour wg et wg-quick pointant vers les versions WolfGuard.

$ cd wolfguard/user-src
$ make -j
# make install
$ cd ../..

Pour forcer l'utilisation d'opérations de clés internes sous Linux, au lieu de la délégation par défaut au module noyau, remplacez make -j par make -j NO_IPC_LLCRYPTO=1.

Un support est disponible pour les clés publiques compressées, dont les longueurs exportées en base64 sont les mêmes que les clés publiques Curve25519 de WireGuard. Cela peut être activé en substituant

$ make -j EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION

dans ce qui précède. Notez cependant que WolfGuard avec WG_USE_PUBLIC_KEY_COMPRESSION est incompatible avec les paramètres par défaut de WolfGuard — lorsqu'il est défini, des clés publiques compressées sont fournies et attendues, à la fois dans la configuration locale et dans les négociations sur le fil.

(4) Construisez et installez le module noyau libwolfssl. Remplacez /usr/src/linux par le chemin de votre arbre source du noyau cible réel, qui doit être entièrement configuré et construit, et correspondre exactement au noyau que vous allez démarrer sur votre système cible. La commande modprobe à la fin suppose que vous ciblez le système natif en cours d'exécution.

$ 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

Avant de mettre le module noyau libwolfssl en production, vous devez le construire et le charger avec les auto-tests étendus activés. Remplacez la recette ./configure ci-dessus par la suivante :

$ ./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

Les options supplémentaires ne sont pas appropriées pour la production, mais un module configuré avec celles-ci doit être chargé dans un environnement d'exécution représentatif pour confirmer que tous les algorithmes fonctionnent correctement.

(5) Construisez et installez le module noyau WolfGuard. Encore une fois, remplacez /usr/src/linux par le chemin de votre arbre source du noyau cible réel, et remplacez 6.16.5-gentoo par la valeur réelle retournée par uname -r sur le système cible. Et encore une fois, la commande modprobe après la construction suppose que vous ciblez le système natif en cours d'exécution.

$ 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

La valeur de KERNELRELEASE est, en pratique, le nom textuel du répertoire sous /lib/modules/ où les modules du noyau cible sont installés.

Les opérations genkey et pubkey dans la dernière ligne sont des tests de fonctionnalité de base. Si tout va bien, elles réussiront et afficheront une clé publique aléatoire.

Comme pour la construction wg-fips ci-dessus, le support des clés publiques compressées peut être activé en ajoutant EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION à la recette make ci-dessus. Le réglage WG_USE_PUBLIC_KEY_COMPRESSION doit être cohérent dans tout l'écosystème.

Si tout ce qui précède réussit, vous êtes maintenant prêt à mettre en place des tunnels WolfGuard. Les playbooks et scripts existants pour WireGuard peuvent être utilisés directement, à condition de substituer /etc/wolfguard à /etc/wireguard, et de générer toutes les clés à l'aide de l'outil WolfGuard wg-fips (wg sera alors un lien vers wg-fips).

Construction et installation des sources FIPS

Les versions certifiées FIPS de l'archive source wolfssl sont fournies séparément. Contactez [email protected].

(1) Créez un répertoire de premier niveau pour les sources et remplissez-le. Cette procédure suppose une archive wolfssl au format 7z — remplacez tar -xf si l'archive est un .tar.gz. Dans les deux cas, ajustez la recette ln -s pour garantir que wolfssl est un lien symbolique vers le répertoire wolfssl extrait. Notez également que les archives du module noyau FIPS sont distinctes des archives non-noyau, bien qu'elles soient sûres à utiliser pour la construction de la bibliothèque utilisateur FIPS, comme indiqué ci-dessous.

$ 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) Construisez et installez la bibliothèque utilisateur libwolfssl.

Notez que cette étape est facultative sous Linux, où par défaut wg-fips délègue les opérations de génération et de conversion de clés au module noyau, plutôt que de les effectuer en interne.

$ cd wolfssl
$ ./configure --quiet --enable-fips=vX --enable-wolfguard
$ make -j
$ ./fips-hash.sh
$ make -j
$ ./wolfcrypt/test/testwolfcrypt
# make install
$ cd ..

Notez que l'argument de --enable-fips doit correspondre à la variante FIPS de l'archive. Actuellement, les arguments les plus appropriés pour une utilisation avec WolfGuard sont v5.2.4 et v6.

(3) Construisez et installez l'outil utilisateur wg-fips — notez que l'installation déplacera les exécutables et pages de man WireGuard existants wg et wg-quick dans les répertoires de destination (s'ils sont présents) vers wg-wireguard et wg-wireguard-quick respectivement, et installera des liens symboliques pour wg et wg-quick pointant vers les versions WolfGuard.

$ cd wolfguard/user-src
$ make -j
# make install
$ cd ../..

Pour forcer l'utilisation d'opérations de clés internes sous Linux, au lieu de la délégation par défaut au module noyau, remplacez make -j par make -j NO_IPC_LLCRYPTO=1.

(4) Construisez et installez le module noyau libwolfssl. Remplacez /usr/src/linux par le chemin de votre arbre source du noyau cible réel, qui doit être entièrement configuré et construit, et correspondre exactement au noyau que vous allez démarrer sur votre système cible.

Il s'agit d'un processus en deux étapes. Vous allez d'abord construire et installer le module avec un hash d'intégrité incorrect. Ensuite, vous le chargerez pour capturer le hash correct, ce qui entraînera une sortie anticipée avec une erreur attendue « Opération annulée ». Ensuite, vous reconstruirez et chargerez le module avec le hash correct. Notez que ces instructions supposent que vous ciblez le système natif. Notez également que la version FIPS libwolfssl la plus basse compatible avec le mode noyau Linux est 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

(Attendez-vous à une sortie anticipée de la commande modprobe ci-dessus, avec un message « Opération annulée ».)

$ 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

Si la deuxième commande modprobe échoue comme la première, avec un autre message « Update verifyCore[] in fips_test.c with new hash ... » dans le journal du noyau, alors votre chaîne d'outils et/ou la configuration du noyau cible contrecarrent la construction reproductible. Dans ce cas, vous devez utiliser cette stratégie alternative, en remplaçant les étapes après la commande NEWHASH= ci-dessus :

$ make module-update-fips-hash FIPS_HASH="$NEWHASH"
# make install
# modprobe libwolfssl

Avant de mettre le module noyau libwolfssl en production, vous devez le construire et le charger avec les auto-tests étendus activés. Pour ce faire, remplacez la recette ./configure ci-dessus par la suivante :

$ ./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

Les options supplémentaires ne sont pas appropriées pour la production, mais un module configuré avec celles-ci doit être chargé dans un environnement d'exécution représentatif pour confirmer que tous les algorithmes fonctionnent correctement.

(5) Construisez et installez le module noyau WolfGuard. Encore une fois, remplacez /usr/src/linux par le chemin de votre arbre source du noyau cible réel, et remplacez 6.16.5-gentoo par la valeur réelle retournée par uname -r sur le système cible.

$ 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

Les opérations genkey et pubkey dans la dernière ligne sont des tests de fonctionnalité de base. Si tout va bien, elles réussiront et afficheront une clé publique aléatoire.

Comme pour la procédure non certifiée FIPS, si tout ce qui précède réussit, vous êtes alors prêt à mettre en place des tunnels WolfGuard. Les playbooks et scripts existants pour WireGuard peuvent être utilisés directement, à condition de substituer /etc/wolfguard à /etc/wireguard, et de générer toutes les clés à l'aide de l'outil WolfGuard wg-fips (wg sera alors un lien vers wg-fips). Cependant, notez que certaines applications clientes et frameworks d'automatisation WireGuard s'attendent à ce que les clés publiques WireGuard soient exportées avec exactement 44 caractères en base64. Les clés publiques WolfGuard sont environ deux fois plus longues, sauf si elles sont construites avec WG_USE_PUBLIC_KEY_COMPRESSION, ce qui n'est actuellement pas supporté dans FIPS v5, mais l'est dans FIPS v6 et ultérieur.