Dieses Paket stellt eine Funktionen zur Verfügung um automatisiert Let's EncryptTM Zertifikate erstellen und verwalten zu können.
Let's EncryptTM ist eine freie, automatisierte, und offene Zertifizierungsstelle (CA), welche zum öffentlichen Wohl von der Internet Security Research Group (ISRG) betrieben wird.
Hinweis
Let's EncryptTM hat sich der Transparenz verpflichtet
und veröffentlicht deshalb regelmäßig detaillierte Informationen für
welche Domains Zertifikate ausgestellt wurden. Siehe hierzu den
GoogleTM Transparenzreport:
Das Certs_dehydrated-Paket besteht aus folgenden Komponenten:
Ein lauffähiger eisfair-Server mit installierten apache2- und certs-Paket.
Das Certs_dehydrated-Paket wird über das Setup-Menü installiert. Wird eine ältere Paketversion vorgefunden, so wird diese deinstalliert bevor die neuen Programmdateien installiert werden.
Das Menü im Setup-Programm ist wie folgt aufgebaut:
Die Menüpunkte dürften selbsterklärend sein, da sie keinerlei weitere Eingaben erwarten. Aus diesem Grund wird auf deren Funktion nicht näher eingegangen.
Die Konfiguration kann über den Menüpunkt 'Edit configuration' geändert werden. Standardmäßig wird der Editor aufgerufen, der in der Environment-Konfiguration über die Variable 'EDITOR' festgelegt wurde. Nachdem der Editor beendet wurde wird abgefragt, ob die Konfiguration aktiviert werden soll. Wird dies bestätigt, werden über ein Skript die Anpassungen umgehend wirksam gemacht.
In der Konfigurationsdatei, die über das Menü zugänglich ist, sind folgende Parameter vorhanden; wer sie von Hand editieren will findet sie unter /etc/config.d/certs_dehydrated.
Gültige Werte: yes, no
Standardeinstellung: START_DEHYDRATED='no'
Gültige Werte: auto, 1, 2
Standardeinstellung: DEHYDRATED_API_VERSION=”
ACHTUNG
Bei Verwendung der Staging-Umgebung (test) wird
natürlich nur ein Testzertifikat erstellt, dessen Prüfung
immer einen Fehler in der Zertifikatskette ergeben
wird. Nur bei Verwendung der Produktivumgebung (live) wird
ein voll funktionierendes Zertifikat erzeugt, dessen
Zertifikatskette fehlerfrei ist!
In einem ersten Schritt sollte man trotzdem immer
erst einen Zertifikatsabruf über die Staging-Umgebung
durchführen und erst nach einem fehlerfreien Durchlauf
auf die Produktivumgebung wechseln.
Gültige Werte: live, test
Standardeinstellung: DEHYDRATED_MODE='test'
Hinweis
Weitere Informationen zur Verwendung der verschiedenen
Challenge-Typen finden sich im Absatz `Welchen Challenge-Typ
soll man wann verwenden?'
Gültige Werte: http-01, dns-01, tls-alpn-01
Standardeinstellung: DEHYDRATED_CHALLENGE_TYPE=”
Gültige Werte: gültige E-Mail-Adresse
Standardeinstellung: DEHYDRATED_EMAIL='root@domain.com'
Gültige Werte: 4, 6
Standardeinstellung: DEHYDRATED_IP_VERSION='4'
Gültige Werte: yes, no
Standardeinstellung: DEHYDRATED_PRIVATE_KEY_RENEW='yes'
Gültige Werte: Dateiname mit absoluter Pfadangabe
Standardeinstellung: DEHYDRATED_PRIVATE_KEY_FILE='/full/path/to/key-file.key'
Gültige Werte: secp384r1, prime256v1, rsa
Standardeinstellung: DEHYDRATED_PRIVATE_KEY_ALGO='secp384r1'
Gültige Werte: 1024, 2048, 4096, 8192
Standardeinstellung: DEHYDRATED_PRIVATE_KEY_BITS='2048'
Beispiel:
Gültige Werte: default, dst-root-ca-x3, isrg-root-x1
Standardeinstellung: DEHYDRATED_PREF_CHAIN='default'
Gültige Werte: absolute Pfadangabe
Standardeinstellung: DEHYDRATED_DOCUMENT_ROOT='/var/www/htdocs/certs_dehydrated'
Gültige Werte: absolute Pfadangabe
Standardeinstellung: DEHYDRATED_DATA_PATH='/var/certs/dehydrated'
Gültige Werte: absolute Pfadangabe
Standardeinstellung: DEHYDRATED_ACCOUNT_PATH='/var/certs/dehydrated/accounts'
Gültige Werte: Text, bestehend aus den Zeichen a-z, 0-9, -, _, .
Standardeinstellung: DEHYDRATED_APACHE2_PREFIX=”
Gültige Werte: Zahl
Standardeinstellung: DEHYDRATED_ALPN_LISTEN_PORT=”
Gültige Werte: no oder 'i accept the agreement' in Großbuchstaben
Standardeinstellung: DEHYDRATED_ACCEPT_AGREEMENT='no'
Gültige Werte: Zahl
Standardeinstellung: DEHYDRATED_DOMAIN_N='1'
Gültige Werte: yes oder no
Standardeinstellung: DEHYDRATED_DOMAIN_1_ACTIVE='yes'
ACHTUNG
Es ist zu beachten, dass Let's EncryptTM in Zertifikaten
weder die Verwendung von IP-Adressen noch von inoffiziellen,
selbst erstellten Domains wie .lan oder .local, etc. zulässt.
Gültige Werte: FQDN
Beispiel: DEHYDRATED_DOMAIN_1_NAME='meine.domain.com'
Gültige Werte: all oder apache2, ldapserver, mail, mini_httpd, partimg, pure-ftpd, ssmtp
Beispiel: DEHYDRATED_DOMAIN_1_USAGE='apache2:mail'
Gültige Werte: yes oder no
Standardeinstellung: DEHYDRATED_HOOK_CHAIN='no'
Gültige Werte: Zahl
Standardeinstellung: DEHYDRATED_HOOK_CMD_N='2'
Gültige Werte: yes oder no
Standardeinstellung:
DEHYDRATED_HOOK_CMD_1_ACTIVE='yes'
DEHYDRATED_HOOK_CMD_2_ACTIVE='yes'
Gültige Werte: clean_challenge, deploy_cert, deploy_challenge, deploy_ocsp, invalid_challenge, request_failure, unchanged_cert
Standardeinstellung:
DEHYDRATED_HOOK_CMD_1_TYPE='deploy_cert'
DEHYDRATED_HOOK_CMD_2_TYPE='deploy_cert'
DEHYDRATED_HOOK_CMD_3_TYPE='invalid_challenge'
Gültige Werte: absoluter Pfad zu einem ausführbaren Befehl
Standardeinstellung:
DEHYDRATED_HOOK_CMD_1_EXEC='/var/install/config.d/certs_dehydrated.sh'
DEHYDRATED_HOOK_CMD_2_EXEC='/var/install/config.d/certs_dehydrated.sh'
DEHYDRATED_HOOK_CMD_3_EXEC='/var/install/config.d/certs_dehydrated.sh'
Gültige Werte: gültige Programmoption
Standardeinstellung:
DEHYDRATED_HOOK_CMD_1_OPTIONS='–create-eisfair-cert'
DEHYDRATED_HOOK_CMD_2_OPTIONS='–cleanup-certs'
DEHYDRATED_HOOK_CMD_3_OPTIONS='–send-challenge-warning'
Gültige Werte: yes, no
Standardeinstellung: DEHYDRATED_CHECK_ON_START='no'
Gültige Werte: yes, no
Standardeinstellung: DEHYDRATED_CHECK_CRON='yes'
1 - Minuten, 2 - Stunden, 3 - Tag des Monats, 4 - Monat, 5 - Wochentag.
D.h. bei Verwendung der Standardeinstellung wird sonntäglich um 00:13h eine Aktualisierung durchgeführt. Wer Näheres über die verwendete Befehlssyntax erfahren möchte, sollte über eine Internet-Suchmaschine nach 'man' und 'crontab' suchen.
Gültige Werte: Crontab-spezifischer Parametereintrag
Standardeinstellung: DEHYDRATED_CRL_CRON_SCHEDULE='13 0 * * 0'
Gültige Werte: Zahl
Standardeinstellung: DEHYDRATED_LOG_COUNT='6'
Gültige Werte: daily, weekly, monthly
Standardeinstellung: DEHYDRATED_LOG_INTERVAL='weekly'
Bei der Anforderung eines Let's EncryptTM-Zertifikates können beim Auftreten verschiedener Ereignisse (Hooks), auf Wunsch eigene Skripte aufgerufen werden um bestimmte Aktionen zu veranlassen. Werden mehrere Skriptaufrufe füer ein dediziertes Ereignis definiert, so werden diese in der Reihenfolge der Definition ausgeführt.
Folgende Ereignisse existieren:
Beim Aufruf eines Ereignisskriptes stehen eine begrenzte Anzahl von Umgebungsvariablen zur Verfügung auf welche aus den Skripten zugegriffen werden kann. Folgende Umgebungsvariablen existieren:
Folgende Umgebungsvariablen stehen beim Auftreten der angegebenen Ereignisses zur Verfügung:
In der Konfiguration des Paketes sind standardmäßig bereits vier Skriptaufrufe aktiviert, die für die korrekte Funktion des Paketes erforderlich sind.
Dieser Skriptaufruf erzeugt aus den von Let's EncryptTM bereit gestellten Dateien die von eisfair benötigten Zertifikatsdateien (Server- und Zwischenzertifikat) und erforderliche, paketspezifische symbolische Links in der eisfair-Verzeichnisstruktur.
Dieser Skriptaufruf archiviert nicht mehr benötigte Let's EncryptTM Dateien im Unterverzeichnis /var/certs/dehydrated/archive, die sich sonst bei einer Zertifikatserneuerung im Verzeichnis /var/certs/dehydrated/certs ansammeln würden.
Dieser Skriptaufruf versendet eine Warnnachricht an den 'Postmaster', wenn es bei dem Abruf eines von Let's EncryptTMangeforderten Zertifikates zu einem Fehler bei der Prüfung der ausgehandelten Challenge gekommen und der Abruf somit fehlgeschlagen ist.
Dieser Skriptaufruf startet bei Bedarf eisfair-Dienste neu, deren Zertifikate zuvor erneuert wurden. Welcher Dienst für welches Zertifikat neu gestartet werden soll, wird über die DEHYDRATED_DOMAIN_x_USAGE Parameter festgelegt.
Folgende Skriptaufrufe stehen darüber hinaus bei Bedarf zur Verfügung:
/etc/init.d/certs_dehydrated --start-alpn-server - start alpn responder /etc/init.d/certs_dehydrated --stop-alpn-server - stop alpn responder
Damit die mit einem automatischen Let's EncryptTM Zertifikatsabruf einhergehende Prüfung der in einem Zertifikat verwendeten Domain funktioniert, wenn der Challenge-Typ `http-01' verwendet wird, muss die folgende URL über das Internet erreichbar sein: http://meine.domain.dom/.well-known/acme-challenge
Der erfolgreiche Zugriff wird durch die Anzeige des folgenden Textes bestätigt:
Let's Encrypt rocks!
Hinweis
Da für die Anzeige des genannten Textes eine Datei
namens index.html verwendet wird, ist es erforderlich,
dass der Parameter APACHE2_DIRECTORY_INDEX
auch diesen Dateinamen enthält!
Bei Verwendung des Challenge-Typ `tls-alpn-01' ist sicher zu stellen, dass der TCP-Port 443 bzw. den über den Parameter DEHYDRATED_ALPN_LISTEN_PORT definierte Port, korrekt an den ALPN-Responder-Dienst weiter geleitet wird.
ACHTUNG
Der Challenge-Typ `tls-apn-01' kann nur füer die
Verifizierung gewählt werden, wenn der Server zuvor
bereits über das https-Protokoll erreicht werden
kann. Falls dies nicht der Fall ist, muss füer den
erstmaligen Zertifikatsabruf die Einstellung `http-01'
verwendet werden
Wird dieser Parameter nicht gesetzt, so wird standardmäßig mittels des Challenge-Typ `http-01' eine Prüfung über den Port 80/tcp duchgeführt.
Wie zuvor beschrieben, muss für einen automatischen Let's EncryptTM Zertifikatsabruf die Prüfung der in einem Zertifikat verwendeten Domain über einen HTTP-/HTTPS-Zugriff über das Internet ermöglicht werden. Da nicht jeder nur für diese Prüfung dauerhaft einen über das Internet zugänglichen Webserver betreiben möchte, kann man bei Bedarf über die Ereignisse 'startup_hook' und 'exit_hook' eine temporäre TCP-Portfreischaltung auf seinem Internet-Router aktivieren, so dieser dies skriptgesteuert zulässt.
Wer eine AVM-FRITZ!BoxTM sein Eigen nennt kann sich glücklich schätzen und hierfür das fbtr64toolbox-Paket von Marcus Roeckrath installieren. Mit dem im Paket enthaltenen Skript `fbtr64toolbox.sh' können auf komfortable Weise Parameter über SOAP-Aufrufe gesetzt oder gelöscht werden. Voraussetzung für die korrekte Funktion des Skriptes ist, dass in der Router-Konfiguration, unter `Heimnetz -> Heimnetzübersicht -> Netzwerkeinstellungen -> Heimnetzfreigaben' der Parameter `Zugriff für Anwendungen zulassen' aktiviert wird. Mittels der folgenden Konfigurationsparameter kann man anschließend im Paket automatisiert TCP-Portfreigabe in der AVM-FRITZ!BoxTM aktivieren bzw. deaktivieren lassen:
DEHYDRATED_HOOK_CMD_1_ACTIVE = 'yes' DEHYDRATED_HOOK_CMD_1_TYPE = 'startup_hook' DEHYDRATED_HOOK_CMD_1_EXEC = '/usr/bin/fbtr64toolbox.sh' DEHYDRATED_HOOK_CMD_1_OPTIONS = 'add --extport 80 --protocol TCP --intclient 192.168.178.3 --intport 80 --description "my port forward" --active' DEHYDRATED_HOOK_CMD_2_ACTIVE = 'yes' DEHYDRATED_HOOK_CMD_2_TYPE = 'exit_hook' DEHYDRATED_HOOK_CMD_2_EXEC = '/usr/bin/fbtr64toolbox.sh' DEHYDRATED_HOOK_CMD_2_OPTIONS = 'add --extport 80 --protocol TCP --intclient 192.168.178.3 --intport 80 --description "my port forward" --inactive'
Wer die eingerichtete TCP-Portfreischaltung lieber jedes Mal wieder vollständig löschen möchte kann dies z.B. über den folgenden Befehlsaufruf bewerkstelligen:
DEHYDRATED_HOOK_CMD_2_EXEC = '/usr/bin/fbtr64toolbox.sh' DEHYDRATED_HOOK_CMD_2_OPTIONS = 'del --extport 80 --protocol TCP'
Let's EncryptTM limitiert die Anzahl der abrufbaren Zertifikate pro Zeiteinheit um eine faire Nutzung für so viele Personen wie möglich zu gewährleisten. Die gesetzten Grenzwerte sollten für die meisten Personen nicht erreicht werden. Auch führt das Erneuern von Zertifikaten grundsätzlich nicht zu einem Erreichen eines Grenzwertes. So können selbst größere Organisationen eine hohe Anzahl von Zertifikaten abrufen, ohne dass Let's EncryptTM eingreifen bzw. tätig werden muss.
Hinweis
Wegen der genannten Grenzwerte sollten initiale Tests
eines Zertifikatsabrufes immer gegen die Staging-Umgebung
durchgeführt werden.
Zum Zeitpunkt der Erstellung dieser Dokumentation galten folgende Grenzwerte, welche man jederzeit unter folgender Webadresse nachschlagen kann: https://letsencrypt.org/docs/rate-limits/
Anzahl doppelter Zertifikate ..................: 5/Woche Anzahl der Zertifikate pro registrierter Domain: 20/Woche Anzahl der Domain-Namen pro Zertifikat ........: 100 Anzahl der Zertifikatsanfragen pro IP-Adresse .: 500 Anzahl ausstehender Zertifikatsautorisierungen.: 300
Möchte man bei der Anforderung von Let's EncryptTM-Zertifikaten eine eigene, feste Schlüsseldatei verwenden, so muss diese vor der der Verwendung manuell erstellt werden. Der Kommandozeilenbefehl um eine private Schlüsseldatei mit einer Größe von 4096 Byte zu erstellen lautet:
openssl genrsa -out /path/to/store/private.key 4096
Processing server-1.domain.com + Checking domain name(s) of existing cert... changed! + Domain name(s) are not matching! + Names in old certificate: server-1.domain.com server-1-alt.domain.com + Configured names: server-1.domain.com + Forcing renew. + Checking expire date of existing cert... + Valid till Dec 31 07:30:56 2017 GMT (Longer than 30 days). Ignoring because renew was forced! + Signing domains... + Generating private key... + Generating signing request... + Requesting challenge for server-1.domain.com... -> Executing hook script 'deploy_challenge' ... + Responding to challenge for server-1.domain.com... + Challenge is valid! -> Executing hook script 'clean_challenge' ... + Requesting certificate... + Checking certificate... + Done! + Creating fullchain.pem... + Using cached chain! -> Executing hook script 'deploy_cert' ... creating files/links required by eisfair ... + domain 'server-1.domain.com': - link '/usr/local/ssl/csr/server-1.domain.com.csr' created/updated. - link '/usr/local/ssl/private/server-1.domain.com.key' created/updated. - link '/usr/local/ssl/newcerts/server-1.domain.com.crt' created/updated. - file '/usr/local/ssl/newcerts/server-1.domain.com.dh' exists. - file '/usr/local/ssl/certs/server-1.domain.com.pem' created. + domain 'server-1-alt.domain.com': - skipped. checking symbolic links to certificate ... + domain 'server-1.domain.com': - link 'exim.pem' ok. - link 'imapd.pem' ok. - link 'ipop3d.pem' ok. restarting eisfair services ... + package 'mail' restarted. # INFO: Using main config file /etc/dehydrated/config Moving unused file to archive directory: server-1.domain.com/cert-1506933030.csr Moving unused file to archive directory: server-1.domain.com/cert-1506933030.pem Moving unused file to archive directory: server-1.domain.com/chain-1506933030.pem Moving unused file to archive directory: server-1.domain.com/fullchain-1506933030.pem Moving unused file to archive directory: server-1.domain.com/privkey-1506933030.pem + Done! Processing server-2.domain.com + Signing domains... + Creating new directory /var/certs/dehydrated/certs/server-2.domain.com ... + Generating private key... + Generating signing request... + Requesting challenge for server-2.domain.com... -> Executing hook script 'deploy_challenge' ... + Responding to challenge for server-2.domain.com... + Challenge is valid! -> Executing hook script 'clean_challenge' ... + Requesting certificate... + Checking certificate... + Done! + Creating fullchain.pem... + Using cached chain! -> Executing hook script 'deploy_cert' ... creating files/links required by eisfair ... + domain 'server-1.domain.com': - link '/usr/local/ssl/csr/server-1.domain.com.csr' created/updated. - link '/usr/local/ssl/private/server-1.domain.com.key' created/updated. - link '/usr/local/ssl/newcerts/server-1.domain.com.crt' created/updated. - file '/usr/local/ssl/newcerts/server-1.domain.com.dh' exists. - file '/usr/local/ssl/certs/server-1.domain.com.pem' created. + domain 'server-2.domain.com': - link '/usr/local/ssl/csr/server-2.domain.com.csr' created/updated. - link '/usr/local/ssl/private/server-2.domain.com.key' created/updated. - link '/usr/local/ssl/newcerts/server-2.domain.com.crt' created/updated. - file '/usr/local/ssl/newcerts/server-2.domain.com.dh' exists. - file '/usr/local/ssl/certs/server-2.domain.com.pem' created. checking symbolic links to certificate ... + domain 'server-1.domain.com': - link 'exim.pem' ok. - link 'imapd.pem' ok. - link 'ipop3d.pem' ok. restarting eisfair services ... + package 'mail' restarted. # INFO: Using main config file /etc/dehydrated/config + Done! finished.