ACME-client Lego

De ACME-client Lego is een onafhankelijk, gratis, opensourceproject geschreven in de taal Go. Het is ideaal voor eigen integratie en scripting en geniet brede ondersteuning van domeinregistrars en DNS-providers. Lego is een flexibele ACME-client die eenvoudig kan worden geïntegreerd in eigen systemen en scripts. Naast HTTP-01-validatie biedt het DNS-validatie via veel DNS-providers (lijst met ondersteunde DNS-providers) voor het verkrijgen van WildCard SSL-certificaten.
De handleiding gebruikt syntaxis die is geverifieerd op versie Lego 5.*.* en is bedoeld voor Debian/Ubuntu met Apache 2 en de ACME-client Lego.

Basisbegrippen

• ACME – protocol voor geautomatiseerde uitgifte en verlenging van SSL/TLS-certificaten.
• HTTP-01 – ACME-validatiemethode die domeineigendom verifieert met behulp van een tijdelijk bestand dat bereikbaar is via HTTP.
• DNS-01 – validatiemethode via het DNS TXT-record _acme-challenge.
• EAB kid + hmac – External Account Binding (EAB)-gegevens van de certificeringsautoriteit. Ze koppelen Certbot aan een account of product.
• Systemd-service - een configuratiebestand dat het Linux-systeem vertelt hoe het een applicatie moet starten en draaiende moet houden, ook na een herstart van de server.

Als het domein example.com in de voorbeelden voorkomt, vervang het dan altijd door uw eigen domein.

Lego-installatie

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

Na een succesvolle installatie raden we aan de tijdelijke bestanden te verwijderen.

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

Apache, webroot

Deze procedure maakt een basis VirtualHost-configuratie voor het domein op poort 80. Het stelt DocumentRoot in, de rechten voor de webmap, maakt Apache-logs aan, schakelt de configuratie in met a2ensite, verifieert de juistheid ervan (apache2ctl configtest) en herlaadt de wijzigingen. Ten slotte verifieert het de beschikbaarheid van de website met een HTTP-verzoek 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"

Lego-configuratiebestanden

De aanbevolen aanpak voor Lego v5 is om de instellingen op te slaan in een configuratiebestand. De systemd-service hoeft dan geen lang commando met domeinen en hooks te bevatten.

Configuratiebestand lego.yml

Het .yml-bestand is een tekstconfiguratiebestand in YAML-formaat, gebruikt voor een overzichtelijke notatie van instellingen, parameters en gestructureerde gegevens. Vervang voordat u de YAML-configuratie opslaat example.com door uw eigen domein, vas@email.cz door uw contact-e-mail en de waarden KID / HMAC door de gegevens uit uw ACME-certificaatbestelling.

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

Tip! U kunt een bijna volledige YML-inhoud direct op de server genereren en vervolgens alleen de juiste e-mail, kid en hmacKey invullen. Voer gewoon het onderstaande commando uit en kopieer de inhoud van de index.html-pagina naar het bestand lego.yml.
›› De voorbereide YML tonen/verbergen.

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

De rechten en eigenaar van het bestand controleren:

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

Uitgifte van het SSL/TLS-certificaat

Controleer voor het uitvoeren echo ${DOMAIN} of stel de DOMAIN-variabele in op de naam van uw domein DOMAIN="example.com". De tool Lego voert HTTP-01-validatie uit met behulp van een bestand dat tijdelijk in de webroot is opgeslagen, verifieert het domeineigendom en maakt vervolgens een SSL/TLS-certificaat aan. Het certificaat, de privésleutel en het uitgevende (intermediaire) certificaat worden opgeslagen in de map /etc/lego/${DOMAIN}/certificates/.

Tijdens het genereren toont de ACME-client Lego informatie over het verzoek:

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

De gegenereerde SSL-certificaatbestanden verifiëren

Toont de inhoud van de map certificates die is aangemaakt door de Lego-service, inclusief het certificaat, de privésleutel en het uitgevende certificaat voor het geselecteerde domein.

De map certificates/ bevat het uitgegeven .crt, .key, de intermediaire certificaten van de certificeringsautoriteit en metadata.

Het certificaat uitrollen naar Apache

Dit voorbeeld gebruikt de variabele ${DOMAIN}, die u vanaf het begin van de handleiding al ingesteld zou moeten hebben. Voordat u de commando's uitvoert, kunt u controleren of de variabele correct is ingesteld, bijvoorbeeld: echo ${DOMAIN}
De variabele ${DOMAIN} wordt gebruikt in de naam van het configuratiebestand, de waarden ServerName en ServerAlias en het pad naar de webroot.
Waarschuwing! - de paden naar het SSL-certificaat en de privésleutel gebruiken het domein in de vorm example-com. De paden moeten overeenkomen met het domein dat in de Lego-configuratie is gebruikt.

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}

Resultaat: werkende HTTPS.

Automatische verlenging

Lego kan het certificaat automatisch verlengen, maar na de installatie maakt het niet zelf de systemd-units aan voor regelmatige uitvoering. Voor automatische verlenging moeten daarom twee units worden aangemaakt:

• lego-example-com-renew.service – voert de controle en, indien nodig, de verlenging van het certificaat uit.
• lego-example-com-renew.timer – zorgt ervoor dat de service dagelijks op een ingesteld tijdstip wordt uitgevoerd.

Vervang voor het invoegen indien nodig example-com in de naam van de service/timer door uw eigen naam, en vervang example.com in het configuratiepad door uw eigen domein.

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

Verifieer na het aanmaken van de units de inhoud ervan:

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

Herlaad de nieuwe units, schakel de timer in en controleer of deze actief is:

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

Resultaat: de timer is actief en systemd heeft de volgende uitvoering ingepland.

Veilige test van de service:

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

Resultaat: als het certificaat nog niet bijna verlopen is, kan Lego melden dat verlenging niet nodig is. Dit is correct gedrag.

Lijst met beschikbare Lego-units:

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

systemctl list-timers | grep lego

Resultaat: beide varianten tonen alle services en timers die gerelateerd zijn aan de ACME-client Lego.

Waar ga je nu naartoe?

• ACME-protocol
• ACME-client Lego (WildCard + API DNS)
• ACME-client Certbot
• SSL-certificaat - Alles wat je moet weten