ACME-Client Lego - WildCard SSL

Eine ausführliche Anleitung für die Bereitstellung eines Stern-WildCard-SSL-Zertifikats über den ACME-Client Lego und die API-DNS-Validierung mit dem Webhosting VEDOS. Das Vorgehen ist für Zertifikate des Typs example.com und *.example.com gedacht, bei denen die Erneuerung automatisch erfolgen soll, ohne manuell TXT-Einträge einzugeben. Die Anleitung verwendet ein ACME-Zertifikat der Certum-Zertifizierungsstelle. Das verwendete Zertifikat dient nur als Beispiel – das Funktionsprinzip und das ACME-Bereitstellungsverfahren sind für alle Zertifizierungsstellen gleich.

Die Anleitung verwendet eine auf Lego 5.2.2 überprüfte Syntax. Lego v5 hat einige Parameter im Vergleich zu älteren Versionen geändert. Überprüfen Sie daher bei einem Fehler wie flag provided but not defined die korrekte Syntax mit lego accounts register --help, lego run --help oder lego --help.

Grundbegriffe

• ACME – Protokoll für die automatisierte Ausstellung und Erneuerung von SSL/TLS-Zertifikaten.
• Lego – ein in Go geschriebener ACME-Client. Er kann eine DNS-Validierung über viele DNS-Anbieter durchführen (Liste der unterstützten DNS-Anbieter).
• DNS-01 – Validierung über den DNS-TXT-Eintrag _acme-challenge. Sie ist für WildCard-Zertifikate erforderlich.
• EAB kid + hmac – External Account Binding (EAB)-Details von der Zertifizierungsstelle. Sie verknüpfen ACME client mit einem Konto oder Produkt.
• VEDOS WAPI – die VEDOS-API-Schnittstelle, über die Lego DNS-TXT-Einträge erstellt und löscht.
• Systemd-Dienst - eine Konfigurationsdatei, die dem Linux-System mitteilt, wie eine Anwendung gestartet und auch nach einem Serverneustart am Laufen gehalten wird.

Ersetzen Sie in allen gezeigten Beispielen die Domain example.com durch Ihre eigene Domain.

Lego-Installation

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

Nach einer erfolgreichen Installation empfehlen wir, die temporären Dateien zu entfernen.

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

DNS-API-Anbieter

Diese Anleitung verwendet die DNS-API des Domain-Registrars Vedos, der eine API für die Verwaltung des DNS registrierter Domains anbietet. Für das Vedos-Webhosting müssen Sie WAPI aktivieren und außerdem die erlaubten IP-Adressen und das WAPI-Passwort eintragen.

IP-Adressen des VPS-Servers

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

Tragen Sie im Feld Erlaubte IP-Adressen alle ausgehenden IP-Adressen Ihres Servers ein, typischerweise sowohl IPv4 als auch IPv6. Die Werte werden durch ein Leerzeichen getrennt. VEDOS erlaubt API-Anfragen nur von den aufgelisteten IP-Adressen.
Wichtig: Wenn Sie nur IPv4 erlauben und eine API-Anfrage über IPv6 ausgeht, kann die Ausstellung des Zertifikats erfolgreich sein, aber die Bereinigung der TXT-Einträge schlägt mit dem Fehler Access not allowed from this IP address fehl.

Empfohlene Werte für den DNS-Anbieter VEDOS

Apache, webroot

Die grundlegende Apache-Einrichtung ist ein unterstützender Teil. Die DNS-Validierung läuft über die DNS-API, nicht über HTTP, aber der Apache-vhost wird benötigt, um die Website nach der Ausstellung des Zertifikats auszuliefern.

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-Konfigurationsdateien

Der empfohlene Ansatz für Lego v5 ist, die Einstellungen in einer Konfigurationsdatei zu speichern. Der systemd-Dienst muss dann keinen langen Befehl mit Domains, dem DNS-Anbieter und Hooks enthalten.

Konfigurationsdatei .env

Die .env-Datei ist eine Textkonfigurationsdatei, in der Umgebungsvariablen gespeichert werden, zum Beispiel Zugangsdaten, API-Schlüssel oder Anwendungseinstellungen. Zur besseren Übersicht können Sie die Datei provider-domain.env nennen. Die Datei vedos-example.com.env enthält die VEDOS-WAPI-Zugangsdaten, daher speichern wir sie in /etc/lego und setzen darauf eingeschränkte Berechtigungen.

DOMAIN="example.com"

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

Ersetzen Sie in der folgenden Konfiguration WEDOS_LOGIN durch Ihren VEDOS-Login und WEDOS_WAPI_PASSWORD durch das in VEDOS WAPI generierte Passwort. Die timeout- und interval-Werte können Sie so belassen, wie sie sind.

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

Konfigurationsdatei lego.yml

Die .yml-Datei ist eine Textkonfigurationsdatei im YAML-Format, die für eine übersichtliche Notation von Einstellungen, Parametern und strukturierten Daten verwendet wird. Ersetzen Sie vor dem Speichern der YAML-Konfiguration example.com durch Ihre eigene Domain, *.example.com durch den Wildcard-Namen, vas@email.cz durch Ihre Kontakt-E-Mail und die Werte KID / HMAC durch die Angaben aus Ihrer ACME-Zertifikatsbestellung. Namen wie certum-example oder example-com-wildcard sind interne Bezeichnungen; Sie können sie belassen, aber bei mehreren Domains ist es ratsam, sie nach der Domain umzubenennen.

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

Ausstellung des Zertifikats

Ersetzen Sie vor dem Ausführen example.com im Pfad durch die Domain, die Sie beim Erstellen des Verzeichnisses verwendet haben. Der erste Lauf erstellt das ACME-Konto, setzt die DNS-TXT-Einträge über die DNS-API, führt die DNS-01-Validierung durch und speichert das Zertifikat.

Während des Wartens kann Lego ausgeben:

Das bedeutet, dass Lego DNS alle 30 Sekunden überprüft und höchstens 1 Stunde wartet. Überprüfen Sie nach dem Erfolg die Dateien:

Das Verzeichnis certificates/ enthält das ausgestellte .crt, .key, Zwischenzertifikate der Zertifizierungsstelle und Metadaten.

Alternatives CLI-Verfahren für 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'

Bereitstellen des Zertifikats auf Apache

Ersetzen Sie vor dem Erstellen des HTTPS-vhost example.com durch Ihre eigene Domain im Dateinamen, in den Werten ServerName und ServerAlias, in den webroot-Pfaden und in den Zertifikatspfaden. Diese Pfade müssen mit der in der Lego-Konfiguration verwendeten Domain übereinstimmen.

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 Erneuerung

Lego kann das Zertifikat erneuern, erstellt aber nach der Installation nicht selbst einen systemd-Timer. Die regelmäßige Ausführung wird über einen eigenen Service und Timer eingerichtet. Ersetzen Sie vor dem Einfügen example-com im Namen des Service/Timers durch Ihren eigenen sicheren Namen ohne Punkte, zum Beispiel mojedomena-cz, und ersetzen Sie example.com im Konfigurationspfad durch Ihre eigene Domain.

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

Sicherer Test des Dienstes:

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

Wenn das Zertifikat nicht kurz vor dem Ablauf steht, meldet Lego möglicherweise, dass keine Erneuerung erforderlich ist. Das ist korrektes Verhalten.

Häufige Fehler

Unbekannter Parameter in Lego

In Lego v5 lauten die EAB-Parameter --eab.kid und --eab.hmac. Die Parameter gehören immer zu einem bestimmten Unterbefehl.

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

Bereinigung der TXT-Einträge schlägt bei einer nicht erlaubten IP fehl

Fügen Sie auch die IPv6-Adresse des Servers zu den erlaubten IP-Adressen in VEDOS WAPI hinzu. Das Zertifikat kann korrekt ausgestellt werden, aber die TXT-Einträge bleiben nach der Validierung im DNS.

Prüf-Checkliste

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

Wie geht es weiter?

• ACME-Protokoll
• ACME-Client Lego
• ACME-Client Certbot
• SSL-Zertifikat – Alles, was Sie wissen müssen