Client ACME Lego - WildCard SSL

Una guida dettagliata per il deployment di un certificato SSL WildCard tramite il client ACME Lego e la validazione API DNS con l'hosting web VEDOS. La procedura è destinata a certificati del tipo example.com e *.example.com, dove il rinnovo deve essere automatico senza inserire manualmente i record TXT. La guida utilizza un certificato ACME dell'autorità di certificazione Certum. Il certificato utilizzato funge solo da esempio – il principio di funzionamento e la procedura di deployment ACME sono gli stessi per tutte le autorità di certificazione.

La guida utilizza una sintassi verificata su Lego 5.2.2. Lego v5 ha modificato alcuni parametri rispetto alle versioni precedenti, quindi in caso di errore come flag provided but not defined verifica la sintassi corretta utilizzando lego accounts register --help, lego run --help o lego --help.

Concetti di base

• ACME – protocollo per l'emissione e il rinnovo automatizzati dei certificati SSL/TLS.
• Lego – un client ACME scritto in Go. Può eseguire la validazione DNS attraverso numerosi provider DNS (elenco dei provider DNS supportati).
• DNS-01 – validazione tramite il record DNS TXT _acme-challenge. È necessaria per i certificati WildCard.
• EAB kid + hmac – dettagli External Account Binding (EAB) dell'autorità di certificazione. Collegano Certbot a un account o a un prodotto.
• VEDOS WAPI – l'interfaccia API di VEDOS attraverso la quale Lego crea ed elimina i record DNS TXT.
• Systemd service - un file di configurazione che indica al sistema Linux come avviare un'applicazione e mantenerla in esecuzione anche dopo un riavvio del server.

In tutti gli esempi mostrati, sostituisci il dominio example.com con il tuo dominio.

Installazione di 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

Dopo un'installazione riuscita, consigliamo di rimuovere i file temporanei.

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

Provider DNS API

Questa guida utilizza la DNS API del registrar di domini Vedos, che offre un'API per gestire il DNS dei domini registrati. Per l'hosting web Vedos, devi attivare WAPI e inoltre inserire gli indirizzi IP consentiti e la password WAPI.

Indirizzi IP del server VPS

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

Nel campo Indirizzi IP consentiti, inserisci tutti gli indirizzi IP in uscita del tuo server, tipicamente sia IPv4 sia IPv6. I valori sono separati da uno spazio. VEDOS consente le richieste API solo dagli indirizzi IP elencati.
Importante: Se consenti solo IPv4 e qualche richiesta API esce tramite IPv6, l'emissione del certificato può riuscire, ma la pulizia dei record TXT fallirà con l'errore Access not allowed from this IP address.

Valori consigliati per il provider DNS VEDOS

Apache, webroot

La configurazione di base di Apache è una parte di supporto. La validazione DNS avviene tramite la DNS API, non tramite HTTP, ma il vhost Apache è necessario per servire il sito web dopo l'emissione del certificato.

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

File di configurazione di Lego

L'approccio consigliato per Lego v5 è memorizzare le impostazioni in un file di configurazione. Il systemd service non deve quindi contenere un lungo comando con domini, provider DNS e hook.

File di configurazione .env

Il file .env è un file di configurazione di testo in cui vengono memorizzate le variabili d'ambiente, ad esempio credenziali di accesso, chiavi API o impostazioni dell'applicazione. Per chiarezza, puoi nominare il file provider-domain.env. Il file vedos-example.com.env conterrà le credenziali di accesso VEDOS WAPI, quindi lo memorizziamo in /etc/lego e vi impostiamo permessi limitati.

DOMAIN="example.com"

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

Nella configurazione qui sotto, sostituisci WEDOS_LOGIN con il tuo login VEDOS e WEDOS_WAPI_PASSWORD con la password generata in VEDOS WAPI. Puoi lasciare i valori di timeout e interval così come sono.

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

File di configurazione lego.yml

Il file .yml è un file di configurazione di testo in formato YAML, utilizzato per una notazione chiara di impostazioni, parametri e dati strutturati. Prima di salvare la configurazione YAML, sostituisci example.com con il tuo dominio, *.example.com con il nome wildcard, vas@email.cz con la tua e-mail di contatto e i valori KID / HMAC con i dettagli del tuo ordine di certificato ACME. Nomi come certum-example o example-com-wildcard sono etichette interne; puoi lasciarli, ma con più domini è consigliabile rinominarli in base al dominio.

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

Emissione del certificato

Prima dell'esecuzione, sostituisci example.com nel percorso con il dominio utilizzato durante la creazione della directory. La prima esecuzione crea l'account ACME, imposta i record DNS TXT tramite la DNS API, esegue la validazione DNS-01 e salva il certificato.

Durante l'attesa, Lego può stampare:

Questo significa che Lego controlla il DNS ogni 30 secondi e attende al massimo 1 ora. Dopo il successo, verifica i file:

La directory certificates/ contiene il .crt emesso, la .key, i certificati intermedi dell'autorità di certificazione e i metadati.

Procedura CLI alternativa per 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'

Deployment del certificato su Apache

Prima di creare il vhost HTTPS, sostituisci example.com con il tuo dominio nel nome del file, nei valori ServerName e ServerAlias, nei percorsi del webroot e nei percorsi del certificato. Questi percorsi devono corrispondere al dominio utilizzato nella configurazione di 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

Rinnovo automatico

Lego può rinnovare il certificato, ma dopo l'installazione non crea autonomamente un systemd timer. L'esecuzione periodica viene impostata tramite un service e un timer personalizzati. Prima dell'inserimento, sostituisci example-com nel nome del service/timer con un tuo nome sicuro senza punti, ad esempio mojedomena-cz, e sostituisci example.com nel percorso di configurazione con il tuo dominio.

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

Test sicuro del servizio:

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

Se il certificato non è prossimo alla scadenza, Lego può segnalare che il rinnovo non è necessario. Questo è un comportamento corretto.

Errori comuni

Parametro sconosciuto in Lego

In Lego v5 i parametri EAB sono --eab.kid e --eab.hmac. I parametri appartengono sempre a un sottocomando specifico.

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

La pulizia dei record TXT fallisce a causa di un IP non consentito

Aggiungi anche l'indirizzo IPv6 del server agli indirizzi IP consentiti in VEDOS WAPI. Il certificato può essere emesso correttamente, ma i record TXT rimarranno nel DNS dopo la validazione.

Checklist di verifica

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

Dove andare ora?

• Protocollo ACME
• Client ACME Lego
• Client ACME Certbot
• Certificato SSL - Tutto quello che devi sapere