TL;DR — Resumo Rápido

Certificados SSL wildcard com Certbot e DNS-01. Cobre plugins DNS, configuração Cloudflare, renovação automática, limites de taxa e resolução de problemas.

Certificados SSL wildcard permitem que um único certificado proteja cada subdomínio sob seu domínio — *.example.com cobre api.example.com, app.example.com, staging.example.com e qualquer outro subdomínio que você criar. Em vez de emitir certificados individuais para cada serviço, você obtém um único e o implanta em toda a sua infraestrutura. O Let’s Encrypt fornece certificados wildcard gratuitamente, mas exige o desafio DNS-01 para validação — um requisito que desafios baseados em HTTP não conseguem satisfazer.

Este guia cobre todos os aspectos de obtenção e manutenção de certificados wildcard com Certbot: desde entender por que DNS-01 é obrigatório, passando pela validação manual, plugins DNS automatizados, configuração detalhada do Cloudflare, renovação automática com systemd, SANs multi-domínio, limites de taxa e resolução de problemas.

Pré-requisitos

Antes de começar, tenha o seguinte pronto:

  • Ubuntu 22.04 LTS ou 24.04 LTS (ou qualquer Linux baseado em Debian) com acesso sudo.
  • Um domínio registrado com DNS gerenciado por um provedor compatível (Cloudflare, AWS Route 53, DigitalOcean, Google Cloud DNS, ou acesso manual à sua zona).
  • Certbot instalado — ou você o instalará abaixo.
  • Um token de API para seu provedor DNS com permissão para criar e excluir registros DNS.
  • A porta 80 NÃO precisa estar aberta para desafios DNS-01 wildcard (ao contrário dos desafios HTTP-01).

Por Que Certificados Wildcard?

Um certificado padrão cobre um ou mais nomes de host específicos: example.com, www.example.com, api.example.com. Se você adicionar um novo subdomínio — metrics.example.com — deve ou adicionar à lista SAN e reemitir o certificado, ou obter um novo.

Um certificado wildcard (*.example.com) elimina esse problema:

  • Um certificado, subdomínios ilimitados — Qualquer nome de host correspondendo a *.example.com em um único nível fica coberto automaticamente.
  • Gerenciamento simplificado de certificados — Um processo de renovação, uma chave privada, um hook de implantação.
  • Funciona com serviços internos — Subdomínios sem servidores web públicos (APIs internas, interfaces de gerenciamento) são cobertos sem precisar de acesso HTTP.
  • Eficiência de custos — O Let’s Encrypt os emite gratuitamente. Certificados wildcard comerciais de CAs tradicionais custam tipicamente $100–$300/ano.

A única limitação: wildcards cobrem exatamente um nível de subdomínio. *.example.com cobre api.example.com mas não v1.api.example.com. Para subdomínios aninhados, adicione um segundo wildcard: *.api.example.com.

Entendendo o ACME e o Desafio DNS-01

O Let’s Encrypt usa o protocolo ACME (RFC 8555) para automatizar a emissão de certificados. Você deve provar o controle do seu domínio completando um desafio.

Por Que HTTP-01 Não Pode Validar Wildcards

O desafio HTTP-01 coloca um arquivo de token em http://example.com/.well-known/acme-challenge/<TOKEN>. Isso funciona para nomes de host específicos com um servidor web acessível. Mas *.example.com representa um conjunto infinito de nomes de host — a maioria dos quais pode não ter nenhum servidor HTTP. O servidor ACME não tem como sondar cada subdomínio possível, então HTTP-01 é explicitamente proibido para certificados wildcard pela especificação ACME.

Como Funciona o DNS-01

O DNS-01 valida o controle do domínio provando que você pode escrever na zona DNS:

  1. O Certbot contata o servidor ACME e solicita autorização para *.example.com.
  2. O servidor ACME emite um token e instrui a publicar um registro TXT em _acme-challenge.example.com com um valor específico.
  3. O Certbot (ou seu plugin DNS) cria o registro TXT via API do seu provedor DNS.
  4. O servidor ACME consulta resolvedores DNS para verificar que o registro TXT existe.
  5. Uma vez validado, o certificado é assinado e retornado.
  6. O Certbot (ou seu plugin) exclui o registro TXT.

O DNS-01 funciona mesmo quando nenhum servidor web existe, quando a porta 80 está bloqueada por firewall e quando o subdomínio não tem registro A.

Instalando o Certbot

O pacote snap é o método de instalação oficialmente mantido e garante que você sempre tenha a versão mais recente.

# Remover qualquer certbot empacotado pelo sistema para evitar conflitos
sudo apt remove certbot -y 2>/dev/null || true

# Instalar o Certbot via snap
sudo snap install --classic certbot

# Criar symlink para que certbot esteja no PATH
sudo ln -s /snap/bin/certbot /usr/bin/certbot

# Verificar
certbot --version

Se sua distribuição não suporta snaps, use pip em um ambiente virtual:

sudo apt install python3-pip python3-venv -y
python3 -m venv /opt/certbot
/opt/certbot/bin/pip install certbot
sudo ln -s /opt/certbot/bin/certbot /usr/local/bin/certbot

Validação DNS Manual

Para um certificado único ou ao testar, a validação DNS manual não requer tokens de API. Você cria o registro TXT você mesmo.

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

O Certbot exibirá algo como:

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

Once deployed, press Enter to continue...

Faça login no seu provedor DNS, adicione o registro TXT e verifique a propagação antes de pressionar Enter:

dig +short TXT _acme-challenge.example.com
# Deve retornar: "gfj9Xq8R3mT2nKp1vLwY5sAqZdBcF7eH"

# Ou consulte um resolvedor público
dig @8.8.8.8 +short TXT _acme-challenge.example.com

Nota: A validação manual não suporta renovação automática. O Certbot solicitará que você recrie o registro TXT manualmente a cada 60–89 dias. Para uso em produção, configure um plugin DNS automatizado.

Plugins DNS Automatizados

Os plugins DNS eliminam etapas manuais chamando a API do seu provedor DNS para criar e excluir o registro TXT _acme-challenge automaticamente durante a emissão inicial e cada renovação subsequente.

PluginProvedorComando de Instalação
certbot-dns-cloudflareCloudflaresudo snap install certbot-dns-cloudflare
certbot-dns-route53AWS Route 53sudo snap install certbot-dns-route53
certbot-dns-googleGoogle Cloud DNSsudo snap install certbot-dns-google
certbot-dns-digitaloceanDigitalOceansudo snap install certbot-dns-digitalocean
certbot-dns-linodeLinode/Akamaisudo snap install certbot-dns-linode
certbot-dns-hetznerHetzner DNSpip install certbot-dns-hetzner

Configuração Detalhada do Plugin Cloudflare

Passo 1: Criar um Token de API do Cloudflare

Faça login no painel do Cloudflare → Meu Perfil → Tokens de API → Criar Token.

Use o modelo “Editar DNS de zona” e configure:

  • Permissões: Zona → DNS → Editar
  • Recursos de Zona: Incluir → Zona específica → selecione seu domínio
  • Filtragem de Endereço IP: Opcionalmente restrinja ao IP do seu servidor

Passo 2: Criar o Arquivo de Credenciais

sudo mkdir -p /etc/letsencrypt/cloudflare

sudo tee /etc/letsencrypt/cloudflare/credentials.ini > /dev/null <<'EOF'
dns_cloudflare_api_token = SEU_TOKEN_DE_API_CLOUDFLARE_AQUI
EOF

sudo chmod 600 /etc/letsencrypt/cloudflare/credentials.ini
sudo chown root:root /etc/letsencrypt/cloudflare/credentials.ini

Nota de segurança: Nunca use o método legado de dns_cloudflare_email + dns_cloudflare_api_key (Chave de API Global). O token de API com escopo limitado reduz o risco se o arquivo de credenciais for exposto.

Passo 3: Instalar o Plugin

sudo snap install certbot-dns-cloudflare

sudo snap set certbot trust-plugin-with-root=ok
sudo snap connect certbot:plugin certbot-dns-cloudflare

Passo 4: Obter o Certificado

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare/credentials.ini \
  --dns-cloudflare-propagation-seconds 60 \
  -d example.com \
  -d "*.example.com" \
  --email admin@example.com \
  --agree-tos \
  --non-interactive

Passo 5: Verificar o Certificado

sudo certbot certificates

Localização dos Arquivos do Certificado

Após a emissão, os arquivos do certificado são armazenados em /etc/letsencrypt/. O diretório live/ contém links simbólicos para as versões mais recentes:

ArquivoCaminhoPropósito
Cadeia completa/etc/letsencrypt/live/example.com/fullchain.pemCertificado + CA intermediária (use no Nginx/Apache)
Chave privada/etc/letsencrypt/live/example.com/privkey.pemChave privada — proteger com cuidado
Apenas cadeia/etc/letsencrypt/live/example.com/chain.pemApenas cadeia de CA intermediária
Apenas certificado/etc/letsencrypt/live/example.com/cert.pemCertificado do domínio sem cadeia

Configure o Nginx para usar o certificado wildcard:

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name *.example.com example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
}

Renovação Automática com systemd

O Certbot instala automaticamente um timer systemd ao ser instalado via snap ou apt.

Verificar o Timer

sudo systemctl status certbot.timer
sudo systemctl list-timers certbot.timer

Adicionar Hook de Implantação para Nginx

sudo bash -c 'cat >> /etc/letsencrypt/renewal/example.com.conf <<EOF

[renewalparams]
deploy_hook = systemctl reload nginx
EOF'

Testar a Renovação

sudo certbot renew --dry-run

Wildcards Multi-Domínio

Um único certificado pode incluir múltiplos SANs wildcard:

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare/credentials.ini \
  -d example.com \
  -d "*.example.com" \
  -d staging.example.net \
  -d "*.staging.example.net"

*.example.com NÃO cobre *.api.example.com. Cada nível requer uma entrada wildcard separada.

Limites de Taxa

LimiteValorJanela
Certificados por domínio registrado507 dias
Certificados duplicados57 dias
Validações com falha51 hora
Novos pedidos3003 horas

Testes com o Ambiente de Staging

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare/credentials.ini \
  --staging \
  -d example.com \
  -d "*.example.com"

Uma vez que sua configuração funcione corretamente, exclua o certificado de staging e obtenha um de produção:

sudo certbot delete --cert-name example.com
sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare/credentials.ini \
  -d example.com \
  -d "*.example.com"

Certbot vs Alternativas

FerramentaWildcardDNS AutoLet’s EncryptOutras CAsNotas
CertbotSim (plugins)Por pluginSimLimitadoCliente oficial EFF, ecossistema mais amplo
acme.shSimIntegrado (150+)SimSimApenas Bash, sem dependências, portátil
CaddySim (nativo)AutomáticoSimSimSem configuração; módulo DNS deve ser compilado
TraefikSim (nativo)AutomáticoSimLimitadoIdeal para ambientes de contêineres
CA ComercialSimNão (manual)NãoSim$100–$300/ano, opções OV/EV

Resolução de Problemas Comuns

Registro CAA Bloqueando a Emissão

Sintoma: Error: CAA record for example.com prevents issuance

dig +short CAA example.com

Se não existir uma entrada para o Let’s Encrypt, adicione:

example.com.  CAA 0 issue "letsencrypt.org"
example.com.  CAA 0 issuewild "letsencrypt.org"

A tag issuewild é especificamente necessária para autorização de certificados wildcard.

Atrasos na Propagação DNS

Sintoma: DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com

Aumente o tempo de espera de propagação:

--dns-cloudflare-propagation-seconds 120

Verifique que o registro TXT está visível a partir de um resolvedor público:

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

Limite de Taxa Atingido

Sintoma: Error creating new order :: too many certificates already issued

Você emitiu 5 certificados duplicados para o mesmo conjunto de domínios em 7 dias. Aguarde a expiração da janela de limite, adicione ou remova um domínio da lista SAN, ou use --staging para mais testes.

Erro de Permissão no Arquivo de Credenciais

Sintoma: Unsafe permissions on credentials configuration file

sudo chmod 600 /etc/letsencrypt/cloudflare/credentials.ini
sudo chown root:root /etc/letsencrypt/cloudflare/credentials.ini

Resumo

Os certificados SSL wildcard do Let’s Encrypt oferecem a flexibilidade de proteger subdomínios ilimitados com um único certificado gratuito. Os pontos-chave a lembrar:

  • Wildcards exigem o desafio DNS-01 — HTTP-01 não pode validar *.example.com.
  • A validação DNS manual funciona para emissão única mas não suporta renovação automática.
  • Os plugins DNS (certbot-dns-cloudflare, certbot-dns-route53, etc.) permitem renovação totalmente automatizada.
  • O token de API do Cloudflare deve ter permissão Zona:DNS:Editar; o arquivo de credenciais deve ser chmod 600.
  • Os arquivos do certificado ficam em /etc/letsencrypt/live/ — sempre use fullchain.pem no seu servidor web.
  • Os hooks de implantação recarregam Nginx, HAProxy ou outros serviços após cada renovação.
  • Os limites de taxa são rigorosos — use --staging para testes e --dry-run para validar a renovação.
  • Os registros CAA devem incluir letsencrypt.org com issuewild para autorização wildcard.

Artigos Relacionados