WolfGuard VPN с криптографией FIPS 140-3

WolfGuard — это соответствующий требованиям FIPS рефакторинг WireGuard на основе ядра Linux от wolfSSL, изначально разработанный Джейсоном Доненфельдом. Использование практически идентично. WolfGuard состоит из двух основных компонентов: модуля ядра wolfguard.ko и утилиты настройки wg-fips. wolfguard.ko зависит от модуля ядра libwolfssl.ko, а wg-fips зависит от библиотеки libwolfssl.so — эти зависимости собираются из одного и того же исходного кода wolfSSL с конфигурацией для модуля ядра и пользовательской библиотеки соответственно. Скрипт wg-fips-quick работает точно так же, как wg-quick в WireGuard, но с файлами конфигурации в /etc/wolfguard, содержащими открытые и закрытые ключи SECP256R1.

В каталог установки устанавливаются символические ссылки: wg на wg-fips и wg-quick на wg-fips-quick для прозрачной замены WireGuard. Если во время установки найдены исполняемые файлы WireGuard, они переименовываются в wg-wireguard и wg-wireguard-quick, при этом wg-wireguard-quick модифицируется для вызова wg-wireguard, и сохраняется резервная копия wg-wireguard-quick.unpatched.

WolfGuard переназначает криптографию WireGuard следующим образом:

Обратите внимание, что WolfGuard и WireGuard могут сосуществовать в одной системе, одновременно устанавливая туннели WolfGuard и WireGuard.

Если libwolfssl.ko сконфигурирован с --enable-intelasm, производительность WolfGuard соответствует или превышает производительность WireGuard с аппаратным ускорением благодаря ускорению операций AES-256-GCM и SHA2-256 на CPU. Без --enable-intelasm WolfGuard немного медленнее WireGuard с аппаратным ускорением, но все же способен насытить гигабитный Ethernet на современных CPU.

Сборка и установка

Ниже приведены два набора инструкций: первый для сборки из не-FIPS исходников, второй для сборки из сертифицированных по FIPS исходников. В обоих случаях пользовательская утилита и скрипт WolfGuard называются wg-fips и wg-fips-quick, что отражает использование алгоритмов, одобренных FIPS, независимо от статуса сертификации FIPS. Сертифицированные и несертифицированные сборки WolfGuard полностью совместимы друг с другом, но не могут взаимодействовать с WireGuard.

Опцию --enable-intelasm следует использовать только для целей x86 CPU, а для FIPS — только для тех исходников FIPS, которые её поддерживают. Свяжитесь с нами по адресу [email protected] для получения дополнительной информации.

Опция --enable-wolfguard включает минимальный набор функций библиотеки/модуля, необходимый для WolfGuard. Для более полного набора функций используйте --enable-all-crypto.

Команды с префиксом $ должны выполняться непривилегированным пользователем, а команды с # — с привилегиями root, но в том же рабочем каталоге.

Обратите внимание, что если вместо исходников git используется архив выпуска wolfSSL, версия должна быть 5.8.4 или новее.

Сборка и установка не-FIPS исходников git

(1) Создайте корневой каталог для исходников и заполните его:

$ 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) Соберите и установите пользовательскую библиотеку libwolfssl:

Примечание: этот шаг необязателен в Linux, где по умолчанию wg-fips переносит операции генерации и преобразования ключей в модуль ядра, а не выполняет их внутри.

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

(3) Соберите и установите пользовательскую утилиту wg-fips — обратите внимание, что установка переместит существующие исполняемые файлы WireGuard wg и wg-quick и страницы man в целевых каталогах (если они есть) в wg-wireguard и wg-wireguard-quick соответственно, и установит символические ссылки для wg и wg-quick, указывающие на версии WolfGuard.

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

Чтобы принудительно использовать внутренние операции с ключами в Linux вместо переноса в модуль ядра по умолчанию, замените make -j на make -j NO_IPC_LLCRYPTO=1.

Поддерживаются сжатые открытые ключи, длина которых в кодировке base64 такая же, как у открытых ключей Curve25519 WireGuard. Это можно включить, заменив

$ make -j EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION

в приведённом выше. Однако обратите внимание, что WolfGuard с WG_USE_PUBLIC_KEY_COMPRESSION несовместим с настройками WolfGuard по умолчанию — при его включении сжатые открытые ключи предоставляются и ожидаются как в локальной конфигурации, так и при согласовании по сети.

(4) Соберите и установите модуль ядра libwolfssl. Замените /usr/src/linux на путь к вашему дереву исходных кодов целевого ядра, которое должно быть полностью настроено и собрано и точно соответствовать ядру, которое вы будете загружать в целевой системе. modprobe в конце предполагает, что вы работаете с нативной запущенной системой.

$ 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

Прежде чем запускать модуль ядра libwolfssl в производство, вы должны собрать и загрузить его с включённым расширенным самотестированием. Замените приведённый выше рецепт ./configure на следующий:

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

Дополнительные опции не подходят для производства, но модуль, сконфигурированный с ними, следует загрузить в репрезентативной среде выполнения, чтобы убедиться, что все алгоритмы работают правильно.

(5) Соберите и установите модуль ядра WolfGuard. Снова замените /usr/src/linux на путь к вашему дереву исходных кодов целевого ядра, а 6.16.5-gentoo — на фактическое значение, возвращаемое uname -r в целевой системе. И снова modprobe после сборки предполагает, что вы работаете с нативной запущенной системой.

$ 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

Значение KERNELRELEASE — это, по сути, точное имя каталога в /lib/modules/, куда устанавливаются модули целевого ядра.

Команды genkey и pubkey в последней строке — это базовые тесты функциональности. Если всё в порядке, они выполнятся успешно и выведут случайный открытый ключ.

Как и для сборки wg-fips выше, поддержка сжатых открытых ключей может быть включена добавлением EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION в приведённый выше рецепт make. Настройка WG_USE_PUBLIC_KEY_COMPRESSION должна быть согласована во всей экосистеме.

Если всё вышеперечисленное выполнено успешно, вы готовы поднимать туннели WolfGuard. Существующие плейбуки и скрипты для WireGuard могут быть использованы напрямую при условии замены /etc/wireguard на /etc/wolfguard и генерации всех ключей с помощью утилиты WolfGuard wg-fips (wg на этом этапе будет ссылкой на wg-fips).

Сборка и установка FIPS исходников

Сертифицированные по FIPS версии архива исходников wolfssl предоставляются отдельно. Свяжитесь по адресу [email protected].

(1) Создайте корневой каталог для исходников и заполните его. Эта процедура предполагает, что архив wolfssl находится в формате 7z — замените tar -xf, если архив .tar.gz. В любом случае настройте рецепт ln -s, чтобы убедиться, что wolfssl является символической ссылкой на извлечённый каталог wolfssl. Также обратите внимание, что архивы модулей ядра FIPS отличаются от архивов не для ядра, хотя их можно использовать для сборки пользовательской библиотеки FIPS, как показано ниже.

$ 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) Соберите и установите пользовательскую библиотеку libwolfssl.

Примечание: этот шаг необязателен в Linux, где по умолчанию wg-fips переносит операции генерации и преобразования ключей в модуль ядра, а не выполняет их внутри.

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

Обратите внимание, аргумент --enable-fips должен соответствовать варианту FIPS архива. В настоящее время наиболее подходящими аргументами для использования с WolfGuard являются v5.2.4 и v6.

(3) Соберите и установите пользовательскую утилиту wg-fips — обратите внимание, что установка переместит существующие исполняемые файлы WireGuard wg и wg-quick и страницы man в целевых каталогах (если они есть) в wg-wireguard и wg-wireguard-quick соответственно, и установит символические ссылки для wg и wg-quick, указывающие на версии WolfGuard.

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

Чтобы принудительно использовать внутренние операции с ключами в Linux вместо переноса в модуль ядра по умолчанию, замените make -j на make -j NO_IPC_LLCRYPTO=1.

(4) Соберите и установите модуль ядра libwolfssl. Замените /usr/src/linux на путь к вашему дереву исходных кодов целевого ядра, которое должно быть полностью настроено и собрано и точно соответствовать ядру, которое вы будете загружать в целевой системе.

Это двухэтапный процесс. Сначала вы соберёте и установите модуль с неверным хешем целостности. Затем вы загрузите его, чтобы захватить правильный хеш, при этом модуль завершится досрочно с ожидаемой ошибкой «Операция отменена». Затем вы пересоберёте и загрузите модуль с правильным хешем. Обратите внимание, что эти инструкции предполагают, что вы работаете с нативной системой. Обратите также внимание, что минимальная версия libwolfssl FIPS, совместимая с режимом ядра 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

(Ожидается досрочное завершение вышеуказанного modprobe с сообщением «Операция отменена».)

$ 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

Если второй modprobe завершится с ошибкой, как и первый, с другим сообщением «Update verifyCore[] in fips_test.c with new hash ...» в журнале ядра, значит, ваша цепочка инструментов и/или конфигурация целевого ядра нарушают воспроизводимую сборку. В этом случае вам следует использовать следующую альтернативную стратегию, заменив шаги после команды NEWHASH= выше:

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

Прежде чем запускать модуль ядра libwolfssl в производство, вы должны собрать и загрузить его с включённым расширенным самотестированием. Для этого замените приведённый выше рецепт ./configure на следующий:

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

Дополнительные опции не подходят для производства, но модуль, сконфигурированный с ними, следует загрузить в репрезентативной среде выполнения, чтобы убедиться, что все алгоритмы работают правильно.

(5) Соберите и установите модуль ядра WolfGuard. Снова замените /usr/src/linux на путь к вашему дереву исходных кодов целевого ядра, а 6.16.5-gentoo — на фактическое значение, возвращаемое uname -r в целевой системе.

$ 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

Команды genkey и pubkey в последней строке — это базовые тесты функциональности. Если всё в порядке, они выполнятся успешно и выведут случайный открытый ключ.

Как и в процедуре без сертификации FIPS, если всё вышеперечисленное выполнено успешно, вы готовы поднимать туннели WolfGuard. Существующие плейбуки и скрипты для WireGuard могут быть использованы напрямую при условии замены /etc/wireguard на /etc/wolfguard и генерации всех ключей с помощью утилиты WolfGuard wg-fips (wg на этом этапе будет ссылкой на wg-fips). Однако обратите внимание, что некоторые клиентские приложения и фреймворки автоматизации WireGuard ожидают, что открытые ключи WireGuard будут экспортированы ровно 44 символами base64. Открытые ключи WolfGuard примерно вдвое длиннее, если не собраны с WG_USE_PUBLIC_KEY_COMPRESSION, который в настоящее время не поддерживается в FIPS v5, но поддерживается в FIPS v6 и более поздних версиях.