Cliente ACME Lego - WildCard SSL

Um guia detalhado para implementar um certificado SSL WildCard em estrela através do cliente ACME Lego e da validação API DNS com o alojamento web VEDOS. O procedimento destina-se a certificados do tipo example.com e *.example.com, em que a renovação deve ser automática sem introduzir manualmente os registos TXT. O guia utiliza um certificado ACME da autoridade de certificação Certum. O certificado utilizado serve apenas como exemplo – o princípio de funcionamento e o procedimento de implementação ACME são os mesmos para todas as autoridades de certificação.

O guia utiliza sintaxe verificada no Lego 5.2.2. O Lego v5 alterou alguns parâmetros em comparação com versões mais antigas, pelo que, em caso de erro como flag provided but not defined, verifique a sintaxe correta utilizando lego accounts register --help, lego run --help ou lego --help.

Conceitos básicos

• ACME – protocolo para emissão e renovação automatizadas de certificados SSL/TLS.
• Lego – um cliente ACME escrito em Go. Pode realizar validação DNS através de muitos fornecedores de DNS (lista de fornecedores de DNS suportados).
• DNS-01 – validação através do registo DNS TXT _acme-challenge. É necessária para certificados WildCard.
• EAB kid + hmac – detalhes External Account Binding (EAB) da autoridade de certificação. Ligam o Certbot a uma conta ou produto.
• VEDOS WAPI – a interface API do VEDOS através da qual o Lego cria e elimina os registos DNS TXT.
• Systemd service - um ficheiro de configuração que indica ao sistema Linux como iniciar uma aplicação e mantê-la em execução mesmo após um reinício do servidor.

Em todos os exemplos apresentados, substitua o domínio example.com pelo seu próprio domínio.

Instalação do Lego

apt update
apt install -y curl tar

cd /tmp
LEGO_URL=$(curl -s https://api.github.com/repos/go-acme/lego/releases/latest | sed -n 's/.*"browser_download_url": "\(.*linux_amd64.tar.gz\)".*/\1/p' | head -n1)
echo "$LEGO_URL"
curl -L -o lego.tar.gz "$LEGO_URL"
tar -xzf lego.tar.gz
install -m 0755 lego /usr/local/bin/lego
lego --version

Após uma instalação bem-sucedida, recomendamos remover os ficheiros temporários.

rm -f /tmp/lego /tmp/lego.tar.gz /tmp/LICENSE /tmp/CHANGELOG.md

Fornecedor de DNS API

Este guia utiliza a DNS API do registador de domínios Vedos, que oferece uma API para gerir o DNS dos domínios registados. Para o alojamento web Vedos, precisa de ativar o WAPI e também preencher os endereços IP permitidos e a palavra-passe WAPI.

Endereços IP do servidor VPS

curl -4 ifconfig.me
curl -6 ifconfig.me

No campo Endereços IP permitidos, introduza todos os endereços IP de saída do seu servidor, normalmente tanto IPv4 como IPv6. Os valores são separados por um espaço. O VEDOS permite pedidos à API apenas a partir dos endereços IP indicados.
Importante: Se permitir apenas IPv4 e algum pedido à API sair através de IPv6, a emissão do certificado pode ser bem-sucedida, mas a limpeza dos registos TXT falhará com o erro Access not allowed from this IP address.

Valores recomendados para o fornecedor de DNS VEDOS

Apache, webroot

A configuração básica do Apache é uma parte de apoio. A validação DNS ocorre através da DNS API, não através de HTTP, mas o vhost do Apache é necessário para servir o website depois de o certificado ser emitido.

cd /var/www
apt update
apt install -y apache2
systemctl enable --now apache2
a2enmod rewrite headers ssl
systemctl reload apache2

DOMAIN="example.com"
mkdir -p /var/www/$DOMAIN/public
chown -R www-data:www-data /var/www/$DOMAIN
chmod -R 755 /var/www/$DOMAIN
echo "OK $DOMAIN" > /var/www/$DOMAIN/public/index.html

cat > /etc/apache2/sites-available/$DOMAIN.conf <<EOF
<VirtualHost *:80>
    ServerName $DOMAIN
    ServerAlias *.$DOMAIN

    DocumentRoot /var/www/$DOMAIN/public
    <Directory /var/www/$DOMAIN/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog \${APACHE_LOG_DIR}/${DOMAIN}_error.log
    CustomLog \${APACHE_LOG_DIR}/${DOMAIN}_access.log combined
</VirtualHost>
EOF

a2ensite $DOMAIN.conf
apache2ctl configtest
systemctl reload apache2
curl -I http://$DOMAIN

Ficheiros de configuração do Lego

A abordagem recomendada para o Lego v5 é armazenar as definições num ficheiro de configuração. O systemd service não precisa então de conter um comando longo com domínios, o fornecedor de DNS e hooks.

Ficheiro de configuração .env

O ficheiro .env é um ficheiro de configuração de texto no qual são armazenadas variáveis de ambiente, por exemplo credenciais de acesso, chaves de API ou definições da aplicação. Para maior clareza, pode nomear o ficheiro provider-domain.env. O ficheiro vedos-example.com.env conterá as credenciais de início de sessão do VEDOS WAPI, pelo que o armazenamos em /etc/lego e lhe atribuímos permissões restritas.

DOMAIN="example.com"

mkdir -p /etc/lego/$DOMAIN
nano /etc/lego/vedos-$DOMAIN.env

Na configuração abaixo, substitua WEDOS_LOGIN pelo seu login do VEDOS e WEDOS_WAPI_PASSWORD pela palavra-passe gerada no VEDOS WAPI. Pode deixar os valores de timeout e interval como estão.

WEDOS_USERNAME='WEDOS_LOGIN'
WEDOS_WAPI_PASSWORD='WEDOS_WAPI_PASSWORD'
WEDOS_PROPAGATION_TIMEOUT=3600
WEDOS_POLLING_INTERVAL=30
WEDOS_TTL=300

Ficheiro de configuração lego.yml

O ficheiro .yml é um ficheiro de configuração de texto em formato YAML, utilizado para uma notação clara de definições, parâmetros e dados estruturados. Antes de guardar a configuração YAML, substitua example.com pelo seu próprio domínio, *.example.com pelo nome wildcard, vas@email.cz pelo seu e-mail de contacto e os valores KID / HMAC pelos detalhes da sua encomenda de certificado ACME. Nomes como certum-example ou example-com-wildcard são etiquetas internas; pode deixá-los, mas com vários domínios é aconselhável renomeá-los de acordo com o domínio.

mkdir /etc/lego/$DOMAIN
nano /etc/lego/$DOMAIN/lego.yml

storage: /etc/lego/example.com

accounts:
  certum-example:
    server: certum
    email: vas@email.cz
    acceptsTermsOfService: true
    eab:
      kid: KID
      hmacKey: HMAC

servers:
  certum:
    url: https://acme.certum.pl/directory

challenges:
  vedos-dns:
    dns:
      provider: vedos
      envFile: /etc/lego/vedos-example-com.env
      resolvers:
        - 1.1.1.1:53

certificates:
  example-com-wildcard:
    account: certum-example
    challenge: vedos-dns
    domains:
      - example.com
      - "*.example.com"
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2

Emissão do certificado

Antes de executar, substitua example.com no caminho pelo domínio que utilizou ao criar o diretório. A primeira execução cria a conta ACME, define os registos DNS TXT através da DNS API, realiza a validação DNS-01 e guarda o certificado.

Durante a espera, o Lego pode imprimir:

Isto significa que o Lego verifica o DNS a cada 30 segundos e aguarda no máximo 1 hora. Após o sucesso, verifique os ficheiros:

O diretório certificates/ contém o .crt emitido, o .key, os certificados intermédios da autoridade de certificação e os metadados.

Procedimento CLI alternativo para o Lego v5

lego accounts register \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --accept-tos \
  --eab \
  --eab.kid 'KID' \
  --eab.hmac 'HMAC'

set -a
. /etc/lego/vedos-example.com.env
set +a

lego run \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --dns vedos \
  --dns.resolvers 1.1.1.1:53 \
  --domains example.com \
  --domains '*.example.com'

Implementar o certificado no Apache

Antes de criar o vhost HTTPS, substitua example.com pelo seu próprio domínio no nome do ficheiro, nos valores ServerName e ServerAlias, nos caminhos do webroot e nos caminhos do certificado. Estes caminhos têm de corresponder ao domínio utilizado na configuração do Lego.

cat > /etc/apache2/sites-available/example.com-le-ssl.conf <<'EOF'
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName example.com
    ServerAlias *.example.com

    DocumentRoot /var/www/example.com/public
    <Directory /var/www/example.com/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile /etc/lego/example.com/certificates/example.com.crt
    SSLCertificateKeyFile /etc/lego/example.com/certificates/example.com.key

    ErrorLog ${APACHE_LOG_DIR}/example.com_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/example.com_ssl_access.log combined
</VirtualHost>
</IfModule>
EOF

a2ensite example.com-le-ssl.conf
apache2ctl configtest
systemctl reload apache2

curl -I https://example.com
curl -I https://test.example.com

Renovação automática

O Lego pode renovar o certificado, mas após a instalação não cria por si próprio um systemd timer. A execução regular é configurada através de um serviço e timer personalizados. Antes de inserir, substitua example-com no nome do service/timer pelo seu próprio nome seguro sem pontos, por exemplo mojedomena-cz, e substitua example.com no caminho da configuração pelo seu próprio domínio.

cat > /etc/systemd/system/lego-example-com-renew.service <<'EOF'
[Unit]
Description=Renew Certum WildCard SSL for example.com using Lego and VEDOS DNS
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/lego --config /etc/lego/example.com/lego.yml
EOF

cat > /etc/systemd/system/lego-example-com-renew.timer <<'EOF'
[Unit]
Description=Daily Lego renewal check for example.com

[Timer]
OnCalendar=*-*-* 03:20:00
RandomizedDelaySec=1800
Persistent=true

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now lego-example-com-renew.timer
systemctl list-timers | grep lego

Teste seguro do serviço:

systemctl start lego-example-com-renew.service
journalctl -u lego-example-com-renew.service -n 100 --no-pager

Se o certificado não estiver perto de expirar, o Lego pode indicar que a renovação não é necessária. Este é o comportamento correto.

Erros comuns

Parâmetro desconhecido no Lego

No Lego v5 os parâmetros EAB são --eab.kid e --eab.hmac. Os parâmetros pertencem sempre a um subcomando específico.

lego accounts register --help
lego accounts list --help
lego run --help

A limpeza dos registos TXT falha num IP não permitido

Adicione também o endereço IPv6 do servidor aos endereços IP permitidos no VEDOS WAPI. O certificado pode ser emitido corretamente, mas os registos TXT permanecerão no DNS após a validação.

Lista de verificação

dig TXT _acme-challenge.example.com +short
lego --config /etc/lego/example.com/lego.yml
systemctl status lego-example-com-renew.timer
apache2ctl configtest
curl -I https://example.com

Para onde seguir?

• Protocolo ACME
• Cliente ACME Lego
• Cliente ACME Certbot
• Certificado SSL - Tudo o que precisa de saber