ACME-client Lego - WildCard SSL

Een gedetailleerde handleiding voor het uitrollen van een star WildCard SSL-certificaat via de ACME-client Lego en API DNS-validatie met de VEDOS-webhosting. De procedure is bedoeld voor certificaten van het type example.com en *.example.com, waarbij de verlenging automatisch moet verlopen zonder handmatig TXT-records in te voeren. De handleiding gebruikt een ACME-certificaat van de Certum certificeringsautoriteit. Het gebruikte certificaat dient slechts als voorbeeld – het werkingsprincipe en de ACME-implementatieprocedure zijn hetzelfde voor alle certificeringsautoriteiten.

De handleiding gebruikt syntaxis die is geverifieerd op Lego 5.2.2. Lego v5 heeft enkele parameters gewijzigd ten opzichte van oudere versies, dus in geval van een fout zoals flag provided but not defined verifieert u de juiste syntaxis met lego accounts register --help, lego run --help of lego --help.

Basisbegrippen

• ACME – protocol voor geautomatiseerde uitgifte en verlenging van SSL/TLS-certificaten.
• Lego – een ACME-client geschreven in Go. Het kan DNS-validatie uitvoeren via veel DNS-providers (lijst met ondersteunde DNS-providers).
• DNS-01 – validatie via het DNS TXT-record _acme-challenge. Het is vereist voor WildCard-certificaten.
• EAB kid + hmac – External Account Binding (EAB)-gegevens van de certificeringsautoriteit. Ze koppelen Certbot aan een account of product.
• VEDOS WAPI – de VEDOS API-interface waarmee Lego DNS TXT-records aanmaakt en verwijdert.
• 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.

Vervang in alle getoonde voorbeelden het domein example.com 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

DNS API-provider

Deze handleiding gebruikt de DNS API van domeinregistrar Vedos, die een API biedt voor het beheren van de DNS van geregistreerde domeinen. Voor Vedos-webhosting moet u WAPI activeren en ook de toegestane IP-adressen en het WAPI-wachtwoord invullen.

IP-adressen van de VPS-server

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

Voer in het veld Toegestane IP-adressen alle uitgaande IP-adressen van uw server in, doorgaans zowel IPv4 als IPv6. De waarden worden gescheiden door een spatie. VEDOS staat API-verzoeken alleen toe vanaf de vermelde IP-adressen.
Belangrijk: als u alleen IPv4 toestaat en een API-verzoek via IPv6 uitgaat, kan de uitgifte van het certificaat slagen, maar zal het opschonen van de TXT-records mislukken met de fout Access not allowed from this IP address.

Aanbevolen waarden voor de VEDOS DNS-provider

Apache, webroot

De basisconfiguratie van Apache is een ondersteunend onderdeel. DNS-validatie verloopt via de DNS API, niet via HTTP, maar de Apache-vhost is nodig om de website aan te bieden nadat het certificaat is uitgegeven.

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

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, de DNS-provider en hooks te bevatten.

Configuratiebestand .env

Het .env-bestand is een tekstconfiguratiebestand waarin omgevingsvariabelen worden opgeslagen, bijvoorbeeld toegangsgegevens, API-sleutels of applicatie-instellingen. Voor de duidelijkheid kunt u het bestand provider-domein.env noemen. Het bestand vedos-example.com.env bevat de VEDOS WAPI-inloggegevens, dus we slaan het op in /etc/lego en stellen er beperkte rechten voor in.

DOMAIN="example.com"

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

Vervang in de onderstaande configuratie WEDOS_LOGIN door uw VEDOS-login en WEDOS_WAPI_PASSWORD door het in VEDOS WAPI gegenereerde wachtwoord. De waarden voor timeout en interval kunt u laten zoals ze zijn.

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

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, *.example.com door de wildcard-naam, vas@email.cz door uw contact-e-mail en de waarden KID / HMAC door de gegevens uit uw ACME-certificaatbestelling. Namen zoals certum-example of example-com-wildcard zijn interne labels; u kunt ze laten staan, maar bij meerdere domeinen is het aan te raden ze te hernoemen op basis van het domein.

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

Uitgifte van het certificaat

Vervang voor het uitvoeren example.com in het pad door het domein dat u hebt gebruikt bij het aanmaken van de map. De eerste uitvoering maakt het ACME-account aan, stelt de DNS TXT-records in via de DNS API, voert DNS-01-validatie uit en slaat het certificaat op.

Tijdens het wachten kan Lego het volgende tonen:

Dit betekent dat Lego elke 30 seconden DNS controleert en maximaal 1 uur wacht. Verifieer na succes de bestanden:

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

Alternatieve CLI-procedure voor 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'

Het certificaat uitrollen naar Apache

Vervang voordat u de HTTPS-vhost aanmaakt example.com door uw eigen domein in de bestandsnaam, de waarden ServerName en ServerAlias, de webroot-paden en de certificaatpaden. Deze paden moeten overeenkomen met het domein dat in de Lego-configuratie is gebruikt.

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

Automatische verlenging

Lego kan het certificaat verlengen, maar na de installatie maakt het niet zelf een systemd-timer aan. Regelmatige uitvoering wordt ingesteld via een eigen service en timer. Vervang voor het invoegen example-com in de naam van de service/timer door uw eigen veilige naam zonder punten, bijvoorbeeld mojedomena-cz, en vervang example.com in het configuratiepad door uw eigen domein.

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

Veilige test van de service:

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

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

Veelvoorkomende fouten

Onbekende parameter in Lego

In Lego v5 zijn de EAB-parameters --eab.kid en --eab.hmac. De parameters horen altijd bij een specifiek subcommando.

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

Het opschonen van TXT-records mislukt op een niet-toegestaan IP

Voeg ook het IPv6-adres van de server toe aan de toegestane IP-adressen in VEDOS WAPI. Het certificaat kan correct worden uitgegeven, maar de TXT-records blijven na de validatie in DNS staan.

Verificatiechecklist

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

Waar ga je nu naartoe?

• ACME-protocol
• ACME-client Lego
• ACME-client Certbot
• SSL-certificaat - Alles wat je moet weten