Código QR WireGuard: gerá-lo a partir de um .conf (qrencode)

Divulgação de afiliados: este artigo contém links de afiliado da Contabo. Se adquirir um VPS através deles, recebemos uma comissão sem qualquer custo adicional para você.

Escrever uma chave privada em base64 no teclado de um telemóvel é tão desagradável que as pessoas acabam por copiar as configurações através de aplicações de mensagens, o que é pior. O código QR existe para evitar ambas as coisas.

É um único comando, e a parte que vale a pena ler é o que acontece depois de o ler com a câmara.

Ainda não tem configuração, ou não tem um terminal à mão? O nosso gerador de configuração WireGuard cria o ficheiro do servidor e uma configuração de cliente por dispositivo, cada uma com o seu código QR, inteiramente no seu navegador: as chaves são geradas localmente com Curve25519 e nada é enviado para um servidor. Não converte um .conf existente; para isso, a ferramenta é o qrencode, abaixo. Também ainda não tem servidor? Os ficheiros que ele gera funcionam em qualquer VPS com um IPv4 público, por exemplo um VPS Cloud 4 da Contabo a 5,50 €/mês (link de afiliado, prazo de 24 meses, IVA incluído).

Gerar um código

Instale o codificador:

apt install qrencode      # Debian, Ubuntu
dnf install qrencode      # Fedora, RHEL

Depois, na máquina que contém a configuração do cliente:

qrencode -t ansiutf8 < /etc/wireguard/client1.conf

O código aparece no terminal, desenhado com caracteres de bloco. Abra o WireGuard no telemóvel, adicione um túnel, escolha a leitura a partir de código QR e aponte a câmara para o ecrã. O túnel é adicionado completo, com o nome, os endereços, as chaves e o peer.

Não existe nenhum formato especial. O código QR contém o ficheiro de configuração em texto simples. Tudo o que consegue ler um código QR consegue ler a sua configuração.

O tamanho raramente é uma limitação aqui. Uma configuração típica de cliente WireGuard tem algumas centenas de bytes, e a norma QR vai até à versão 40, uma grelha de 177 por 177 módulos que comporta 2 953 bytes no mais baixo dos seus quatro níveis de correção de erros. Uma configuração cabe folgadamente, e é precisamente por isso que tudo, incluindo a chave privada, viaja numa única imagem.

Para obter um ficheiro em vez de um desenho no terminal:

qrencode -o client1.png < /etc/wireguard/client1.conf

Se o código não for lido, as causas habituais são um tipo de letra do terminal que deforma os blocos, ou uma configuração muito longa. -t utf8 em vez de ansiutf8 produz um código mais pequeno, e reduzir o tamanho do tipo de letra do terminal ajuda mais do que qualquer outra coisa.

A parte que importa

Uma configuração de cliente WireGuard contém PrivateKey: uma chave Curve25519 de 32 bytes, escrita como 44 caracteres base64 numa única linha. O código QR contém a configuração. Portanto, o código QR é a chave privada, num formato concebido para ser lido à distância por uma câmara.

Isso muda a forma como deve ser tratado:

• Não o fotografe. Uma foto vai para o rolo da câmara e, na maioria dos telemóveis, diretamente para uma cópia de segurança na nuvem.
• Não o coloque numa mensagem de chat nem num email. Ambos são cópias armazenadas que você não controla.
• Limpe o terminal depois da leitura. clear sozinho não esvazia o histórico de deslocamento. Use reset, ou feche completamente a janela do terminal.
• Apague os ficheiros PNG imediatamente. Um client1.png esquecido numa pasta pessoal sobrevive ao motivo pelo qual foi criado.
• Não o mostre onde uma câmara o possa ver, o que num escritório partilhado inclui a janela atrás de você.

Uma chave privada por cliente é a regra que o código QR torna fácil de quebrar. Gerar uma configuração e lê-la em três telemóveis dá aos três a mesma identidade, e o servidor deixa de os conseguir distinguir, não consegue revogar um deles e encaminha mal o tráfego quando dois estão ligados ao mesmo tempo. Adicionar um peer distinto por dispositivo é explicado em adicionar um peer WireGuard.

Gerar primeiro a configuração, se ainda não tiver uma

O código QR é o último passo. Antes dele, o cliente precisa de um par de chaves e de uma entrada de peer no servidor:

wg genkey | tee client1.key | wg pubkey > client1.pub

Depois, uma configuração que referencie a chave pública do servidor, o endpoint e AllowedIPs, e um bloco [Peer] correspondente no servidor com client1.pub. Esquecer o lado do servidor é a razão mais comum para um túnel lido por QR não se ligar a nada: o telemóvel está configurado e o servidor nunca ouviu falar dele.

Se preferir não construir os ficheiros à mão, o gerador de configuração escreve os dois lados de uma vez (o [Interface] do servidor com todos os blocos [Peer], mais um ficheiro de cliente e um código QR por dispositivo), para que o telemóvel que lê o código e o servidor com que ele comunica fiquem coerentes desde o início.

O servidor precisa de um endereço IP público que o seu telemóvel consiga alcançar a partir de uma rede móvel. Uma ligação doméstica atrás de CGNAT não tem um (verifique a sua com o verificador de porta WireGuard); um pequeno VPS tem, por cerca de 5 € por mês.

Os guias completos, incluindo o lado do servidor, estão em configuração do PiVPN com WireGuard para um Raspberry Pi e em auto-hospedagem num VPS para um servidor alugado. Ambos geram configurações de cliente que pode passar diretamente ao qrencode.

Se a leitura funciona mas o túnel não

O código QR cumpriu a sua função no momento em que o túnel aparece na aplicação. Tudo o que vem depois é WireGuard normal.

Verifique se o telemóvel mostra um handshake recente. Um peer saudável refaz o handshake aproximadamente a cada 120 segundos, por isso, num túnel ativo, qualquer valor superior a cerca de dois minutos é um sintoma e não uma pausa. Se não mostrar, siga a resolução de problemas de handshake: endereço do endpoint, porta acessível a partir do exterior (51820/UDP por defeito), firewall do servidor e entrada de peer. Se o handshake funciona mas as páginas ficam bloqueadas, trata-se do MTU, um problema especialmente comum nas redes móveis.

As notas de configuração específicas de cada plataforma estão em configuração do WireGuard no Android e configuração do WireGuard no iOS.