Dies ist eine Sammlung kleiner Python 3 Skripte, um die Erstellung und Validierung von Let's Encrypt SSL Zertifikaten in Verbindung mit Hosteurope WebHosting und Wordpress Hosting Paketen so weit als möglich zu automatisieren.
Die Skripte automatisieren folgende Schritte:
- Aufruf des certbot mit den richtigen Optionen, um ein Sammel-Zertifikat für die gewünschten Domains zu erstellen oder zu verlängern
- Hochladen der von certbot vorgegebenen Validierungstokens für die einzelnen Domains mittels FTP
Das abschließende Einbinden des Zertifikats bleibt ein manueller Schritt, da Hosteurope dafür keine API bietet, die eine Automatisierung ermöglicht.
Dieses Vorgehen wurde sowohl mit WebHosting Paketen als auch den eingeschränkten Wordpress Hosting Paketen erfolgreich durchgeführt.
Für die Nutzung der Skripte wird benötigt:
Die Skripte wurden unter Linux sowie dem Windows Subsystem for Linux getestet und das Vorgehen auf diesem Blog beschrieben.
Die Skripte werden mittels 3 JSON Dateien konfiguriert, die manuell zu erstellen sind.
Die Konfigurationsdateien müssen entweder im gleichen Verzeichnis wie die Python Skripte oder im Verzeichnis ~/.config/hosteurope-letsencrypt liegen.
In der Datei einstellungen.json wird die im Zertifikat zu hinterlegende Emailadresse gepflegt. Weiterhin wird konfiguriert, ob die Staging Umgebung von Let's Encrypt verwendet werden soll. Die Staging Umgebung sollte man nutzen, wenn man kein richtiges Zertifikat erstellen will, sondern zum Beispiel noch mit den richtigen Parametern experimentiert.
{
"email": "webmaster@example.com",
"staging": false,
"preferred-challenge": "http",
"kis-username": "sso-username",
"kis-password": "my sso password",
"kis-2fa": true
}
| Parameter | Bedeutung |
|---|---|
| E-Mail Adresse für den Let's Encrypt Account. | |
| staging | true aktiviert die Verwendung der Let's Encrypt Staging Umgebung. |
| preferred-challenge | http oder dns. Setzt die zu verwendende Let's Encrypt Challenge auf HTTP oder DNS. |
| kis-username | Username, that you use to log into sso.hosteurope.de (only needed for certificate replacement) |
| kis-password | Password, that you use to log into sso.hosteurope.de (only needed for certificate replacement) |
| kis-2fa | Boolean indicating whether you use 2FA to log into sso.hosteurope.de (only needed for certificate replacement) |
In der Datei domains.json gibt man die Domains an, für die ein Zertifikat erstellt werden soll. Neben den Domainamen muss weiterhin der Pfad auf dem FTP Server angegeben werden, damit die Skripte die von certbot vorgegebenen Validierungstoken an den richtigen Stellen platzieren können.
{
"domain1.example.com": "domain1",
"domain2.example.com": "domain-2/komischer_pfad"
}
Es können natürlich nicht nur Sub-Domains, sondern alle im WebHosting Paket enthaltenen Domains angegeben werden. Da Let's Encrypt erst experimentelle Unterstützung für Wildcard Zertifikate bietet, muss jede Sub-Domain einzeln aufgeführt werden!
In der Datei cert-urls.json gibt man die URLs an, unter denen das Zertifikat für eine bestimmte Domain ersetzt werden kann.
{
"example.com": "https://kis.hosteurope.de/administration/webhosting/admin.php?menu=6&wp_id=....&mode=sslupload&v_id=....",
"example2.com": "https://kis.hosteurope.de/administration/webhosting/admin.php?menu=6&wp_id=....&mode=sslupload&v_id=....",
}
Die entsprechende URL findet man normalerweise über Webhosting > Konfigurieren > Sicherheit & SSL > SSL Administrieren > example.com > Ersetzen
In der Datei ftp.json gibt man die FTP Zugangsdaten an. Diese werden vom validate.py Skript genutzt, um per FTP die entsprechenden Validierungstoken auf dem Webserver zu platzieren.
{
"server": "ftp-server.hosteurope.de",
"login": "ftp-user",
"passwort": "GEHEIM"
}
Das Skript löscht die hochgeladenen Token nicht. Die Token liegen im jeweiligen Domainpfad auf dem Webserver im Unterverzeichnis .well-known/acme-challenge.
Achtung: Wenn Du Wordpress Hosting verwendest ist zusätzliche Konfiguration nötig, damit die Domainvalidierung von Let's Encrypt funktioniert.
Um die Domain zu validieren, fragt Let's Encrypt, falls die HTTP-01 Challenge verwendet wird, eine URL ab: http://<YOUR_DOMAIN>/.well-known/acme-challenge/<TOKEN>.
Die Hosteurope Wordpress Hosting Pakete kontrollieren die Dateien in /; als Kunde kann man per FTP lediglich Dateien im Wordpress-Verzeichnis cust_upload/ ablegen.
Wir müssen also sicherstellen, dass die Validierung über /.well-known/acme-challenge/<TOKEN> funktioniert, in dem die von diesen Skripten (validate.py automatisiert den Tokenupload über FTP) erzeugte Datei geladen wird. Folgendes Vorgehen:
- Installiere das Wordpress Plugin Redirection.
- In den Optionen des Plugins setze IP-Protokollierung auf
keineoderAnonymisiert(#DSGVO). - Damit das Redirection Plugin funktioniert, muss eine Wordpress
.htaccessvorhanden sein. Diese kannst du automatisch erzeugen lassen, indem Du Einstellungen > Permalinks öffnest und speicherst. - Lege nun eine Umleitung mit folgenden Parametern an:
| Parameter | Wert |
|---|---|
| URL-Quelle | ^/\.well-known/acme-challenge/(.*) |
| Titel | Let's Encrypt Domain Validation |
| Passend | Nur URL |
| Wenn übereinstimmend | Umleitung zur URL |
| HTTP-Status Code | 301 Dauerhaft verschoben |
| Ziel-URL | http://<YOUR_DOMAIN>/cust_upload/www/.well-known/acme-challenge/$1 |
In der oben genannten Ziel-URL ist der Pfadanteil www/ enthalten. Dieses Verzeichnis musst Du selbst (z.B. per FTP) innerhalb von cust_upload/ anlegen. Ausserdem muss dieser Pfad als Mapping in domains.json angegeben werden, damit der Upload des Tokens die Datei wie von Let's Encrypt erwartet erzeugen kann.
Ein neues Zertifikat wird erstellt mittels:
sudo python3 neu.py
Ein bestehendes Zertifikat wird verlängert mittels:
sudo python3 verlaengern.py
Wenn die Skripte mit Root-Rechten laufen, legt certbot die generierten Zertifikate unter /etc/letsencrypt
ab. Wird certbot als user aufgerufen, werden die certbot Parameter --work-dir, --config-dir, --logs-dir gesetzt und ~/.config/hosteurope-letsencrypt als Basis verwendet.
Die folgenden Abschnitte erklären im Detail, was bei jedem Skript geschieht.
Das Skript neu.py ruft certbot auf und fordert die Erstellung eines Zertifikats für alle in domains.json angegebenen Domains an.
Um eine Domain gegenüber Let's Encrypt zu validieren, muss eine Datei hochgeladen werden. Dazu wird beim Aufruf von certbot das validate.py Skript übergeben. Dieses erhält von certbot Namen und Inhalt der hochzuladenden Datei und lädt diese via FTP auf den Hosteurope Webserver hoch.
Da certbot Ausgaben des validate.py Skripts unterdrückt, werden Debug Meldungen in die Datei validation.log geschrieben.
Nachdem das Zertifikat erstellt wurde, muss es manuell im KIS eingebunden werden.
Let's Encrypt Zertifikate haben eine Gültigkeit von 90 Tagen. Deshalb müssen die Zertifikate verlängert werden. Falls man in einstellungen.json eine gültige Emailadresse angegeben hat, wird man von Let's Encrypt einige Tage vor Ablauf daran erinnert.
Es muss kein komplett neues Zertifikat erstellt werden, sondern ein bestehendes Zertifikat kann verlängert werden. Das verlaengern.py Skript führt diese Verlängerung durch. Dazu wird wiederum mittels validate.py die Domain gegenüber Let's Encrypt validiert.
Nachdem das Zertifikat verlängert wurde, muss es manuell über das KIS eingebunden werden.
Zertifikate können nur verlängert werden, wenn die zugehörigen Dateien nicht gelöscht wurden. certbot legt alle zu einem Zertifikat zugehörigen Dateien als root unterhalb von /etc/letsencrypt oder als User unter ~/.config/hosteurope-letsencrypt ab. Die Zertifikatsdateien enthalten eine Nummer in ihrem Dateinamen, die bei jeder Verlängerung um 1 hochgezählt wird. Das neueste Zertifikat ist immer jenes, mit der höchsten Nummer im Dateinamen.
set_dns_challenge benötigt das Python-Paket pyppeteer.
Das Paket kann man über pip install pyppeteer installieren.
Alternativ kann auch pipenv verwendet werden: Dafür muss man pipenv auf dem System installieren.
Danach kann mit pipenv shell und pipenv install die nötige Abhängigkeit hinzugefügt werden.
Durch certbot wird bei einer Validierung per DNS eine DNS Challenge erwartet. In der Regel wird dieses Verfahren für Wildcard Domains (*.domain.de) genutzt und setzt einen DNS TXT record vorraus in dem der Challenge-String angegeben werden muss. Der DNS-Eintrag muss vorher per Hand angelegt werden, unter Domainservices > Domain-Administration > Namesserver- / DNS-Einträge ändern > mydomain.de. Dort muss ein neuer TXT Eintrag mit _acme-challenge.domain.de angelegt werden. Das Skript set_dns_challenge.py erlaubt das automatisierte Eintragen des Challenge-String.
Dazu wird das Skript mit der Domain und dem Challenge-String aus certbot als Parametern gestartet.
./set_dns_challenge.py -d *.domain.de -c 3940jw09spfi3wq9rwjiefpw93r0w9
Die Domains und dazu passenden URLs aus KIS, die das Skript benötigt, können in der domains.json eingetragen werden. (Auch parallel zu Eintragen zur http Validierung.) Die benötigte Seite der URL ist dieselbe wie zum Eintragen des TXT Records oben.
{
"*.example.com": "https://kis.hosteurope.de/administration/domainservices/index.php?menu=....&mode=autodns&submode=edit&domain=....",
"*.example.de": "https://kis.hosteurope.de/administration/domainservices/index.php?menu=....&mode=autodns&submode=edit&domain=...."
}
Nach Ausführen den Skripts dauert es ca. 10-15 Sekunden bis der DNS-Eintrag aktualisiert verfügbar ist. Dann kann im certbot Enter gedrückt werden, um die DNS-Challenge zu prüfen.
set_certificate benötigt das Python-Paket pyppeteer.
Das Paket kann man über pip install pyppeteer installieren.
Alternativ kann auch pipenv verwendet werden: Dafür muss man pipenv auf dem System installieren.
Danach kann mit pipenv shell und pipenv install die nötige Abhängigkeit hinzugefügt werden.
Durch certbot wird ein Zertifikat erstellt, das alle angegebenen Domains abdeckt. Dieses Zertifikat muss
jedoch noch im Hosteurope KIS eingebungen werden. Der Skript set_certificate.py kann das automatisieren
: Für alle in cert-urls.json eingetragenen Domains ersetzt er das Zertifikat.
Durch certbot wird ein Zertifikat erstellt, das alle angegebenen Domains abdeckt. Dieses Zertifikat muss manuell im Hosteurope KIS als globales Zertifikat angegeben werden. Der entsprechende Menüpunkt findet sich unter:
Webhosting -> Sicherheit & SSL -> SSL administrieren
Soll ein neues Zertifikat hochgeladen werden, muss das oberste globale Zertifikat ersetzt werden. Dieses Zertifikat gilt für alle Domains und Sub-Domains, für die kein eigenes Zertifikat gesetzt ist.
certbot erzeugt 4 Dateien. Lediglich die folgenden 2 Dateien müssen im KIS im entsprechenden Formular hochgeladen werden:
- Zertifikat: fullchain.pem
- Key: privkey.pem
Das Passwort Feld muss leer bleiben!
Nach dem Hochladen startet Hosteurope den Webserver neu und das Zertifikat ist innerhalb weniger Minuten online.
Wenn für die Website vorher kein HTTPS verwendet wurde, muss auch der DNS A Record der Domain geändert werden.
Die neue IP-Adresse wird unter Domainservices > Domain-Administration > Namesserver- / DNS-Einträge ändern > mydomain.de
als "SSL A-Record-IP" gelistet.