Unterabschnitte

Das Certs_dehydrated-Paket

Die Einleitung

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.

Die Funktionen

Das Certs_dehydrated-Paket besteht aus folgenden Komponenten:

Die Voraussetzungen

Ein lauffähiger eisfair-Server mit installierten apache2- und certs-Paket.

Die Installation

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

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 weiter eingegangen.

Die Änderung der Konfiguration

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.

Die Konfigurationsdatei

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.

Die Parameter

START_DEHYDRATED

Für die Aktivierung des Certs_dehydrated-Paketes muss dieser Parameter lediglich auf den Wert 'yes' gestellt werden. Die Einstellung 'no' deaktiviert das Paket.

Gültige Werte: yes, no

Standardeinstellung: START_DEHYDRATED='no'

DEHYDRATED_MODE

Über diesen Parameter kann der Betriebsmodus des dehydrated- Programms eingestellt werden, d.h. es kann bestimmt werden ob sich dieses mit dem Let's EncryptTM Staging- (test) oder Produktivserver (live) verbinden soll.

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!


Gültige Werte: live, test

Standardeinstellung: DEHYDRATED_MODE='test'

DEHYDRATED_EMAIL

Über diesen Parameter wird die E-Mail-Adresse festgelegt, die bei der Zertifikatserstellung als Kontaktadresse für z.B. den Widerruf von Zertifikat verwendet werden soll.

Gültige Werte: gültige E-Mail-Adresse

Standardeinstellung: DEHYDRATED_EMAIL='root@domain.com'

DEHYDRATED_IP_VERSION (Optionaler Parameter)

Über diesen Parameter kann auf Wunsch die verwendete IP-Version eingestellt werden, welche das dehydrated-Programm standardmäßig zur Anforderung eines Zertifikates verwenden soll. Hierbei ist zu beachten, dass Let's EncryptTM bei der Prüfung der in der Zertifikatsanfrage angegebenen, primären Domain auch prüft, ob die IP-Adresse des abfragenden Servers mit der per DNS aufgelösten IP-Adresse übereinstimmt. Falls nicht, schlägt die Prüfung fehl.

Gültige Werte: 4, 6

Standardeinstellung: DEHYDRATED_IP_VERSION='4'

DEHYDRATED_PRIVATE_KEY_RENEW

Über diesen Parameter wird festgelegt, ob bei der Anforderung eines TLS-Zertifikats auch immer ein neuer privater Schlüssel zum Signieren erstellt werden soll oder nicht. Falls der Wert`nein' gewählt wird, muss über den Parameter
DEHYDRATED_PRIVATE_KEY_FILE der vollständige Pfad zu einer privaten Schlüsseldatei angegeben werden. Die gleiche Schlüsseldatei zu verwenden kann von Vorteil sein, wenn man z.B. häufiger ein Zertifikat widerrufen muss.

Gültige Werte: yes, no

Standardeinstellung: DEHYDRATED_PRIVATE_KEY_RENEW='yes'

DEHYDRATED_PRIVATE_KEY_FILE

Über diesen Parameter kann der vollständige Pfad zu einer private Schlüsseldatei angegeben werden, welche bei der Anforderung eines TLS-Zertifikates zum Signieren verwendet werden soll. Diese Parameter wird nur dann ausgewertet, wenn
DEHYDRATED_PRIVATE_KEY_RENEW='no' gesetzt wurde.

Gültige Werte: Dateiname mit absoluter Pfadangabe

Standardeinstellung: DEHYDRATED_PRIVATE_KEY_FILE='/full/path/to/key-file.key'

DEHYDRATED_PRIVATE_KEY_BITS (Optionaler Parameter)

Über diesen Parameter kann auf Wunsch eine vom Standard abweichende RSA-Schlüsselstärke eingestellt werden.

Gültige Werte: 1024, 2048, 4096, 8192

Standardeinstellung: DEHYDRATED_PRIVATE_KEY_BITS='2048'

DEHYDRATED_DOCUMENT_ROOT (Optionaler Parameter)

Über diesen Parameter kann ein vom Standard abweichendes Dokumentenstammverzeichnis festgelegt werden. Wird dieser Parameter nicht gesetzt, so wird der folgende Verzeichnispfad verwendet: /var/www/htdocs/certs_dehydrated.

Gültige Werte: absolute Pfadangabe

Standardeinstellung: DEHYDRATED_DOCUMENT_ROOT='/var/www/htdocs/certs_dehydrated'

DEHYDRATED_DATA_PATH (Optionaler Parameter)

Über diesen Parameter kann ein vom Standard abweichendes Datenverzeichnis festgelegt werden in welchem die Zertifikats- und Konfigurationsdateien abgelegt werden sollen. Wird dieser Parameter nicht gesetzt, so wird der folgende Verzeichnispfad verwendet: /var/certs/dehydrated

Gültige Werte: absolute Pfadangabe

Standardeinstellung: DEHYDRATED_DATA_PATH='/var/certs/dehydrated'

DEHYDRATED_ACCOUNT_PATH (Optionaler Parameter)

Über diesen Parameter kann ein vom Standard abweichendes Account-Verzeichnis festgelegt werden in welchem die Account- Schlüssel und Registrierungsinformationen abgelegt werden sollen. Wird dieser Parameter nicht gesetzt, so wird der folgende Verzeichnispfad verwendet: /var/certs/dehydrated/accounts

Gültige Werte: absolute Pfadangabe

Standardeinstellung: DEHYDRATED_ACCOUNT_PATH='/var/certs/dehydrated/accounts'

DEHYDRATED_ACCEPT_AGREEMENT

Durch Setzen dieses Parameters bestätigt man das Let's EncryptTM Subscriber Agreement gelesen und akzeptiert zu haben, welches über die Adresse https://acme-v01.api.letsencrypt.org/terms abgerufen werden kann.

Gültige Werte: no oder 'i accept the agreement' in Großbuchstaben

Standardeinstellung: DEHYDRATED_ACCEPT_AGREEMENT='no'

DEHYDRATED_DOMAIN_N

Über diesen Parameter wird die Anzahl der Domains festgelegt für die separate Let's EncryptTM Zertifikate angefordert werden sollen.

Gültige Werte: Zahl

Standardeinstellung: DEHYDRATED_DOMAIN_N='1'

DEHYDRATED_DOMAIN_x_ACTIVE

Wird dieser Parameter auf den Wert `yes' gesetzt, so wird der zugehörige Datensatz aktiviert, `no' deaktiviert ihn.

Gültige Werte: yes oder no

Standardeinstellung: DEHYDRATED_DOMAIN_1_ACTIVE='yes'

DEHYDRATED_DOMAIN_x_NAME

Über diesen Parameter können eine oder mehrere FQDN-Namen (Fully Qualified Domain Name), getrennt durch einen Doppelpunkt, angegeben werden welche in ein TLS-Zertifikat einfließen sollen. Die erste Domain ist die Hauptdomain eines Zertifikates, alle folgenden, optionalen Einträge stellen alternative Domainnamen dar. Die Verwendung von IP-Adressen wird generell von Let's EncryptTM-Zertifikaten nicht unterstützt.

Hinweis
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äßt.


Gültige Werte: FQDN

Beispiel: DEHYDRATED_DOMAIN_1_NAME='meine.domain.com'

DEHYDRATED_DOMAIN_x_USAGE

Über diesen Parameter können einer oder mehrerer, durch einen Doppelpunkt voneinander getrennte eisfair-Paketnamen angegeben werden für welche dieses Zertifikat verwendet werden soll. So diese Pakete reservierte Zertifikatsnamen verwenden, werden automatisch die erforderlichen symbolischen Links auf das konfigurierte Let's EncryptTM-Zertifikat erstellt.

Gültige Werte: all oder apache2, ldapserver, mail, mini_httpd, partimg, pure-ftpd, ssmtp

Beispiel: DEHYDRATED_DOMAIN_1_USAGE='apache2:mail'

DEHYDRATED_HOOK_CHAIN

Wird dieser Parameter auf den Wert `yes' gesetzt, so wird ein Hook nur einmal pro Zertifikat und nicht für jeden Domainnamen in einem Zertifikat aufgerufen.

Gültige Werte: yes oder no

Standardeinstellung: DEHYDRATED_HOOK_CHAIN='no'

DEHYDRATED_HOOK_CMD_N

Über diesen Parameter wird die Anzahl der auszuführenden Befehle festgelegt, welche bei Auftreten von Ereignissen ausgeführt werden sollen.

Gültige Werte: Zahl

Standardeinstellung: DEHYDRATED_HOOK_CMD_N='2'

DEHYDRATED_HOOK_CMD_x_ACTIVE

Wird dieser Parameter auf den Wert `yes' gesetzt, so wird der zugehörige Datensatz aktiviert, `no' deaktiviert ihn.

Gültige Werte: yes oder no

Standardeinstellung: DEHYDRATED_HOOK_CMD_1_ACTIVE='yes' DEHYDRATED_HOOK_CMD_2_ACTIVE='yes'

DEHYDRATED_HOOK_CMD_x_TYPE

Über diesen Parameter wird das Ereignis ausgewählt bei welchem der Befehl ausgeführt werden soll.

Gültige Werte: clean_challenge, deploy_cert, deploy_challenge, 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'

DEHYDRATED_HOOK_CMD_x_EXEC

Über diesen Parameter wird der Befehl festgelegt, welcher beim Auftreten eines Ereignisses ausgeführt werden soll.

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'

DEHYDRATED_HOOK_CMD_x_OPTIONS

Über diesen Parameter werden die Optionen festgelegt, welche an den definierten Befehl übergeben werden sollen.

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'

DEHYDRATED_CHECK_ON_START

Über diesen Parameter wird festgelegt, ob nach einem Neustart des eisfair-Servers eine Zertifikatsprüfung durchgeführt werden soll. Dies kann z.B. für Rechner interessant sein, die nicht dauerhaft betrieben werden.

Gültige Werte: yes, no

Standardeinstellung: DEHYDRATED_CHECK_ON_START='no'

DEHYDRATED_CHECK_CRON

Wird dieser Parameter auf 'yes' gestellt, so wird regelmäßig geprüft, ob Let's EncryptTM-Zertifikate für die konfigurierten Domains aktualisiert werden müssen, die Einstellung 'no' deaktiviert diese Funktion.
Über den Parameter DEHYDRATED_CHECK_CRON_SCHEDULE wird dabei der Zeitintervall vorgegeben, in welchem eine Prüfung durchgeführt wird.

Gültige Werte: yes, no

Standardeinstellung: DEHYDRATED_CHECK_CRON='yes'

DEHYDRATED_CHECK_CRON_SCHEDULE

Über diesen Parameter wird festgelegt zu welchem Zeitpunkt bzw. in welchem Intervall eine automatisierte Prüfung der konfigurierten Let's EncryptTM-Zertifikate erfolgen soll. Die fünf Teilparameter haben dabei folgende Bedeutung:

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'

DEHYDRATED_LOG_COUNT

Über diesen Parameter wird eingestellt, wie viele Logdateien vorgehalten werden sollen. Wird dieser Wert überschritten, so wird die älteste Logdatei gelöscht.

Gültige Werte: Zahl

Standardeinstellung: DEHYDRATED_LOG_COUNT='6'

DEHYDRATED_LOG_INTERVAL

Dieser Parameter bestimmt in welchen Intervallen die Logdateien archiviert werden sollen. Zur Auswahl stehen die Schlüsselwörter `daily' - täglich, `weekly' - wöchentlich und `monthly' - monatlich.

Gültige Werte: daily, weekly, monthly

Standardeinstellung: DEHYDRATED_LOG_INTERVAL='weekly'

Der Aufruf von Ereignisskripten

Die Ereignisse

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. Folgende Ereignisse existieren:

Die Umgebungsvariablen

Beim Aufruf eines Ereignisskriptes stehen eine begrenzte Anzahl von Umgebungsvariablen zur Verfügung auf welche aus den Skripten zugegriffen werden kann. Folgende Umgebungsvariablen existieren:

Die Zuordnung der Umgebungsvariablen zu den Ereignissen

Folgende Umgebungsvariablen stehen beim Auftreten der angegebenen Ereignisses zur Verfügung:

Die standarmäßig eingerichteten Ereignisskripte

In der Konfiguration des Paketes sind standardmäßig bereits drei Skriptaufrufe aktiviert, die für die korrekte Funktion des Paketes erforderlich sind.

/var/install/config.d/certs_dehydrated.sh -create-eisfair-cert

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.

/var/install/config.d/certs_dehydrated.sh -cleanup-certs

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.

/var/install/config.d/certs_dehydrated.sh -send-challenge-warning

Dieser Skriptaufruf versendet eine Warnnachricht an den 'Postmaster', wenn es bei dem Abruf eines von Let's EncryptTM angeforderten Zertifikates zu einem Fehler bei der Prüfung der ausgehandelten Challenge gekommen und der Abruf somit fehlgeschlagen ist.

Weitere Funktionen, die bei Bedarf zur Verfügung stehen

Folgende Skriptaufrufe stehen darüber hinaus bei Bedarf zur Verfügung:

/var/install/config.d/certs_dehydrated.sh -create-eisfair-cert

Dieser Skriptaufruf erzeugt eisfair-spezifische Zertifikatsdateien in der eisfair-Verzeichnisstruktur.

/var/install/config.d/certs_dehydrated.sh -cleanup-certs

Dieser Skriptaufruf archiviert abgelaufene bzw. ersetzte Let's EncryptTMZertifikatsdateien und verschiebt diese standarmäßig nach /var/certs/dehydrated/archive.

Verschiedenes

Den Serverzugriff von extern prüfen

Damit die mit einem automatischen Let's EncryptTM Zertifikatsabruf einhergehende Prüfung der in einem Zertifikat verwendeten Domain funktioniert, 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!

Eine TCP-Portfreischaltung nur für die Zertfikatsprüfung zulassen

Wie zuvor beschrieben, muss für einen automatischen Let's EncryptTM Zertifikatsabruf die Prüfung der in einem Zertifikat verwendeten Domain über einen HTTP-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 Hooks 'deploy_challenge' und 'clean_challenge' 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 avm_fritz_toolbox-Paket von Marcus Roeckrath installieren. Mit dem im Paket enthaltenen Skript `avm-fritz-toolbox.sh' können auf komfortabele 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    = 'deploy_challenge'
DEHYDRATED_HOOK_CMD_1_EXEC    = '/usr/bin/avm-fritz-toolbox.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    = 'clean_challenge'
DEHYDRATED_HOOK_CMD_2_EXEC    = '/usr/bin/avm-fritz-toolbox.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/avm-fritz-toolbox.sh'
DEHYDRATED_HOOK_CMD_2_OPTIONS = 'del --extport 80 --protocol TCP'

Let's EncryptsTM Limitierung der abrufbaren Zertifikate (Rate Limit)

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 gesetzen 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.

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 Zertifikatsauthorisierungen: 300

Die manuelle Erstellung eines privaten Zertifikatsschlüssels

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

Das Glossar

Holger Bruenjes 2017-11-12