What is Let's Encrypt?

To be able to provide access to Lobster_data via HTTPS, you need a certificate. See section Adding an HTTPS Listener.

Let’s Encrypt (→ documentation) is a free certificate authority (CA) through which Lobster_data can automatically obtain such certificates. These are then also automatically renewed when they expire.

Lobster_data uses the ACME protocol and the Certbot client internally for this purpose. The corresponding components are included in the standard and only need to be configured as described below.

Preconditions

The CertificateExchangeService must be active (./etc/factory.xml, see there).
Configuration file ./etc/cex.xml must be adjusted (see below).
Lobster_data must be accessible from the outside (port 80 and 443 must be open).
forceSSL must not be active, otherwise no certificate can be generated! Two files must be adjusted for this purpose.
- ./etc/webdefault.xml - Surround this part in comments as shown.
- ./etc/startup.xml - Set the parameter to false.

Adjusting Configuration File ./etc/cex.xml

With an installation from Lobster_data 4.5 onwards, there is already a prepared block for adding Certbot handlers in the configuration file. Change the tags NoCall to Call for 'activation' (do not forget the identical change for the closing tag, otherwise the system start will end with an error). Important note: You can copy the template below, but please make sure that the lines mentioned below have been adjusted. Otherwise there could be authentication problems!

The Following Parameters Must Be Adjusted

Parameter	Line in example	Description
mailSenderAddress	9	Email sender address.
handlerName	22	The handler name be visible later in the notes of the certificate overview.
accountContact	32	Contact email address. Is required by Let's Encrypt and must always be specified.
addDomain	55	The public address of Lobster_data.

Optional

Parameter	Line in example	Description
certbotURL	31	The staging environment can also be specified here with acme://letsencrypt.org/staging. This has the advantage that there is no waiting time if too many authorisation requests fail. You can find more information about this at 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>

Enabling HTTPS Listener/Specifying Certificate

If Lobster_data has been restarted, the newly generated certificates are displayed in the certificate overview (local certificates) after a few minutes. These are marked with a note, the handler name.

To finally use the new Let's Encrypt certificate, you must activate the HTTPS listener and adjust configuration file ./etc/hub.xml. See the following example:

images/download/attachments/119251606/1377.png

Important note: Both the CN (Common Name) and the ksnote prefix can be used. The latter acts as a kind of alias and uses the certificate note as unique reference.

Usage on DMZ Server

Since a DMZ server is in most cases the interface to the outside or from the outside to the inside, Certbot must be installed there. In addition to the standard changes to the ./etc/factory.xml, ./etc/cex.xml, and ./etc/hub.xml configuration files (as described above), the following must be adjusted.

./etc/cex.xml: The parameter dbAlias must have the value dmzcommauth .

images/download/attachments/119251606/1397.png

./etc/auth_dmz.xml: The parameter <Set name="localDbFile">dmz/hsql/cacheHsql</Set> must not be active and must be commented out.

Error Handling

If errors occur, they can be found in the following logs.

./logs/console.txt
If Lobster_data no longer starts, this is usually due to faulty configuration files. Please check the configuration files ./etc/cex.xml, ./etc/hub.xml and ./etc/factory.xml.
./logs/services/message.log
To narrow down the results, you can search for CERTBOTHANDLER. This will give you a rough overview of whether a CSR (Certificate Signing Request) was successful.
./logs/services/error.log
If the authentication fails, this can be seen here.