Como emitir certificado wildcard com Certbot

Por que um certificado wildcard exige DNS-01

Um certificado wildcard cobre todos os subdomínios de primeiro nível de um domínio: *.example.com abrange app.example.com, blog.example.com e qualquer outro nome com apenas um nível de label. O Let's Encrypt emite certificados wildcard apenas através do desafio DNS-01, portanto o Certbot deve provar o controle do DNS do domínio publicando um registro TXT em _acme-challenge.example.com. O desafio HTTP-01 não é válido, pois servir um arquivo de token prova apenas o controle de um hostname específico, o mesmo hostname de onde o servidor de validação baixou o arquivo. Um wildcard é uma afirmação sobre todos os nomes possíveis sob o domínio, e o único registro público que representa todo o namespace é o próprio DNS.

Este requisito define todas as outras etapas desta página. Para passar no DNS-01, você deve ser capaz de criar registros TXT na zona do domínio, seja manualmente ou através da API (interface de programação de aplicações) do seu provedor de DNS. O método manual funciona uma vez e falha na renovação, pelo motivo detalhado abaixo. O método via API, utilizando um plugin de DNS do Certbot, renova o certificado de forma automática; este é o método recomendado.

Este é o capítulo sobre wildcard dos nossos guias de Certbot. Certificados comuns de um único hostname, a configuração do servidor web e as regras da porta 80 são abordados em Certbot com nginx no Ubuntu 24.04 e Certbot com Apache no Ubuntu 24.04.

Como funciona o registro TXT _acme-challenge

Quando o Certbot solicita *.example.com, o Let's Encrypt responde com um token aleatório. O Certbot combina esse token com a chave da sua conta ACME (automatic certificate management environment), gera um hash do resultado usando SHA-256 e produz um valor de texto curto. Esse valor deve aparecer como um registro TXT em _acme-challenge.example.com. O Let's Encrypt então consulta os name servers autoritativos do seu domínio a partir de sua própria infraestrutura. Se o registro lido for igual ao valor esperado, você provou que controla a zona; o controle da zona é aceito como controle de todos os nomes sob ela.

Dois detalhes causam a maioria das falhas:

• Solicitar example.com e *.example.com no mesmo certificado significa dois desafios separados, e ambos os registros TXT residem no mesmo nome, _acme-challenge.example.com. Ambos devem existir simultaneamente. Adicionar o segundo registro é o procedimento correto; substituir o primeiro pelo segundo fará a falha do primeiro desafio.
• A validação consulta seus servidores autoritativos, mas painéis de controle de provedores podem levar um minuto ou mais para propagar um novo registro para eles. Verifique externamente antes de iniciar a validação:

dig +short TXT _acme-challenge.example.com @1.1.1.1

Quando o comando imprimir o valor solicitado pelo Certbot, a validação pode ser bem-sucedida. Quando não imprimir nada, aguarde e execute novamente.

Veja funcionando uma vez: modo manual

O modo manual exige que você edite o DNS manualmente. Esta é a melhor forma de entender o mecanismo antes de automatizá-lo:

sudo certbot certonly --manual --preferred-challenges dns -d example.com -d '*.example.com'

As aspas ao redor do wildcard impedem que o shell trate * como um padrão de nome de arquivo. O Certbot pausa e exibe as instruções:

Please deploy a DNS TXT record under the name:
_acme-challenge.example.com.
with the following value:
Jx9mQ2wLr8vTn5cKp0aYdG3hB7fZs4eN1oiRuXqMk6E

Crie o registro TXT no painel do seu provedor de DNS, confirme se ele está visível com o comando dig acima e só então pressione Enter. Como esta execução solicita o domínio raiz e o wildcard, o Certbot fará duas solicitações; mantenha ambos os registros ativos até que a emissão termine. O sucesso é indicado pelas linhas habituais:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem

Por que o modo manual não consegue se renovar sozinho

Cada renovação exige um novo desafio com um novo token, portanto o valor TXT muda todas as vezes. O registro que você colou hoje será inútil em 60 dias. O timer de renovação executa o Certbot sem supervisão duas vezes por dia, e não há ninguém no teclado para colar o novo valor, então um certificado emitido manualmente falha na renovação com este erro exato:

Failed to renew certificate example.com with error: The manual plugin is not
working; there may be problems with your existing configuration.
The error was: PluginError('An authentication script must be provided with
--manual-auth-hook when using the manual plugin non-interactively.')

Você pode atender a esse requisito escrevendo scripts --manual-auth-hook que chamam a API do seu provedor de DNS, mas, nesse caso, você estará reconstruindo um plugin de DNS manualmente. Use o modo manual para aprender o fluxo ou para um caso isolado em um domínio cujo DNS você ainda não consegue automatizar, e defina um lembrete bem antes do dia 90, pois o Let's Encrypt não envia mais e-mails de expiração. Para todo o resto, use um plugin.

O caminho do plugin: certbot-dns-cloudflare no Ubuntu 24.04

Um plugin de DNS utiliza uma credencial de API do seu provedor de DNS e realiza todo o processo de criação de registros TXT automaticamente, tanto na emissão quanto em cada renovação. O Cloudflare é o exemplo utilizado aqui por ser o plugin de provedor mais comum e por estar disponível nos pacotes do Ubuntu.

Nossos guias de Certbot recomendam o uso de pacotes apt no Ubuntu 24.04, e essa recomendação se aplica ao Cloudflare:

sudo apt update
sudo apt install certbot python3-certbot-dns-cloudflare

Uma observação sobre versões. O repositório do 24.04 disponibiliza este plugin na versão 2.0.0 junto ao Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare mostra a sua versão. Essa diferença não causa problemas e tokens de API com escopo funcionam, pois a biblioteca python3-cloudflare subjacente no 24.04 é a 2.11.1, superior à 2.3.1 exigida pelo plugin para suporte a tokens. Em versões mais antigas do Ubuntu, essa biblioteca era incompatível com tokens, o que gerava os avisos encontrados online sobre o plugin apt forçar o uso da Global API Key. No 24.04, esses avisos não se aplicam.

No dashboard do Cloudflare, crie um token de API com escopo, não a Global API Key: My Profile, depois API Tokens, depois Create Token, com a permissão única Zone / DNS / Edit, limitada à zona específica para a qual você está emitindo o certificado. Salve-o em um arquivo que apenas o root possa ler:

sudo mkdir -p /root/.secrets
sudo tee /root/.secrets/cloudflare.ini > /dev/null <<'EOF'
dns_cloudflare_api_token = paste_your_scoped_token_here
EOF
sudo chmod 600 /root/.secrets/cloudflare.ini

O Certbot verifica as permissões e avisa sobre Unsafe permissions on credentials configuration file se o arquivo estiver legível por outros usuários. Agora execute a emissão:

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
  -d example.com -d '*.example.com'

O plugin cria os registros TXT via API, aguarda um curto período de propagação, executa a validação e depois deleta os registros. Se os name servers da sua zona demorarem para propagar as alterações, aumente o tempo de espera com --dns-cloudflare-propagation-seconds 60. O certificado é salvo em /etc/letsencrypt/live/example.com/, e você deve configurar o nginx ou Apache para fullchain.pem e privkey.pem exatamente como os guias básicos indicam, incluindo o deploy hook.

Se o plugin do seu provedor não estiver no apt

O repositório 24.04 contém pacotes de plugins apenas para alguns provedores, incluindo Cloudflare, Route 53, DigitalOcean e a interface genérica RFC 2136. Execute apt search certbot-dns para ver a lista. Se o seu provedor não estiver na lista, a nossa recomendação de priorizar o apt não se aplica: instale o Certbot e o plugin via snap, e remova o Certbot do apt primeiro para evitar conflitos de timers de renovação no /etc/letsencrypt:

sudo apt remove certbot python3-certbot-dns-cloudflare
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-dns-yourprovider

Um plugin snap conecta-se apenas ao Certbot via snap; ele não estende a versão do apt, por isso as duas instalações não podem coexistir. Se o seu host de DNS não oferecer uma API, suas opções reais são migrar o DNS do domínio para um provedor que possua uma, ou rodar seu próprio servidor de nomes e apontar o plugin rfc2136 para ele.

Renovação: teste agora, não em 60 dias

O Certbot registra como cada certificado foi emitido em /etc/letsencrypt/renewal/example.com.conf, incluindo authenticator = dns-cloudflare e o caminho das credenciais, permitindo que o timer padrão de duas vezes ao dia realize a renovação sem intervenção manual. Teste todo o processo usando o ambiente de staging:

sudo certbot renew --dry-run

O sucesso indica que as credenciais funcionam e a validação é concluída de ponta a ponta; a renovação real em 60 dias seguirá o mesmo caminho. Duas ações de acompanhamento são recomendadas hoje. Primeiro, um certificado renovado no disco não surte efeito até que o servidor web o recarregue; portanto, configure o deploy hook descrito nos guias de nginx e Apache. Segundo, trate o arquivo de credenciais com segurança: qualquer usuário com permissão de leitura pode editar sua zona DNS, o que é suficiente para redirecionar seu e-mail ou passar desafios DNS-01 próprios. Mantenha o arquivo com mode 600 em /root, limite o token a apenas uma zona e faça o rotate se suspeitar de vazamento.

Quando você não precisa de um wildcard

Um wildcard é a ferramenta correta para muitos subdomínios ou para subdomínios imprevisíveis. Ele não deve ser o padrão para outros casos.

• Um único subdomínio, ou um pequeno grupo de subdomínios conhecidos: um certificado SAN (subject alternative name) comum é mais simples. O certbot --nginx -d example.com -d www.example.com -d app.example.com suporta até 100 nomes via HTTP-01, e nenhuma credencial de API de DNS precisa ficar no servidor.
• Um wildcard corresponde a exatamente um label. O *.example.com não cobre o example.com, por isso os comandos acima solicitam ambos, e ele também não cobre o a.b.example.com; para isso seria necessário o *.b.example.com.
• Uma única chave privada protege cada subdomínio. Se a máquina que a armazena for comprometida, todos os nomes cobertos pelo wildcard são afetados simultaneamente.
• Se o Traefik realiza o TLS (transport layer security) para seus containers, você não precisa do Certbot: O Traefik solicita certificados wildcard via DNS-01, utilizando o mesmo tipo de token de provedor.

Onde o wildcard é realmente útil: subdomínios por cliente ou por app criados mais rápido do que o tempo para reemitir certificados, e hosts internos sem porta 80 pública, como serviços acessíveis apenas via uma VPN WireGuard. O DNS-01 nunca se conecta ao host que está sendo certificado, portanto, mesmo uma máquina totalmente privada pode possuir um certificado de confiança pública.

FAQ

O Certbot pode emitir um certificado wildcard com HTTP-01?

Não. O HTTP-01 comprova o controle de um único hostname, pois o servidor de validação busca um arquivo de token exatamente nesse nome. Um wildcard cobre todos os nomes sob o domínio, portanto o Let's Encrypt exige o desafio DNS-01 para isso; os autenticadores --nginx, --apache, --webroot e --standalone são todos baseados em HTTP. O único caminho é um registro TXT em _acme-challenge.example.com, inserido manualmente ou por um plugin de DNS.

Um certificado wildcard cobre o domínio raiz?

Não. O wildcard corresponde a exatamente um label, portanto *.example.com cobre www.example.com, mas não o domínio puro example.com, nem o a.b.example.com. Solicite ambos os nomes em um único certificado usando -d example.com -d '*.example.com'. Isso cria dois desafios, e ambos os registros TXT ficam no mesmo nome _acme-challenge.example.com, então adicione o segundo registro sem deletar o primeiro.

Por que meu certificado wildcard não renova automaticamente?

Porque ele foi emitido com --manual. Cada renovação exige um novo valor TXT, e o timer automático não consegue inseri-lo, então a renovação falha com o erro An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Reemita o certificado com um plugin de DNS como o certbot-dns-cloudflare, ou utilize scripts --manual-auth-hook e --manual-cleanup-hook que editem o registro via API do seu provedor.

Quanto tempo o registro TXT _acme-challenge leva para aparecer?

Depende do seu provedor de DNS: de alguns segundos a vários minutos. A validação consulta os servidores autoritativos da sua zona, então verifique com dig +short TXT _acme-challenge.example.com @1.1.1.1 e aguarde o valor esperado antes de continuar uma execução manual. Com um plugin, aumente o tempo de espera interno através da opção de propagação do plugin, como --dns-cloudflare-propagation-seconds 60, caso a validação informe que o registro não foi encontrado.

Um certificado wildcard é menos seguro que um certificado normal?

A criptografia é idêntica. As diferenças são operacionais: uma única chave privada cobre todos os subdomínios, então um comprometimento tem maior alcance, e a credencial da API de DNS necessária para a automação é um segredo sensível armazenado no servidor. Se você utiliza apenas alguns subdomínios conhecidos, um certificado SAN evita ambos os problemas, que é exatamente quando este guia recomenda não usar wildcard.