Das Certs_dehydrated-Paket

Die Einleitung

Dieses Paket stellt eine Funktionen zur Verfügung um automatisiert Let's Encrypt^TM Zertifikate erstellen und verwalten zu können.

Let's Encrypt^TM ist eine freie, automatisierte, und offene Zertifizierungsstelle (CA), welche zum öffentlichen Wohl von der Internet Security Research Group (ISRG) betrieben wird.

Hinweis
Let's Encrypt^TM hat sich der Transparenz verpflichtet und veröffentlicht deshalb regelmäßig detaillierte Informationen für welche Domains Zertifikate ausgestellt wurden. Siehe hierzu den Google^TM Transparenzreport:

https://transparencyreport.google.com/https/certificates

Die Funktionen

Das Certs_dehydrated-Paket besteht aus folgenden Komponenten:

• dehydrated - Ein ACME-Dienstprogramm welches zur Abfrage von signierten TLS-Zertifikaten von einem Let's Encrypt^TM ACME-Server genutzt wird.
  (https://github.com/dehydrated-io/dehydrated/)

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:

• Certs Service
  • ...
  • Goto certs modules
    • Let's Encrypt Certificate administration
      • View documentation: Anzeigen der Dokumentation
      • Edit configuration: Bearbeiten der Konfiguration
      • Show certificate validity: Gültigkeit der Zertifikate anzeigen
      • Check certificate chain: Prüfen der Zertifikatskette
      • Send test email to administrator: E-Mail-Versand pruefen
      • Request certificate update: Manuelle Zertifikatsaktualisierung anstoßen
      • Archive unused certificates: Unbenutzte bzw. abgelaufene Zertifikate archivieren
      • View log file: Logdatei anzeigen
      • Return: Untermenü verlassen

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 Ä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_API_VERSION (Optionaler Parameter)

Über diesen Parameter kann die zu verwendende Version des ACME Protokolls festgelegt werden. Wird dieser Parameter nicht gesetzt, so wird das zu verwendenden ACME Protokoll automatisch ermittelt.

Gültige Werte: auto, 1, 2

Standardeinstellung: DEHYDRATED_API_VERSION=”

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 Encrypt^TM 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!
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'

DEHYDRATED_CHALLENGE_TYPE (Optionaler Parameter)

Über diesen Parameter kann auf Wunsch der zu verwendende Challenge-Typ eingestellt werden, welchen das dehydrated-Programm standardmäßig zur Anforderung eines Zertifikates verwenden soll. Wird dieser Parameter nicht gesetzt, so wird standardmäßig der Challenge-Typ 'http-01' verwendet.

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=”

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 Encrypt^TM 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_ALGO

Über diesen Parameter kann der zu verwendende Schlüsselalgorithmus festgelegt werden, welcher zum Signieren verwendet werden soll. Da sowohl `secp384r1' als auch `prime256v1' auf elliptischen Kurven basieren und somit als sicherer eingestuft werden, sind diese `rsa' vorzuziehen, welcher jedoch weiter verbreitet ist.

Gültige Werte: secp384r1, prime256v1, rsa

Standardeinstellung: DEHYDRATED_PRIVATE_KEY_ALGO='secp384r1'

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_PREF_CHAIN (Optionaler Parameter)

Über diesen Parameter kann auf Wunsch eine vom Standard abweichende Zertifikatskette eingestellt werden.

Beispiel:

• default: Verwendet derzeit die dst-root-ca-x3-Zertifikatskette
• dst-root-ca-x3: Server Zertifikat > R3 > ISRG Root X1
• isrg-root-x1: Server Zertifikat > R3 > DST Root CA X3

Gültige Werte: default, dst-root-ca-x3, isrg-root-x1

Standardeinstellung: DEHYDRATED_PREF_CHAIN='default'

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_APACHE2_PREFIX (Optionaler Parameter)

Über diesen Parameter kann auf Wunsch ein Dateinamensprefix für die Apache2- Konfigurationsdatei festgelegt werden, um so die Ladereihenfolge der virtuellen Hostkonfigurationen zu beeinflussen.

Gültige Werte: Text, bestehend aus den Zeichen a-z, 0-9, -, _, .

Standardeinstellung: DEHYDRATED_APACHE2_PREFIX=”

DEHYDRATED_ALPN_LISTEN_PORT (Optionaler Parameter)

Falls der Wert des Parameters DEHYDRATED_CHALLENGE_TYPE auf `tls-alpn-01' gesetzt wurde, kann über diesen Parameter auf Wunsch ein vom Standard abweichender TCP-Port für den ALPN Responder angegeben werden. Wird dieser Parameter nicht gesetzt, so wird standardmäßig der TCP-Port 443 verwendet.

Gültige Werte: Zahl

Standardeinstellung: DEHYDRATED_ALPN_LISTEN_PORT=”

DEHYDRATED_ACCEPT_AGREEMENT

Durch Setzen dieses Parameters bestätigt man das Let's Encrypt^TM 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 Encrypt^TM 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.

ACHTUNG
Es ist zu beachten, dass Let's Encrypt^TM 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'

DEHYDRATED_DOMAIN_x_USAGE

Über diesen Parameter können eine oder mehrere, 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 Encrypt^TM-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 Ereignis (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, 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'

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 Encrypt^TM-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 Encrypt^TM-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 Encrypt^TM-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:

• clean_challenge: Dieses Ereignis tritt einmal nach dem Versuch der Prüfung eines Domainnamens ein, unabhängig davon ob diese erfolgreich war oder nicht. Hier können z.B. Dateien oder DNS-Einträge gelöscht werden welche nicht länger benötigt werden.
• deploy_cert: Dieses Ereignis tritt einmal für jedes erzeugte Zertifikat ein. Hier kann man z.B. neue Zertifikatsdateien in ein anderes Verzeichnis kopieren, einen Service neu starten oder die Zertifikats Hashes neu erzeugen lassen.
• deploy_challenge: Dieses Ereignis tritt pro Domainname, eingeschlossen aller angegebenen alternativer Domainnamen, einmal nach Erzeugen des Bestätigungs-Token und vor Abruf des Zertifikates ein.
• deploy_ocsp: Dieses Ereignis tritt einmal für jede erzeugte OCSP-Stapeldatei ein.
• exit_hook: Dieses Ereignis tritt einmal nach dem Aufruf des cron-Befehls auf. Hier können zum Beispiel finale Bereinigungen oder anders geartete Aufgaben ausgeführt werden.
• generate_csr: Dieses Ereignis tritt vor jeder Zertifikatsignieroperation auf. Es kann dazu verwendet werden um z.B. eine Zertifikatsanforderung mit Hilfe eines externen Werkzeugs zu erzeugen. Es wird einzig die Ausgabe der Zertifikatsanforderung im PEM-Format erwartet.
• invalid_challenge: Dieses Ereignis tritt einmal nach dem erfolglosen Versuch einen Domainnamens zu prüfen ein. Hier kann zum Beispiel ein Administrator über einen fehlgeschlagenen Aktualisierungsversuch informiert werden.
• request_failure: Dies Ereignis tritt bei einer fehlgeschlagenen HTTP-Anfrage ein (HTTP-Fehlerkode ungleich 2xx). Hier kann zum Beispiel ein Administrator über einen fehlgeschlagenen Verbindungsversuch per E-Mail informiert werden.
• startup_hook: Dieses Ereignis tritt einmal vor dem Aufruf des cron-Befehls auf. Hier können zum initiale Befehle, wie z.B. das Starten eines Webservers, ausgeführt werden.
• unchanged_cert: Dies Ereignis tritt einmal für jedes noch gültige Zertifikat ein, welches somit nicht erneuert wurde.

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:

• ALPNCERTDIR: Das Verzeichnis indem ALPN-Zertifikate zwischen gespeichert werden.
  Standardeinstellung: /var/certs/dehydrated/alpn-certs .
• BASEDIR: Das Basisverzeichnis unter welchem sich die Verzeichnisse mit den erzeugten Zertifikatsdateien befinden.
  Standardeinstellung: /var/certs/dehydrated .
• CERTFILE: Der absolute Pfad zu der Datei die das signierte Zertifikat enthält.
  Beispiel: /var/certs/dehydrated/certs/meine.domain.de/cert.pem
• CHAINFILE: Der absolute Pfad zu der Datei die das Zwischenzertifikat enthält.
  Beispiel: /var/certs/dehydrated/certs/meine.domain.de/chain.pem
• DOMAIN: Der Domainname (CN oder alternative Domainname) welcher aktuell bearbeitet wird.
  Beispiel: meine.domain.de
• FULLCHAINFILE: Der absolute Pfad zu der Datei die die vollständige Zertifikatskette enthält.
  Beispiel: /var/certs/dehydrated/certs/meine.domain.de/fullchain.pem
• KEYFILE: Der absolute Pfad zu der Datei die den privaten Schlüssel für das Signieren der Zertifikatsanfrage enthält.
  Beispiel: /var/certs/dehydrated/certs/meine.domain.de/privkey.pem
• TIMESTAMP: Der Zeitstempel zu dem das angegebene Zertifikat ausgestellt wurde in Sekunden seit dem 1970-01-01 00:00:00 UTC.
  Beispiel: 1472909429 (-> Sat Sep 3 15:30:29 CEST 2016)
• TOKEN_FILENAME: Der Dateiname welche den Token enthält der zur Zertifikatsprüfung über HTTP bereit gestellt werden muss. Der Token wird üblicherweise über folgende URL bereit gestellt: /.well-known/acme-challenge/${TOKEN_FILENAME}.
• TOKEN_VALUE: Der Token der zur Zertifikatsprüfung über den _acme-challenge TXT-Eintrag im DNS bereit gestellt werden muss. Bei einer Prüfung über HTTP ist dieser in der über die Umgebungsvariable ${TOKEN_FILENAME} angegebenen Datei enthalten.
• WELLKNOWN: Das Dokumentenstammverzeichnis des Webserver in welchem bei einer Zertifikatsprüfung über HTTP die Tokendatei bereitgestellt wird.
  Standardeinstellung: /var/www/htdocs/certs_dehydrated .

Die Zuordnung der Umgebungsvariablen zu den Ereignissen

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

• clean_challenge: DOMAIN, TOKEN_FILENAME, TOKEN_VALUE
• deploy_cert: DOMAIN, KEYFILE, CERTFILE, FULLCHAINFILE,
  CHAINFILE, TIMESTAMP
• deploy_challenge: DOMAIN, TOKEN_FILENAME, TOKEN_VALUE
• deploy_ocsp: DOMAIN, OCSPFILE, TIMESTAMP
• exit_hook: keine Umgebungsvariablen verfügbar.
• generate_csr: DOMAIN, CERTDIR, ALTNAMES
• invalid_challenge: DOMAIN, RESULT
• request_failure: STATUSCODE, REASON, REQTYPE, HEADERS
• startup_hook: keine Umgebungsvariablen verfügbar.
• unchanged_cert: DOMAIN, KEYFILE, CERTFILE, FULLCHAINFILE,
  CHAINFILE

Die standarmäßig eingerichteten Ereignisskripte

In der Konfiguration des Paketes sind standardmäßig bereits vier 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 Encrypt^TM bereit gestellten Dateien die von eisfair benötigten Zertifikatsdateien (Server- und Zwischenzertifikat) und erforderliche, paketspezifische symbolische Links in der eisfair-Verzeichnisstruktur.

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

Dieser Skriptaufruf archiviert nicht mehr benötigte Let's Encrypt^TM 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 Encrypt^TMangeforderten Zertifikates zu einem Fehler bei der Prüfung der ausgehandelten Challenge gekommen und der Abruf somit fehlgeschlagen ist.

/var/install/config.d/certs_dehydrated.sh –restart-eisfair-services-on-request

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.

Weitere Funktionen, die bei Bedarf zur Verfügung stehen

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

Verschiedenes

Den Serverzugriff von extern prüfen

Damit die mit einem automatischen Let's Encrypt^TM 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.

Welchen Challenge-Typ soll man wann verwenden?

Wie in der Beschreibung des optionalen Parameters DEHYDRATED_CHALLENGE_TYPE erwähnt, unterstützt Let's Encrypt^TM die folgenden Challenge-Typen um zu verifizieren, dass man im Besitz der Domain ist für die eine Zertifikatsanfrage gestellt wird:

• dns-01: Dieser Challenge-Typ ist zu wählen, wenn man Zugriff auf den öffentlichen DNS-Eintrag seiner Domain hat und man dort automatisiert einen TXT-Eintrag mit der bei der Verifizierung generierten Challenge erstellen will.

• http-01: (Standardauswahl) Dieser Challenge-Typ ist zu wählen, wenn man die bei der Verifizierung generierte Challenge über den eigenen Webserver, über den Port 80/tcp, bereitstellen will.

• tls-alpn-01: Dieser Challenge-Typ ist zu wählen, wenn man die bei der Verifizierung generierte Challenge über den eigenen Webserver, über den verschlüsselten Port 443/tcp, bereitstellen will.

  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.

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

Wie zuvor beschrieben, muss für einen automatischen Let's Encrypt^TM 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!Box^TM 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!Box^TM 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 Encrypts^TM Limitierung der abrufbaren Zertifikate (Rate Limit)

Let's Encrypt^TM 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 Encrypt^TM 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

Die manuelle Erstellung eines privaten Zertifikatsschlüssels

Möchte man bei der Anforderung von Let's Encrypt^TM-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

Meldungen eines Aktualisierungslaufs

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.

Das Glossar

• ACME - Automatic Certificate Management Environment
• ALPN - Application-Layer Protocol Negotiation
• CA - Certificate Authority (Zertifizierungsstelle)
• FQDN - Fully Qualified Domain Name
• ISRG - Internet Security Research Group
• RSA - Rivest-Shamir-Adleman cryptosystem
• SOAP - Simple Object Access Protocol
• TCP - Transmission Control Protocol
• TLS - Transport Layer Security
• TM - Trademark
• URL - Uniform Resource Locator