Jadice Server REST-Schnittstelle mit TLS absichern

Owned by Simon Welsch
Last updated: März 01, 2022

Step-by-step guide

Um die REST-Schnittstelle von jadice server über TLS abzusichern müssen drei Dinge angepasst werden.

  1. Der embedded jetty-Server, den jadice server mitbringt, muss so konfiguriert werden, dass dieser die für die Verschlüsselung benötigten Keystores kennt. Dazu erstellen Sie unter server-config/application die Datei jetty-tls.xml mit diesem Inhalt:

    jetty-tls.xml
    <beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:http="http://cxf.apache.org/transports/http/configuration"
    xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration"
    xmlns:sec="http://cxf.apache.org/configuration/security" xmlns:cxf="http://cxf.apache.org/core"
    xsi:schemaLocation="
    http://www.springframework.org/schema/beans                  https://www.springframework.org/schema/beans/spring-beans-4.0.xsd
    http://cxf.apache.org/configuration/security                 https://cxf.apache.org/schemas/configuration/security.xsd
    http://cxf.apache.org/transports/http/configuration            https://cxf.apache.org/schemas/configuration/http-conf.xsd
    http://cxf.apache.org/transports/http-jetty/configuration      https://cxf.apache.org/schemas/configuration/http-jetty.xsd
    http://cxf.apache.org/core                                     https://cxf.apache.org/schemas/core.xsd">
    <cxf:bus />
    <httpj:engine-factory bus="cxf">
        <httpj:engine port="9001">
            <httpj:tlsServerParameters>
                <sec:keyManagers keyPassword="password">
                    <sec:keyStore
                        file="C:\path\to\your\keystore.jks"
                        password="password" type="JKS" />
                </sec:keyManagers>
                <sec:trustManagers>
                    <sec:keyStore
                        file="C:\path\to\your\keystore.jks"
                        password="password" type="JKS" />
                </sec:trustManagers>
                <sec:clientAuthentication want="true"
                    required="false" />
            </httpj:tlsServerParameters>
            <httpj:handlers>
                <bean class="org.eclipse.jetty.server.handler.DefaultHandler" />
            </httpj:handlers>
        </httpj:engine>
    </httpj:engine-factory>
</beans>

    Beachten Sie bitte, dass für den Keystore der absolute Pfad im Dateisystem angegeben werden muss.

  2. Um die oben erzeugte Konfigurationsdatei in jadice server einzubinden muss in der Datei server-config/application/server.xml folgende Zeile ergänzt werden - und zwar nach dem Import der rest.xml:

    Ergänzung in server.xml
    <import resource="jetty-tls.xml"/>


  3. Die Addresse und den Port in der Datei server-config/application/rest.xml entsprechend der Werte im jetty-tls.xml anpassen

    Anpassung in rest.xml
    <value>https://${jadice.server.hostname}:9001</value>
<value>https://localhost:9001</value>
...
<jaxrs:server id="restEndpoint" address="https://${jadice.server.hostname}:9001/jadiceServer">

Passwörter absichern 

Im obigen Beispiel stehen die Passwörter im Klartext in der Konfigurationsdatei. Dies ist natürlich für Produktionsumgebungen nicht zu empfehlen. Jetty bietet mehrere Optionen Passwörter abzusichern, für Keystore Passwörter kommt aber nur obfuscation infrage (siehe Secure Password Obfuscation). Zusammen mit der Verwendung von Umgebungsvariablen sollte dieses Verfahren dennoch genug Sicherheit bieten.

Beispiel mit dem Passwort "password":

  1. Password mittels jetty-util.jar "verschleiern".

    obfuscate password
    # im Root Verzeichnis der jadice server Installation ausführen - oder alternativ ein anderes jetty-util.jar verwenden 
$ java -cp server-lib/jetty-util-9.4.43.v20210629.jar org.eclipse.jetty.util.security.Password password 
2022-02-21 16:14:52.735:INFO::main: Logging initialized @175ms to org.eclipse.jetty.util.log.StdErrLog
password
OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v
MD5:5f4dcc3b5aa765d61d8327deb882cf99

  2. Umgebungsvariable anlegen. Hierzu das Ergebnis von Schritt 1 inklusive OBF: verwenden.

    create environment variable
    # unter linux
$ export JS_JETTY_KEYSTORE_PASSWORD=OBF:1z0f1vu91vv11z0f
# unter Windows
# z.B. über die GUI: Systemsteuerung\System und Sicherheit\System > Erweiterte Systemeinstellungen > Umgebungsvariablen > Systemvariablen "Neu"

  3. Passwort in der Datei  server-config/application/jetty-tls.xml durch Platzhalter ersetzen. 

    <beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:http="http://cxf.apache.org/transports/http/configuration"
    xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration"
    xmlns:sec="http://cxf.apache.org/configuration/security" xmlns:cxf="http://cxf.apache.org/core"
    xsi:schemaLocation="
    http://www.springframework.org/schema/beans                  https://www.springframework.org/schema/beans/spring-beans-4.0.xsd
    http://cxf.apache.org/configuration/security                 https://cxf.apache.org/schemas/configuration/security.xsd
    http://cxf.apache.org/transports/http/configuration            https://cxf.apache.org/schemas/configuration/http-conf.xsd
    http://cxf.apache.org/transports/http-jetty/configuration      https://cxf.apache.org/schemas/configuration/http-jetty.xsd
    http://cxf.apache.org/core                                     https://cxf.apache.org/schemas/core.xsd">
    <cxf:bus />
    <httpj:engine-factory bus="cxf">
        <httpj:engine port="9001">
            <httpj:tlsServerParameters>
                <sec:keyManagers keyPassword="${JS_JETTY_KEYSTORE_PASSWORD}">
                    <sec:keyStore
                        file="C:\path\to\your\keystore.jks"
                        password="${JS_JETTY_KEYSTORE_PASSWORD}" type="JKS" />
                </sec:keyManagers>
                <sec:trustManagers>
                    <sec:keyStore
                        file="C:\path\to\your\keystore.jks"
                        password="${JS_JETTY_KEYSTORE_PASSWORD}" type="JKS" />
                </sec:trustManagers>
                <sec:clientAuthentication want="true"
                    required="false" />
            </httpj:tlsServerParameters>
            <httpj:handlers>
                <bean class="org.eclipse.jetty.server.handler.DefaultHandler" />
            </httpj:handlers>
        </httpj:engine>
    </httpj:engine-factory>
</beans>

Weitere Informationen

Informationen zu den Einstellungen können Sie der Dokumentation von Apache CXF Jetty entnehmen.

Treten Probleme bei der Aktivierung von TLS auf, hilft die System-Property -Djavax.net.debug=all oft weiter, um das Problem einzugrenzen. Diese Einstellung kann in der Datei wrapper/wrapper.conf eingetragen werden. Oracle bietet einen ausführlichen Artikel zum Thema "Debugging SSL/TLS Connections" an.