Unterabschnitte

Das Certs_letsencrypt-Paket

Die Einleitung

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

Let's Encrypt 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_letsencrypt-Paket besteht aus folgenden Komponenten:

Die Voraussetzungen

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

Die Installation

Das Certs_letsencrypt-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_letsencrypt.

Die Parameter

START_LETSENCRYPT

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

Gültige Werte: yes, no

Standardeinstellung: START_LETSENCRYPT='no'

LETSENCRYPT_MODE

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

Gültige Werte: live, test

Standardeinstellung: LETSENCRYPT_MODE='test'

LETSENCRYPT_EMAIL

Über diesen Parameter wird die E-Mail-Adresse festgelegt, die bei der Zertifikatserstellung als Kontaktadresse im TLS-Zertifikat verwendet werden soll.

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

Standardeinstellung: LETSENCRYPT_EMAIL='root@domain.com'

LETSENCRYPT_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
LETSENCRYPT_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: LETSENCRYPT_PRIVATE_KEY_RENEW='yes'

LETSENCRYPT_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
LETSENCRYPT_PRIVATE_KEY_RENEW='no' gesetzt wirde.

Gültige Werte: yes, no

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

LETSENCRYPT_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: LETSENCRYPT_PRIVATE_KEY_BITS='2048'

LETSENCRYPT_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_letsencrypt.

Gültige Werte: absolute Pfadangabe

Standardeinstellung: LETSENCRYPT_DOCUMENT_ROOT='/var/www/htdocs/certs_letsencrypt'

LETSENCRYPT_DATA_DIR (Optionaler Parameter)

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

Gültige Werte: absolute Pfadangabe

Standardeinstellung: LETSENCRYPT_DATA_DIR='/var/certs/letsencrypt'

LETSENCRYPT_DOMAIN_N

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

Gültige Werte: Zahl

Standardeinstellung: LETSENCRYPT_DOMAIN_N='1'

LETSENCRYPT_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: LETSENCRYPT_DOMAIN_1_ACTIVE='yes'

LETSENCRYPT_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 Encrypt nicht unterstützt.

Hinweis
Es ist zu beachten, dass Let's Encrypt 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: LETSENCRYPT_DOMAIN_1_NAME='meine.domain.com'

LETSENCRYPT_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 Encrypt-Zertifikat erstellt.

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

Beispiel: LETSENCRYPT_DOMAIN_1_USAGE='apache2:mail'

LETSENCRYPT_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: LETSENCRYPT_HOOK_CMD_N='1'

LETSENCRYPT_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: LETSENCRYPT_HOOK_CMD_1_ACTIVE='yes'

LETSENCRYPT_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, unchanged_cert

Standardeinstellung: LETSENCRYPT_HOOK_CMD_1_TYPE='deploy_cert'

LETSENCRYPT_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: LETSENCRYPT_HOOK_CMD_1_EXEC='/var/install/config.d/certs_letsencrypt.sh'

LETSENCRYPT_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: LETSENCRYPT_HOOK_CMD_1_OPTIONS='-create-cert'

LETSENCRYPT_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: LETSENCRYPT_CHECK_ON_START='no'

LETSENCRYPT_CHECK_CRON

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

Gültige Werte: yes, no

Standardeinstellung: LETSENCRYPT_CHECK_CRON='yes'

LETSENCRYPT_CHECK_CRON_SCHEDULE

Über diesen Parameter wird festgelegt zu welchem Zeitpunkt bzw. in welchem Intervall eine automatisierte Prüfung der konfigurierten Let's Encrypt TLS-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: LETSENCRYPT_CRL_CRON_SCHEDULE='13 0 * * 0'

LETSENCRYPT_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: LETSENCRYPT_LOG_COUNT='6'

LETSENCRYPT_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: LETSENCRYPT_LOG_INTERVAL='weekly'

Der Aufruf von Ereignisskripten

Die Ereignisse

Bei der Anforderung eines Let's Encrypt-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:

Verschiedenes

Let's Encrypt-Zugriff von extern prüfen

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

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

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

eis 2016-11-28