Was ist Let's Encrypt?

Um das Ansprechen von Lobster_data per HTTPS zu ermöglichen, benötigen Sie ein Zertifikat. Siehe Abschnitt Hinzufügen eines HTTPS-Listeners.

Let’s Encrypt (→ Dokumentation) ist eine kostenfreie Zertifizierungsstelle (CA, Certificate Authority), über die Lobster_data automatisiert entsprechende Zertifikate erhalten kann. Diese werden dann auch automatisch erneuert, wenn sie abgelaufen sind.

Lobster_data verwendet dazu intern das ACME-Protokoll und den Certbot Client. Die entsprechenden Komponenten sind im Standard enthalten und müssen lediglich konfiguriert werden, wie im folgenden beschrieben.

Voraussetzungen

Der CertificateExchangeService muss aktiv sein (./etc/factory.xml, siehe dort).
Die Konfigurationsdatei ./etc/cex.xml muss angepasst werden (siehe unten).
Lobster_data muss öffentlich erreichbar sein (Port 80 und 443 müssen offen sein).
forceSSL darf nicht aktiv sein, da sonst kein Zertifikat generiert werden kann! Hierzu müssen zwei Dateien angepasst werden.
- ./etc/webdefault.xml - Diesen Part wie ersichtlich in Kommentar setzen.
- ./etc/startup.xml - Den Parameter auf false setzen.

Anpassen der Konfigurationsdatei ./etc/cex.xml

Bei einer Installation ab Lobster_data 4.5 befindet sich bereits ein vorbereiteter Block für das Hinzufügen von Certbot Handlern in der Konfigurationsdatei. Ändern Sie dort zur "Aktivierung" die Tags NoCall zu Call (die identische Änderung beim schließenden Tag nicht vergessen, sonst endet der Start des Systems mit einem Fehler). Wichtiger Hinweis: Sie können die Vorlage unten kopieren, aber bitte achten Sie darauf, dass die unten genannten Zeilen angepasst wurden. Andernfalls könnte es Probleme mit der Authentifizierung geben!

Folgende Stellen müssen angepasst werden

Parameter	Zeile in Beispiel	Beschreibung
mailSenderAddress	9	E-Mail-Sender-Adresse.
handlerName	22	Dieser wird später in den Notizen der Zertifikatsübersicht zu sehen sein.
accountContact	32	Kontakt-E-Mail-Adresse. Wird von Let's Encrypt benötigt und ist immer anzugeben.
addDomain	55	Die öffentliche Adresse von Lobster_data.

Optional

Parameter	Zeile in Beispiel	Beschreibung
certbotURL	31	Hier kann auch die Staging Environment mit acme://letsencrypt.org/staging angegeben werden. Dies hat den Vorteil, dass es bei zu vielen fehlgeschlagenen Authorization Requests keine Wartezeit gibt. Mehr Informationen dazu finden Sie unter https://letsencrypt.org/docs/staging-environment.

./etc/cex.xml

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC
 "-//Lobster//DTD Configure 1.0//EN"
 "http://www.lobster.de/dtd/configure_1_3.dtd">
<Configure class="com.ebd.hub.services.certexchange.CertificateExchangeService">
 
    <!-- Name of the DB alias to be used for internal data -->
    <Set name="dBAlias">hub</Set>
       <Set name="mailSenderAddress">mail@example.com</Set> 
    <!--
        Certbot Handler configuration for the management of certificates
        that should be signed by an ACME supporting CA, e.g. Let's Encrypt
    -->
    <!-- Change NoCall to Call (don't forget the </NoCall> to enable this -->
    <Call name="addCertbotHandler">
        <Arg><New class="com.ebd.hub.services.certexchange.CertbotHandler">
            <!--
                Name of the handler. Certificates handled by this handler
                will have the name in the keystore notes and can be used
                as search term in TLS-configurations
            -->
            <Set name="handlerName">example.com</Set>
            <!--
                Used as contact for ACME-server account registrations
            -->
            <!--
                The URL of the ACME endpoint. The URL in this sample
                is the staging server, the URL of the production
                server is acme://letsencrypt.org
            -->
            <Set name="certbotURL">acme://letsencrypt.org/</Set>
            <Set name="accountContact">mailto:mail@example.com</Set>
            <!--
                Adds a certificate algorithm to be handled. This will
                lead to the creation of a keypair and finally a
                CA-signed certificate.
            -->
            <Call name="addCertificateAlgorithm">
                <!-- the non-EC algorithm -->
                <Arg>RSA</Arg>
                <!-- key size in bits -->
                <Arg type="int">2048</Arg>
            </Call>
            <Call name="addCertificateAlgorithm">
                <!-- the EC algorithm -->
                <Arg>ECDSA</Arg>
                <!-- the curve name -->
                <Arg type="String">secp256r1</Arg>
            </Call>
            <!--
                Adds a domain the certificate should contain as common name
                or alternate subject name.
            -->
            <Call name="addDomain">
                <Arg>example.com</Arg>
            </Call>           
            <!--
                Number of days a certificate should be valid. This is part
                of the request to the CA and its support is CA-dependent. It
                might be ignored or denied, leading to an error. In that case
                setting it to 0 will omit adding it to the request
            -->
            <Set name="requestedCertificateValidityDays">0</Set>
            <!--
                (change NoSet to Set to activate this setting)
                Number of days before expiry a renewal request should be
                sent to the CA
            -->
            <Set name="daysBeforeExpireRefresh">10</Set>
        </New></Arg>
    </Call>
 
</Configure>

HTTPS Listener aktivieren/Zertifikat angeben

Wurde Lobster_data neu gestartet, werden nach ein paar Minuten die neu generierten Zertifikate in der Zertifikatsübersicht (eigene Zertifikate) angezeigt. Diese sind mit einer Notiz, dem Handler Name, gekennzeichnet.

Um letztendlich das neue Let's-Encrypt-Zertifikat zu verwenden, müssen Sie den HTTPS-Listener aktivieren und die Konfigurationsdatei ./etc/hub.xml anpassen, siehe folgendes Beispiel:

images/download/attachments/119251606/1377.png

Wichtiger Hinweis: Es kann sowohl der CN (Common Name), als auch das ksnote-Kürzel verwendet werden. Letzteres fungiert als eine Art Alias und verwendet die Zertifikats-Notiz für eine eindeutige Zuordnung.

Verwendung auf DMZ-Server

Da ein DMZ-Server in den meisten Fällen die Schnittstelle nach außen bzw. von außen nach innen ist, muss der Certbot dort installiert werden. Zusätzlich zu den Standard-Änderungen der Konfigurationsdateien ./etc/factory.xml, ./etc/cex.xml und ./etc/hub.xml (wie oben beschrieben), muss folgendes angepasst werden.

./etc/cex.xml: Hier muss für den Parameter dbAlias der Wert dmzcommauth eingetragen werden.

images/download/attachments/119251606/1397.png

./etc/auth_dmz.xml: Der Parameter <Set name="localDbFile">dmz/hsql/cacheHsql</Set> darf nicht aktiv und muss auskommentiert sein.

Error Handling

Treten Fehler auf, findet man diese in den folgenden Logs.

./logs/console.txt
Startet Lobster_data nicht mehr, liegt dies meist an fehlerhaften Konfigurationsdateien. Bitte die Konfigurationsdateien ./etc/cex.xml, ./etc/hub.xml und ./etc/factory.xml überprüfen.
./logs/services/message.log
Um die Ergebnisse einzugrenzen, kann nach CERTBOTHANDLER gesucht werden. Das liefert Ihnen eine grobe Übersicht, ob ein CSR (Certificate Signing Request) erfolgreich war.
./logs/services/error.log
Schlägt die Authentifizierung fehl, ist dies hier zu erkennen.