WireGuard «Key is not the correct length or format»: causas

Arrancas a interface e és travado antes de qualquer ligação:

Key is not the correct length or format

A chave no ecrã parece estar bem. Toda a dificuldade deste erro está aí: o que está errado é normalmente um carácter que não consegues ver.

O que é exatamente uma chave válida

Uma chave WireGuard são 32 bytes de dados em bruto. Escritos em base64, 32 bytes dão exatamente 44 caracteres, e o último é sempre =, o carácter de preenchimento. Isso dá-te um teste que se aplica num segundo, a olho ou por comando:

echo -n "$KEY" | wc -c

44 sem quebra de linha, 45 se a quebra de linha ainda lá estiver. Qualquer outro valor não é uma chave, pareça o que parecer.

O mesmo vale para chaves privadas, chaves públicas e chaves pré-partilhadas, já que as três têm 32 bytes. O que leva diretamente à armadilha da última secção.

Causa 1: uma quebra de linha final invisível

A causa isolada mais comum, e vem de um comando que parece perfeitamente razoável:

PRIVATE_KEY=$(cat privatekey)

O cat devolve o ficheiro incluindo a quebra de linha final, e a substituição de comandos aqui remove-a, mas o mesmo valor escrito numa configuração com um heredoc ou uma macro de editor mantém-na muitas vezes. Escrito no wg0.conf, obténs uma chave seguida de um carácter a mais e um valor de 45 bytes onde eram exigidos 44.

Remove-a explicitamente em vez de contar com a sorte:

tr -d '\n' < privatekey

Causa 2: a chave partida em duas linhas

Copiar uma chave de uma janela de terminal estreita, de um email ou de um cliente de chat pode inserir uma quebra de linha a meio. No ficheiro de configuração, o valor termina agora ao fim de trinta e poucos caracteres, e o resto fica sozinho numa linha órfã.

Procura-a com uma verificação de comprimento por linha em vez de ler:

awk -F' = ' '/Key/ {print $1, length($2)}' /etc/wireguard/wg0.conf

Cada linha de chave deve mostrar 44. Qualquer outro valor nessa lista é o culpado, e isto funciona numa configuração com uma dúzia de peers, onde a inspeção a olho não funciona.

Causa 3: a chave veio acompanhada

Uma chave gerada e mostrada num só passo pode apanhar coisas à sua volta. Duas versões disto:

• Um prompt da shell ou o eco do comando, capturado juntamente com a saída ao copiar do histórico do terminal.
• Um espaço no início, que o base64 não tolera e que nenhum editor te vai mostrar.

Quando é uma chave nova, regenerar é mais rápido do que investigar:

wg genkey > privatekey
chmod 600 privatekey
wg pubkey < privatekey > publickey

Redirecionar para um ficheiro em vez de ler do ecrã elimina toda esta categoria de problemas, e o chmod importa porque uma chave privada legível por todos é um problema em si.

Se a configuração ainda está a ser escrita, podes dispensar o terminal para as chaves por completo. O nosso gerador de configurações WireGuard gratuito cria os pares de chaves no teu navegador (Curve25519, nada é enviado para um servidor) e escreve-os diretamente no [Interface] do servidor, nos seus blocos [Peer] e num ficheiro de cliente por dispositivo. Nenhuma chave passa por uma área de transferência, uma linha de terminal partida ou um prompt da shell pelo caminho, e cada chave que escreve tem exatamente 44 caracteres: a verificação awk acima mostra 44 em cada linha da sua saída. O gerador é gratuito até 10 dispositivos; acima disso, o WireGuard Pro (o nosso próprio produto, 9 EUR uma única vez, sem subscrição) sobe o limite para 250 e acrescenta um ZIP com cada .conf de cliente e o respetivo código QR em PNG, prático para configurar um escritório ou uma família inteira de uma só vez.

Causa 4: o tipo certo de chave no sítio errado

Esta não produz o erro, e é precisamente por isso que tem lugar aqui. Uma chave pública também tem 44 caracteres base64, por isso colocá-la no campo PrivateKey é lido na perfeição e falha em silêncio para sempre. Nenhuma mensagem, nenhuma rejeição, apenas um handshake que nunca acontece.

A verificação consiste em derivar em vez de comparar:

wg pubkey < privatekey

Se a saída for igual ao valor do teu campo PrivateKey, puseste lá uma chave pública. Uma chave privada passada pelo wg pubkey dá algo diferente dela própria; uma chave pública passada por ele dá lixo ou um erro, nunca o valor de partida.

Uma auditoria de uma linha a todas as chaves de uma configuração

Em vez de as testar uma a uma:

grep -oP '(?<= = )[A-Za-z0-9+/]{40,50}=' /etc/wireguard/wg0.conf | while read k; do
  printf '%s %s\n' "$(printf %s "$k" | wc -c)" "$k"
done

Cada linha deve começar por 44. Um número diferente de 44 é uma chave estragada, e encontraste-a sem ler um único carácter de base64.

Para teres os comandos de chaves à mão (wg genkey, wg pubkey < private.key para verificar que uma chave privada corresponde à pública que colaste, wg genpsk, wg show wg0 latest-handshakes), a nossa WireGuard Cheat Sheet gratuita reúne-os numa página A4 imprimível com as diretivas de configuração e as tabelas de MTU e portas. Paga o que quiseres, 0 USD aceite. Descarregar a cheat sheet.

Onde isto aparece a seguir

Corrigir o formato faz-te passar a leitura da configuração e entrar na classe seguinte de problemas, que é um túnel que sobe e não faz nada. Uma chave bem formada mas que não é a chave que o outro lado espera produz uma falha completamente diferente, tratada em o erro required key not available.

Há dois casos vizinhos que vale a pena distinguir deste. A chave pré-partilhada é uma terceira chave com a mesma forma de 44 caracteres mas regras simétricas, por isso é fácil pô-la no sítio errado: vê o guia da chave pré-partilhada. E a mesma chave instalada em dois dispositivos é lida sem problemas e falha de uma forma que parece aleatória, o que é outra história, contada em two devices, one key (em inglês).

Se escreves configurações à mão com frequência suficiente para cair nisto repetidamente, os modelos em modelos de configuração WireGuard eliminam a maior parte da transcrição. Se estás a montar o próprio servidor de raiz, começa num VPS KVM com o seu próprio IPv4 público, onde o wg-quick corre num kernel que controlas: um Contabo Cloud VPS (link de afiliado) custa 5.50 € por mês num prazo de 24 meses (consultado a 17 de outubro de 2026), e o Ultahost VPS Basic (link de afiliado) custa 5.52 $ por mês num prazo de 24 meses, com 1 GB de RAM e garantia de reembolso de 30 dias (consultado a 21 de outubro de 2026).