Client ACME Lego

Il client ACME Lego è un progetto indipendente, gratuito e open source scritto nel linguaggio Go. È ideale per l'integrazione personalizzata e lo scripting e gode di un ampio supporto da parte di registrar di domini e provider DNS. Lego è un client ACME flessibile che può essere facilmente integrato in sistemi e script personalizzati. Oltre alla validazione HTTP-01, offre la validazione DNS attraverso numerosi provider DNS (elenco dei provider DNS supportati) per ottenere certificati SSL WildCard.
La guida utilizza una sintassi verificata sulla versione Lego 5.*.* ed è destinata a Debian/Ubuntu con Apache 2 e il client ACME Lego.

Concetti di base

• ACME – protocollo per l'emissione e il rinnovo automatizzati dei certificati SSL/TLS.
• HTTP-01 – metodo di validazione ACME che verifica la proprietà del dominio utilizzando un file temporaneo accessibile tramite HTTP.
• DNS-01 – metodo di validazione tramite il record DNS TXT _acme-challenge.
• EAB kid + hmac – dettagli External Account Binding (EAB) dell'autorità di certificazione. Collegano Certbot a un account o a un prodotto.
• 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.

Se negli esempi compare il dominio example.com, sostituiscilo sempre 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

Apache, webroot

Questa procedura crea una configurazione VirtualHost di base per il dominio sulla porta 80. Imposta DocumentRoot, i permessi per la directory web, crea i log di Apache, abilita la configurazione tramite a2ensite, ne verifica la correttezza (apache2ctl configtest) e ricarica le modifiche. Infine, verifica la disponibilità del sito web tramite una richiesta HTTP curl.

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

# or just updates
apt update
apt install --only-upgrade apache2
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 www.$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"
curl -I "http://www.$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 e hook.

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, vas@email.cz con la tua e-mail di contatto e i valori KID / HMAC con i dettagli del tuo ordine di certificato ACME.

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

storage: /etc/lego/example.com

accounts:
  certum-account:
    server: certum
    email: your@email.com   # your email address for CA Certum
    acceptsTermsOfService: true
    eab:
      kid: KID
      hmacKey: HMAC

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

challenges:
  http-chal:
    http:
      # Path to your website's document root.
      # Lego will temporarily write a file to this directory .well-known/acme-challenge/
      webroot: /var/www/example.com/public

certificates:
  example-com:
    account: certum-account
    challenge: http-chal
    domains:
      - example.com
      - www.example.com
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2

Suggerimento! Puoi generare un contenuto YML quasi completo direttamente sul server e poi limitarti a inserire l'e-mail, il kid e l'hmacKey corretti. Esegui semplicemente il comando qui sotto e copia il contenuto dalla pagina index.html nel file lego.yml.
›› Mostra/Nascondi lo YML preparato.

cat > "/var/www/$DOMAIN/public/index.html" <<EOF
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>${DOMAIN}</title>
<style>
body { font-family: sans-serif; max-width: 900px; margin: 40px auto; }
pre { background:#f4f4f4; padding:1em; overflow:auto; }
</style>
</head>
<body>

<h1>OK – ${DOMAIN}</h1>
<p>Apache is working correctly.</p>
<h2>lego.yml</h2>
<pre><code>storage: /etc/lego/${DOMAIN}

accounts:
  certum-account:
    server: certum
    email: YOUR_EMAIL
    acceptsTermsOfService: true
    eab:
      kid: YOUR_KID
      hmacKey: YOUR_HMAC_KEY

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

challenges:
  http-chal:
    http:
      webroot: /var/www/${DOMAIN}/public

certificates:
  ${DOMAIN//./-}:
    account: certum-account
    challenge: http-chal
    domains:
      - ${DOMAIN}
      - www.${DOMAIN}
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2
</code></pre>

</body>
</html>
EOF

Verifica dei permessi e del proprietario del file:

stat -c "%a %U:%G %n" /etc/lego/$DOMAIN/lego.yml

Emissione del certificato SSL/TLS

Prima dell'esecuzione, controlla echo ${DOMAIN} oppure imposta la variabile DOMAIN sul nome del tuo dominio DOMAIN="example.com". Lo strumento Lego esegue la validazione HTTP-01 utilizzando un file memorizzato temporaneamente nel webroot, verifica la proprietà del dominio e crea quindi un certificato SSL/TLS. Il certificato, la chiave privata e il certificato dell'emittente (intermediate) verranno memorizzati nella directory /etc/lego/${DOMAIN}/certificates/.

Durante la generazione, il client ACME Lego stamperà le informazioni sulla richiesta:

root@vmiXXXXXXXX:~# echo ${DOMAIN}
example.com

root@:~# lego --config /etc/lego/$DOMAIN/lego.yml

INFO  Archive account scope=accountID filepath=/etc/lego/example.com/accounts/acme.certum.pl/certum-acme/
      archives=/etc/lego/example.com/archives/accounts/acme.certum.pl_certum-acme_1785270773.zip
INFO  Private key saved. filepath=/etc/lego/example.com/accounts/acme.certum.pl/certum-account/certum-account.key
INFO  Registering the account (EAB). email=your@email.com
WARN  !!!! HEADS UP !!!!

Your account credentials have been saved in your
configuration directory at "/etc/lego/example.com/accounts".

You should make a secure backup of this folder now. This
configuration directory will also contain private keys
generated by lego and certificates obtained from the ACME
server. Making regular backups of this folder is ideal.

INFO  Obtaining bundled SAN certificate. domains="example.com, www.example.com"
INFO  Use solver. domain=www.example.com type=http-01
INFO  Use solver. domain=example.com type=http-01
INFO  http01: Trying to solve HTTP-01. domain=www.example.com
INFO  The server validated our request. domain=www.example.com
INFO  http01: Trying to solve HTTP-01. domain=example.com
INFO  The server validated our request. domain=example.com
INFO  Validations succeeded; requesting certificates. domains="example.com, www.example.com"
INFO  Waiting for certificates. timeout=30s interval=500ms domains="example.com, www.example.com"
INFO  Server responded with a certificate. domains="example.com, www.example.com"
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.crt
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.issuer.crt
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.key
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.pem
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.json

Verifica i file del certificato SSL generato

Mostra il contenuto della directory certificates creata dal servizio Lego, incluso il certificato, la chiave privata e il certificato dell'emittente per il dominio selezionato.

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

Deployment del certificato su Apache

Questo esempio utilizza la variabile ${DOMAIN}, che dovresti già avere impostato dall'inizio della guida. Prima di eseguire i comandi, puoi assicurarti che la variabile sia impostata correttamente, ad esempio: echo ${DOMAIN}
La variabile ${DOMAIN} viene utilizzata nel nome del file di configurazione, nei valori ServerName e ServerAlias e nel percorso del webroot.
Attenzione! - i percorsi del certificato SSL e della chiave privata utilizzano il dominio nella forma example-com. I percorsi devono corrispondere al dominio utilizzato nella configurazione di Lego.

cat > /etc/apache2/sites-available/${DOMAIN}-le-ssl.conf <<EOF
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName ${DOMAIN}
    ServerAlias www.${DOMAIN}

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

    SSLEngine on
    SSLCertificateFile /etc/lego/${DOMAIN}/certificates/${DOMAIN//./-}.crt
    SSLCertificateKeyFile /etc/lego/${DOMAIN}/certificates/${DOMAIN//./-}.key

    ErrorLog ${APACHE_LOG_DIR}/${DOMAIN}_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/${DOMAIN}_ssl_access.log combined
</VirtualHost>
</IfModule>
EOF

a2ensite ${DOMAIN}-le-ssl.conf
apache2ctl configtest
systemctl reload apache2

curl -I https://${DOMAIN}
curl -I https://www.${DOMAIN}

Risultato: HTTPS funzionante.

Rinnovo automatico

Lego può rinnovare il certificato automaticamente, ma dopo l'installazione non crea autonomamente le unità systemd per l'esecuzione periodica. Per il rinnovo automatico è quindi necessario creare due unità:

• lego-example-com-renew.service – esegue il controllo e, se necessario, il rinnovo del certificato.
• lego-example-com-renew.timer – garantisce che il servizio venga eseguito quotidianamente a un orario stabilito.

Prima dell'inserimento, sostituisci example-com nel nome del service/timer con il tuo nome se necessario, e sostituisci example.com nel percorso di configurazione con il tuo dominio.

cat > /etc/systemd/system/lego-${DOMAIN//./-}-renew.service <<EOF
[Unit]
Description=Renew ACME Certum SSL for example.com using Lego HTTP-01
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/lego --config /etc/lego/${DOMAIN}/lego.yml
EOF

cat > /etc/systemd/system/lego-${DOMAIN//./-}-renew.timer <<EOF
[Unit]
Description=Daily Lego renewal check for ${DOMAIN}

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

[Install]
WantedBy=timers.target
EOF

Dopo aver creato le unità, verificane il contenuto:

cat /etc/systemd/system/lego-example-com-renew.service
echo "----------------"
cat /etc/systemd/system/lego-example-com-renew.timer

Ricarica le nuove unità, abilita il timer e verifica che sia in esecuzione:

systemctl daemon-reload
systemctl enable --now lego-${DOMAIN//./-}-renew.timer
systemctl list-timers | grep lego

Risultato: Il timer è attivo e systemd ha pianificato la sua prossima esecuzione.

Test sicuro del servizio:

systemctl start lego-${DOMAIN//./-}-renew.service
systemctl status lego-${DOMAIN//./-}-renew.service --no-pager
journalctl -u lego-${DOMAIN//./-}-renew.service -n 100 --no-pager

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

Elenco delle unità Lego disponibili:

ls -l /etc/systemd/system/lego*

systemctl list-timers | grep lego

Risultato: Entrambe le varianti mostrano tutti i servizi e i timer relativi al client ACME Lego.

Dove andare ora?

• Protocollo ACME
• Client ACME Lego (WildCard + API DNS)
• Client ACME Certbot
• Certificato SSL - Tutto quello che devi sapere