Content
Dateianzeige für certs_dehydrated (1.1.10)
usr/share/doc/certs_dehydrated/certs_dehydrated.txt
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:
[1]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.
([2]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
o 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 [3]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
[4]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_dehydrat
ed.sh'
DEHYDRATED_HOOK_CMD_2_EXEC='/var/install/config.d/certs_dehydrat
ed.sh'
DEHYDRATED_HOOK_CMD_3_EXEC='/var/install/config.d/certs_dehydrat
ed.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 [5]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^TM angeforderten
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
[6]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:
[7]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
[8]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
[9]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: [10]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.pe
m
Moving unused file to archive directory: server-1.domain.com/fullchain-150693303
0.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
__________________________________________________________________