WolfGuard VPN com criptografia FIPS 140-3

WolfGuard é a reformulação compatível com FIPS do WireGuard baseado no kernel Linux, originalmente projetado e escrito por Jason Donenfeld. O uso é essencialmente idêntico. Existem dois componentes principais do WolfGuard: o módulo de kernel wolfguard.ko e a ferramenta de configuração wg-fips. wolfguard.ko depende do módulo de kernel libwolfssl.ko, e wg-fips depende da biblioteca libwolfssl.so — essas dependências são construídas a partir da mesma fonte wolfSSL, com configuração de módulo de kernel e biblioteca de usuário, respectivamente. O script wg-fips-quick funciona exatamente como wg-quick no WireGuard, mas com scripts de configuração em /etc/wolfguard contendo chaves públicas e privadas SECP256R1.

Links simbólicos são instalados no diretório bin de instalação de wg para wg-fips, e de wg-quick para wg-fips-quick, para substituição transparente do WireGuard. Se executáveis do WireGuard forem encontrados durante a instalação, eles são renomeados para wg-wireguard e wg-wireguard-quick, com wg-wireguard-quick modificado para chamar wg-wireguard, e uma cópia de segurança deixada em wg-wireguard-quick.unpatched.

WolfGuard remapeia a criptografia do WireGuard da seguinte forma:

Note que WolfGuard e WireGuard podem coexistir no mesmo sistema, estabelecendo simultaneamente túneis WolfGuard e WireGuard.

Se libwolfssl.ko for configurado com --enable-intelasm, o desempenho do WolfGuard iguala ou supera o do WireGuard acelerado por CPU, graças à aceleração da CPU das operações AES-256-GCM e SHA2-256. Sem --enable-intelasm, o WolfGuard é ligeiramente mais lento que o WireGuard acelerado por CPU, mas ainda é capaz de saturar ethernet gigabit em CPUs modernas.

Construção e Instalação

Abaixo estão dois conjuntos de instruções, o primeiro para construir a partir de fontes não-FIPS, e o segundo para construir a partir de fontes certificadas FIPS. Em ambos os casos, a ferramenta de usuário e script do WolfGuard são nomeados wg-fips e wg-fips-quick, refletindo seu uso de algoritmos aprovados pelo FIPS, independentemente do status de certificação FIPS. As construções certificadas FIPS e não certificadas do WolfGuard são totalmente interoperáveis entre si, mas não podem interoperar com WireGuard.

A opção --enable-intelasm deve ser usada apenas com alvos de CPU x86, e para FIPS, apenas em fontes FIPS que a suportam. Contacte-nos em [email protected] para mais informações.

A opção --enable-wolfguard habilita o conjunto mínimo de recursos de biblioteca/módulo necessário para WolfGuard. Para um conjunto de recursos mais abrangente, use --enable-all-crypto em vez disso.

Comandos prefixados com $ devem ser executados por um usuário não privilegiado, enquanto aqueles com # devem ser executados com privilégios de root, mas no mesmo contexto de diretório de trabalho estabelecido.

Note que se um arquivo de lançamento do wolfSSL for usado em vez de fontes git, o lançamento deve ser versão 5.8.4 ou mais recente.

Construindo e instalando fontes git não-FIPS

(1) Crie um diretório de nível superior para as fontes e popule-o:

$ 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) Construa e instale a biblioteca de usuário libwolfssl:

Nota: este passo é opcional no Linux, onde por padrão wg-fips descarrega as operações de geração e conversão de chaves para o módulo do kernel, em vez de realizá-las internamente.

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

(3) Construa e instale a ferramenta de usuário wg-fips -- nota: a instalação moverá os executáveis e páginas de manual existentes do WireGuard wg e wg-quick nos diretórios de destino (se presentes) para wg-wireguard e wg-wireguard-quick respectivamente, e instalará links simbólicos para wg e wg-quick que apontam para as versões WolfGuard.

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

Para forçar o uso de operações de chave internas no Linux, em vez do descarregamento padrão para o módulo do kernel, substitua make -j por make -j NO_IPC_LLCRYPTO=1.

Há suporte disponível para chaves públicas comprimidas, cujos comprimentos exportados em base64 são os mesmos que as chaves públicas Curve25519 do WireGuard. Isso pode ser habilitado substituindo

$ make -j EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION

no acima. Note, no entanto, que WolfGuard com WG_USE_PUBLIC_KEY_COMPRESSION é incompatível com as configurações padrão do WolfGuard -- quando ativado, chaves públicas comprimidas são fornecidas e esperadas, tanto na configuração local quanto nas negociações pela rede.

(4) Construa e instale o módulo de kernel libwolfssl. Substitua /usr/src/linux pelo caminho para a árvore de fontes do kernel alvo real, que deve estar totalmente configurada e construída, e corresponder precisamente ao kernel que você inicializará no seu sistema alvo. O modprobe no final assume que você está visando o sistema nativo em execução.

$ 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

Antes de colocar o módulo de kernel libwolfssl em produção, você deve construí-lo e carregá-lo com autoteste estendido ativado. Substitua a receita ./configure acima pela seguinte:

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

As opções extras não são apropriadas para produção, mas um módulo configurado com elas deve ser carregado em um ambiente de tempo de execução representativo para confirmar que todos os algoritmos funcionam corretamente.

(5) Construa e instale o módulo de kernel WolfGuard. Novamente, substitua /usr/src/linux pelo caminho para a árvore de fontes do kernel alvo real, e substitua 6.16.5-gentoo pelo valor real retornado por uname -r no sistema alvo. E novamente, o modprobe após a construção assume que você está visando o sistema nativo em execução.

$ 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

O valor KERNELRELEASE é, efetivamente, o nome exato do diretório em /lib/modules/ onde os módulos do kernel alvo estão instalados.

As operações genkey e pubkey na linha final são testes básicos de funcionalidade. Se tudo estiver bem, terá sucesso e imprimirá uma chave pública aleatória.

Quanto à construção wg-fips acima, o suporte a chave pública comprimida pode ser habilitado adicionando EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION à receita make acima. A configuração WG_USE_PUBLIC_KEY_COMPRESSION deve ser correspondida em todo o ecossistema.

Se tudo acima tiver sucesso, então você está pronto para levantar túneis WolfGuard. Playbooks e scripts existentes para WireGuard podem ser usados diretamente, desde que você substitua /etc/wolfguard por /etc/wireguard, e gere todas as chaves usando a ferramenta WolfGuard wg-fips (wg será neste ponto um link para wg-fips).

Construindo e instalando fontes FIPS

Versões certificadas FIPS do arquivo de fontes wolfssl são fornecidas separadamente. Contacte [email protected].

(1) Crie um diretório de nível superior para as fontes e popule-o. Este procedimento assume um arquivo wolfssl no formato 7z -- substitua tar -xf se o arquivo for .tar.gz. Em ambos os casos, ajuste a receita ln -s para garantir que wolfssl seja um link simbólico para o diretório wolfssl extraído. Note também que arquivos de módulo de kernel FIPS são distintos de arquivos não-kernel, embora sejam seguros para uso na construção da biblioteca de usuário FIPS, conforme mostrado abaixo.

$ 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) Construa e instale a biblioteca de usuário libwolfssl.

Nota: este passo é opcional no Linux, onde por padrão wg-fips descarrega as operações de geração e conversão de chaves para o módulo do kernel, em vez de realizá-las internamente.

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

Nota: o argumento para --enable-fips deve corresponder à variante FIPS do arquivo. Atualmente, os argumentos mais adequados para uso do WolfGuard são v5.2.4 e v6.

(3) Construa e instale a ferramenta de usuário wg-fips -- nota: a instalação moverá os executáveis e páginas de manual existentes do WireGuard wg e wg-quick nos diretórios de destino (se presentes) para wg-wireguard e wg-wireguard-quick respectivamente, e instalará links simbólicos para wg e wg-quick que apontam para as versões WolfGuard.

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

Para forçar o uso de operações de chave internas no Linux, em vez do descarregamento padrão para o módulo do kernel, substitua make -j por make -j NO_IPC_LLCRYPTO=1.

(4) Construa e instale o módulo de kernel libwolfssl. Substitua /usr/src/linux pelo caminho para a árvore de fontes do kernel alvo real, que deve estar totalmente configurada e construída, e corresponder precisamente ao kernel que você inicializará no seu sistema alvo.

Este é um processo de duas etapas. Primeiro você construirá e instalará o módulo com um hash de integridade incorreto. Então você o carregará para capturar o hash correto, que sairá cedo com um erro esperado "Operation canceled". Então você reconstruirá e carregará o módulo com o hash correto. Note que estas instruções assumem que você está visando o sistema nativo. Note também que a versão FIPS mais baixa do libwolfssl compatível com modo de 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

(Espere saída precoce do modprobe acima, com uma mensagem "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 o segundo modprobe falhar como o primeiro, com outra mensagem "Update verifyCore[] in fips_test.c with new hash ..." no log do kernel, então sua toolchain e/ou configuração do kernel alvo estão impedindo a construção reproduzível. Nesse caso, você deve usar esta estratégia alternativa, substituindo os passos após o comando NEWHASH= acima:

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

Antes de colocar o módulo de kernel libwolfssl em produção, você deve construí-lo e carregá-lo com autoteste estendido ativado. Para fazer isso, substitua a receita ./configure acima pela seguinte:

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

As opções extras não são apropriadas para produção, mas um módulo configurado com elas deve ser carregado em um ambiente de tempo de execução representativo para confirmar que todos os algoritmos funcionam corretamente.

(5) Construa e instale o módulo de kernel WolfGuard. Novamente, substitua /usr/src/linux pelo caminho para a árvore de fontes do kernel alvo real, e substitua 6.16.5-gentoo pelo valor real retornado por uname -r no sistema alvo.

$ 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

As operações genkey e pubkey na linha final são testes básicos de funcionalidade. Se tudo estiver bem, terá sucesso e imprimirá uma chave pública aleatória.

Assim como no procedimento não certificado FIPS, se tudo acima tiver sucesso, então você está pronto para levantar túneis WolfGuard. Playbooks e scripts existentes para WireGuard podem ser usados diretamente, desde que você substitua /etc/wolfguard por /etc/wireguard, e gere todas as chaves usando a ferramenta WolfGuard wg-fips (wg será neste ponto um link para wg-fips). No entanto, note que algumas aplicações cliente e frameworks de automação do WireGuard esperam que as chaves públicas do WireGuard sejam exportadas com exatamente 44 caracteres de base64. As chaves públicas do WolfGuard têm aproximadamente o dobro desse comprimento, a menos que sejam construídas com WG_USE_PUBLIC_KEY_COMPRESSION, que atualmente não é suportado no FIPS v5, mas é suportado no FIPS v6 e posteriores.