wolfssl/wolfguardFIPS 140-3準拠のVPNカーネルモジュールおよびユーザーツール、AES-256-GCM、SHA2-256、SECP256R1暗号を使用したWireGuardのドロップイン代替品で、セキュアなトンネリングを実現します。
# WolfGuard VPNとFIPS 140-3暗号化 WolfGuardは、wolfSSLのFIPS準拠のリファクタリングであり、Linuxカーネルベースの [WireGuard](https://www.wireguard.com/)を元に、Jason Donenfeldによって設計および作成されました。 使用方法は基本的に同一です。WolfGuardには2つの主要コンポーネントがあります：`wolfguard.ko`カーネルモジュールと`wg-fips`設定ツールです。 `wolfguard.ko`は`libwolfssl.ko`カーネルモジュールに依存し、`wg-fips`は`libwolfssl.so`ライブラリに依存します — これらの依存関係は同じ[wolfSSL](https://github.com/wolfssl/wolfssl)ソースからビルドされ、それぞれカーネルモジュールとユーザーライブラリの設定が使用されます。 `wg-fips-quick`スクリプトはWireGuardの`wg-quick`とまったく同じように動作しますが、設定スクリプトは`/etc/wolfguard`にあり、SECP256R1公開鍵と秘密鍵を含みます。 インストールbinディレクトリには、`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の暗号を以下のように再マッピングします： | Algo category | WireGuard | WolfGuard | | :----------- | :-------- | :-------- | | ECDH | Curve25519 | SECP256R1 | | AEAD | XChaCha20-Poly1305 | AES-256-GCM | | digest | Blake2s | SHA2-256 | | authenticating digest | Blake2s-HMAC | SHA2-256-HMAC | | internal hash | SipHash | SHA2-256 | | DRBG | ChaCha20 DRBG | SHA2-256 Hash-DRBG | WolfGuardとWireGuardは同じシステム上で共存でき、同時にWolfGuardトンネルとWireGuardトンネルを確立できることに注意してください。 `libwolfssl.ko`が`--enable-intelasm`で設定されている場合、WolfGuardのパフォーマンスはCPUアクセラレーションされたWireGuardに匹敵するかそれを上回ります。これはAES-256-GCMおよびSHA2-256演算のCPUアクセラレーションによるものです。`--enable-intelasm`がない場合、WolfGuardはCPUアクセラレーションされたWireGuardよりもやや遅くなりますが、それでも最新のCPU上でギガビットイーサネットを飽和させることができます。 ## ビルドとインストール 以下に2つの手順を示します。1つ目は非FIPSソースからのビルド、2つ目はFIPS認証ソースからのビルドです。どちらの場合も、WolfGuardユーザーツールとスクリプトはそれぞれ`wg-fips`および`wg-fips-quick`と名前が付けられており、FIPS認証ステータスに関係なくFIPS承認アルゴリズムを使用していることを反映しています。FIPS認証済みおよび非認証のWolfGuardビルドは相互に完全に互換性がありますが、WireGuardとの相互運用はできません。 `--enable-intelasm`オプションはx86 CPUターゲットでのみ使用し、FIPSの場合はそれをサポートするFIPSソースでのみ使用してください。詳細については<[email protected]>までお問い合わせください。 `--enable-wolfguard`オプションは、WolfGuardに必要な最小限のライブラリ/モジュール機能セットを有効にします。より包括的な機能セットの場合は、代わりに`--enable-all-crypto`を使用してください。 `$`が接頭辞として付いたコマンドは非特権ユーザーが実行し、`#`が付いたコマンドはroot権限で、同じ作業ディレクトリコンテキスト内で実行します。 wolfSSLリリースアーカイブを`git`ソースの代わりに使用する場合、リリースはバージョン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ではオプションです。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`実行ファイルとマニュアルページ（存在する場合）がそれぞれ`wg-wireguard`および`wg-wireguard-quick`に移動され、WolfGuardバージョンを指す`wg`および`wg-quick`のシンボリックリンクがインストールされます。 ``` $ cd wolfguard/user-src $ make -j # make install $ cd ../.. ``` Linuxでデフォルトのカーネルモジュールへのオフロードではなく内部鍵操作を強制するには、`make -j`を`make -j NO_IPC_LLCRYPTO=1`に置き換えます。 圧縮公開鍵のサポートが利用可能です。これにより、base64エクスポート長がWireGuard Curve25519公開鍵と同じになります。これは、上記の`make -j`を次のように置き換えることで有効にできます： ``` $ make -j EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION ``` ただし、`WG_USE_PUBLIC_KEY_COMPRESSION`を有効にしたWolfGuardはデフォルトの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`ビルドと同様に、圧縮公開鍵サポートは上記の`make`レシピに`EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION`を追加することで有効にできます。`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.gz`の場合は`tar -xf`に置き換えてください。いずれの場合も、`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ではオプションです。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`実行ファイルとマニュアルページ（存在する場合）がそれぞれ`wg-wireguard`および`wg-wireguard-quick`に移動され、WolfGuardバージョンを指す`wg`および`wg-quick`のシンボリックリンクがインストールされます。 ``` $ cd wolfguard/user-src $ make -j # make install $ cd ../.. ``` Linuxでデフォルトのカーネルモジュールへのオフロードではなく内部鍵操作を強制するには、`make -j`を`make -j NO_IPC_LLCRYPTO=1`に置き換えます。 (4) **libwolfsslカーネルモジュールをビルドしてインストールする。** `/usr/src/linux`を実際のターゲットカーネルソースツリーへのパスに置き換えます。このソースツリーは完全に設定およびビルドされており、ターゲットシステムで起動するカーネルと正確に一致する必要があります。 これは2段階のプロセスです。まず、誤った整合性ハッシュでモジュールをビルドしてインストールします。次に、それをロードして正しいハッシュをキャプチャします。正しいハッシュがキャプチャされると、期待される「Operation canceled」エラーで早期終了します。その後、正しいハッシュでモジュールを再ビルドしてロードします。これらの手順はネイティブシステムを対象としていることを前提としています。また、Linuxカーネルモードと互換性のある最低のlibwolfssl FIPSバージョンは`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`は早期終了し、「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 ``` 2番目の`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`を使用してビルドしない限り、その約2倍の長さになります。この機能は現在FIPS v5ではサポートされていませんが、FIPS v6以降ではサポートされています。
