Beta: TLS/SSL-Zertifikate für enaio®

enaio® • 10.10 »

Die Dokumentation ist zur Zeit noch in Arbeit und wird zeitnah vervollständigt. Der aktuelle Stand kann nur als Überblick über die Konfigurationen dienen. Eine vollständige SSL-Verschlüsselung für alle Komponenten des enaio®-Systems kann mit diesem Stand nicht erreicht werden.
Falls Sie Fragen haben oder im Projekt Test- oder Entwicklungssysteme sichern wollen, dann wenden Sie sich bitte an den Support von OPTIMAL SYSTEMS.

SSL-Zertifikat für enaio® server

Falls Sie ein SSL-Zertifikat für enaio® server einbinden wollen, dann müssen Sie folgende Konfigurationsdateien anpassen:

  • osssl.cfg

    Diese Konfigurationsdatei muss für enaio® server, enaio® client, für die administrativen Clients und für Komponenten wie enaio® capture angepasst werden.

  • enaio® gateway: application-prod.yml

  • enaio® service-manager: application-blue.yml

  • enaio® documentviewer: config.properties

  • enaio® appconnector: osrest.properties

osssl.cfg

Die Konfigurationsdatei osssl.cfg wird in das Installationsverzeichnis von enaio® server und in die Installationsverzeichnisse aller Clients installiert. Diese Dateien müssen angepasst werden.

osssl.cfg von enaio® server

Server: osssl.cfg

 Anpassung 
[osclient_ssl_section]
# Certificate = your-path/client_certificate.pem
VerifyMode = Peer
 
[osclient_ssl_section]
Certificate = D:/server/tls/certificate.pem
VerifyMode = Peer

Pfad zur Zertifikatsdatei *.pem angeben.

Der VerifyMode kann zum Testen deaktiviert werden.

 
[osserver_ssl_section]
...
 
[osserver_ssl_section]
Certificate = D:/server/tls/certificate.pem
...

Pfad zur Zertifikatsdatei *.pem angeben.

 
[osserver_private_section]
# pwd =
 
[osserver_private_section]
pwd = secretpw

Passwort angeben.

Jeder enaio® server benötigt ein Zertifikat.

osssl.cfg der Clients

Clients: osssl.cfg

 Anpassung 
[osclient_ssl_section]
# Certificate = your-path/client_certificate.pem
VerifyMode = Peer
 
[osclient_ssl_section]
Certificate = D:/clients/tls/certificate.pem
VerifyMode = Peer

Pfad zur Zertifikatsdatei *.pem angeben.

Der VerifyMode kann zum Testen deaktiviert werden.

 
[osserver_ssl_section]
...
 
[osserver_ssl_section]
Certificate = D:/clients/tls/certificate.pem
...

Pfad zur Zertifikatsdatei *.pem angeben.

application-prod.yml von enaio® gateway

Datei application-prod.yml aus dem Verzeichnis \Services\gateway\apps\os_gateway\config\: ergänzen Sie folgende Zeile:

ecm.server.useCustomSSLcontex: true

application-blue.yml von enaio® service-manager

Datei application-blue.yml aus dem Verzeichnis \service-manager\config\: ergänzen Sie folgende Zeile:

enaio.dms.useCustomSSLcontext: true

config.properties von enaio® documentviewer

Datei config.properties aus dem Verzeichnis \webapps\osrenditioncache\WEB-INF\classes\config von enaio® documentviewer: ergänzen Sie folgende Zeile:

session.useCustomSSLcontext=true

osrest.properties von enaio® appconnector

Datei osrest.properties aus dem Verzeichnis \configuration von enaio® appconnector: ergänzen Sie folgende Zeile:

useCustomSSLcontext=true

SSL-Zertifikat für enaio® gateway

Die Zertifikatseinbindung und Datenübertragung per HTTPS richten Sie wie folgt ein:

  1. Binden Sie das Zertifikat in die Zertifikatsverwaltung ein.

Das Einbinden eines Zertifikats kann über die Eingabeaufforderung erfolgen, alternativ über Tools wie den KeyStore Explorer.

Eingabeaufforderung:

<Path_service-manager>\jdk\bin\keytool ^
  -importkeystore -srckeystore <Path_gateway>/keystore/myKeystore.p12 ^
  -srcstorepass optimal -destkeystore <path_gateway>\jdk\lib\security\cacerts ^
  -srcstoretype PKCS12 -deststoretype JKS ^
  -deststorepass changeit

Anpassungen:
-importkeystore -srckeystore Pfad zum Zertifikat und Dateiname
-srcstorepass Passwort des Zertifikats
-deststorepass

Passwort der Zertifikatsverwaltung

Default: changeit

  1. Setzen Sie den Standardport des Anwendungsservers auf den HTTPS-Standardport.

Dazu starten Sie den Anwendungsmanager enaio blue gatewayw.exe im Verzeichnis …\services\OS_Gateway\bin und setzen auf der Registerkarte Startup den Parameter –server.port=443.

  1. Aktivieren Sie die Datenübertragung per HTTPS in der Konfigurationsdatei application-prod.yml, die sich im Verzeichnis …\services\OS_Gateway\apps\os_gateway\config\ befindet. Sie kann mit jedem beliebigen Editor bearbeitet werden.
  1. Fügen Sie folgenden Abschnitt hinzu:

    2. https: {
    enabled: true,
    keyAlias: 'enaio',
    keystorePass: 'optimal',
    keystoreFile: '<path_gateway>/keystore/myKeystore.p12',
    keystoreType: PKCS12,
    sslProtocol: 'TLS',
    sslEnabledProtocols: 'TLSv1.2,TLSv1.3'
    }

    Parameter:

    Parameter

    Beschreibung
    enabled

    Aktiviert die Datenübertragung per HTTPS.
    keyAlias:

    Name für den Keystore
    keystorePass

    Passwort für den Keystore-Benutzer
    keystoreFile

    Verzeichnis, in dem sich die Keystore-Datei befindet.

    Werte mit Sonderzeichen benötigen einfache Anführungszeichen.
  1. Speichern und schließen Sie die Datei.

Die Datenübertragung per HTTPS ist eingerichtet.

Wenn Sie ein selbst signiertes SSL-Zertifikat in enaio® gateway verwenden, dann müssen Sie auf allen Clients dessen Root-CA Zertifikat in die vertrauenswürdigen Stammzertifizierungsstellen importieren. Ansonsten wird das Zertifikat von allen Clients als nicht vertrauenswürdig erachtet und ein Verbindungsaufbau, beispielsweise aus enaio® webclient, schlägt fehl. Selbst signierte Zertifikate sind in der Regel für Produktivsysteme nicht empfohlen.

SSL-Zertifikat für enaio® service-manager

Wenn Sie ein SSL-Zertifikat für die Microservices einbinden wollen, dann legen Sie eine neue Profildatei an. In diese Profildatei binden Sie das Zertifikat ein und aktivieren HTTPS. Dort wird ebenfalls der Eureka-Client konfiguriert, so dass sich ein Service beim Eureka-Server registriert und seine Endpunkte veröffentlicht.

Das neue Profil wird dann über die Konfigurationsdatei servicewatcher-sw.yml den Services zugeordnet.

Für den Service 'argus' als Konfigurations-Server wird diese Konfiguration ebenfalls in der Konfigurationsdatei servicewatcher-sw.yml benötigt.

Profildatei anlegen

Die Profildatei legen Sie im Verzeichnis \config von enaio® service-manager an. Beispiel: application-ssl.yml

Zertifikat in enaio® service-manager einbinden

server.ssl:
  enabled: true
  key-store: '.../path/keystore/myKeystore.p12'
  key-store-type: PKCS12
  key-store-password: keystorePassword
  key-alias: myAlias
  key-password: keyPassword

Parameter:

enabled true: SSL aktivieren
key-store Pfad zum Zertifikat und Dateiname
key-store-type Zertifikatstyp
key‑store‑password Keystorepasswort
key-alias Alias
key-password Schlüsselpasswort, falls das Zertifikat entsprechend konfiguriert ist

Zertifikat in die Zertifikatsverwaltung einbinden

Das Einbinden eines Zertifikats kann über die Eingabeaufforderung erfolgen, alternativ über Tools wie den KeyStore Explorer.

Eingabeaufforderung:

  • Führen Sie in der Eingabeaufforderung folgende Befehle aus:

    <Path_service-manager>\jdk\bin\keytool ^
      -importkeystore -srckeystore <Path_service-manager>/keystore/myKeystore.p12 ^
      -srcstorepass optimal -destkeystore <path_service-manager>\jdk\jre\lib\security\cacerts ^
      -srcstoretype PKCS12 -deststoretype JKS ^
      -deststorepass changeit
    Anpassungen:
    -importkeystore -srckeystore Pfad zum Zertifikat und Dateiname
    -srcstorepass Passwort des Zertifikats
    -deststorepass

    Passwort der Zertifikatsverwaltung

    Default: changeit

Eureka-Client konfigurieren

Zertifikate können auf den Hostnamen oder die IP-Adresse ausgestellt werden. Die Konfigurationen unterscheiden sich etwas.

Hostname:

eureka.instance:
  hostname: 'hostname'
  non-secure-port-enabled: false
  secure-port-enabled: true
  secure-port: "${server.port}"
  prefer-ip-address: false
  homePageUrl: "https://${eureka.instance.hostname}:${eureka.instance.secure-port}/"
  healthCheckUrl: "https://${eureka.instance.hostname}:${eureka.instance.secure-port}/manage/health"
  statusPageUrl: "https://${eureka.instance.hostname}:${eureka.instance.secure-port}/manage/info"
  secureHealthCheckUrl: "https://${eureka.instance.hostname}:${eureka.instance.secure-port}/manage/health"

Parameter, die angepasst werden:

hostname

Hostname als qualifizierter Name

IP-Adresse:

eureka.instance:
  preferIpAddress: true
  ipAddress: 10.1.24.222
  non-secure-port-enabled: false
  secure-port-enabled: true
  secure-port: "${server.port}"
  homePageUrl: "https://${eureka.instance.ipAddress}:${eureka.instance.secure-port}/"
  healthCheckUrl: "https://${eureka.instance.ipAddress}:${eureka.instance.secure-port}/manage/health"
  statusPageUrl: "https://${eureka.instance.ipAddress}:${eureka.instance.secure-port}/manage/info"
  secureHealthCheckUrl: "https://${eureka.instance.ipAddress}:${eureka.instance.secure-port}/manage/health"

Parameter, die angepasst werden:

ipAddress IP-Adresse

Profil zuordnen

Das Profil der Datei application-ssl.yml wird in der Konfigurationsdatei servicewatcher-sw.yml aus dem Verzeichnis \config von enaio® service-manager den gewünschten Microservices zugeordnet:

Beispiel:

applications:
- name: adminservice
  type: microservice
  profiles: prod,cloud,ssl
  instances: 1
  memory: 128M
  port: 7273
  path: ${appBase}/adminservice/adminservice-app.jar

Parameter 'profiles' ergänzen: profiles: prod,cloud,ssl

servicewatcher-sw.yml erweitern

Für den Service 'argus' als Konfigurations-Server wird die Konfiguration ‑ Zertifikat einbinden und Eureka-Client konfigurieren ‑ ebenfalls in die Konfigurationsdatei servicewatcher-sw.yml benötigt.

Beispiel für ein Hostnamen-Zertifikat:

eureka.instance:
  hostname: 'hostname'
  non-secure-port-enabled: false
  secure-port-enabled: true
  secure-port: "${server.port}"
  prefer-ip-address: false
  homePageUrl: "https://${eureka.instance.hostname}:${eureka.instance.secure-port}/"
  healthCheckUrl: "https://${eureka.instance.hostname}:${eureka.instance.secure-port}/manage/health"
  statusPageUrl: "https://${eureka.instance.hostname}:${eureka.instance.secure-port}/manage/info"
  secureHealthCheckUrl: "https://${eureka.instance.hostname}:${eureka.instance.secure-port}/manage/health"
 server.ssl:
  enabled: true
  key-store: '.../path/keystore/myKeystore.p12'
  key-store-type: PKCS12
  key-store-password: keystorePassword
  key-alias: myAlias
  key-password: keyPassword

Beispiel für ein IP-Adressen-Zertifikat:

eureka.instance:
  preferIpAddress: true
  ipAddress: 10.1.24.222
  non-secure-port-enabled: false
  secure-port-enabled: true
  secure-port: "${server.port}"
  homePageUrl: "https://${eureka.instance.ipAddress}:${eureka.instance.secure-port}/"
  healthCheckUrl: "https://${eureka.instance.ipAddress}:${eureka.instance.secure-port}/manage/health"
  statusPageUrl: "https://${eureka.instance.ipAddress}:${eureka.instance.secure-port}/manage/info"
  secureHealthCheckUrl: "https://${eureka.instance.ipAddress}:${eureka.instance.secure-port}/manage/health"
 server.ssl:
  enabled: true
  key-store: '.../path/keystore/myKeystore.p12'
  key-store-type: PKCS12
  key-store-password: keystorePassword
  key-alias: myAlias
  key-password: keyPassword

Zusätzlich muss der Parameter SPRING_CLOUD_CONFIG_URI in der Konfigurationsdatei servicewatcher-sw.yml wie folgt angepasst werden:

...
globalEnvironment:
  SPRING_CLOUD_CONFIG_URI: https://<hostname/IP-address>:${server.port}${spring.cloud.config.server.prefix}
...

hostname/IP-address: Abhängig vom Zertifikat wird der Hostname (FQDN) oder die IP-Adresse angegeben.

application-cloud.yml erweitern

Falls SSL für den Service 'discovery' aktiv ist, dann muss der Parameter eureka.client.service-url.defaultZone in der Konfigurationsdatei application-cloud.yml aus dem Verzeichnis \config von enaio® service-manager wie folgt angepasst werden:

eureka.client.service-url.defaultZone: https://<hostname/IP-address>:7261/eureka/

hostname/IP-address: Abhängig vom Zertifikat wird der Hostname (FQDN) oder die IP-Adresse angegeben.

Nach den Anpassungen der Konfigurationsdateien muss enaio® service-manager neu gestartet werden.

SSL-Zertifikat für enaio® documentviewer

Falls Sie ein SSL-Zertifikat für enaio® documentviewer einbinden wollen, dann müssen Sie die Konfigurationsdatei server.xml aus dem Installationsverzeichnis \conf\ wie folgt anpassen:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true">
    <SSLHostConfig>
        <Certificate
            certificateKeystoreFile="<path_documentviewer>\keystore.p12"
            type="PKCS12"
            certificateKeyPassword="keypw"
            certificateKeystorePassword="keystorepw"
        />
    </SSLHostConfig>
</Connector>

Der bestehende Connector muss deaktiviert werden.

Parameter, die angegeben werden müssen:

certificateKeystoreFile Pfad zum SSL‑Zertifikat
type Zertifikatstyp
certificateKeyPassword Schlüsselpasswort
certificateKeystorePassword Keystorepasswort

Weitere Anpassungen:

  • Der öffentlichen Schlüssel der Zertifikatskette muss im Java Keystore von enaio® gateway, enaio® documentviewer, enaio® service-manager und enaio® appconnector eingebunden werden.

  • In der Konfigurationsdatei config.properties aus dem Verzeichnis \webapps\osrenditioncache\WEB-INF\classes\config von enaio® documentviewer muss die URL des Parameters rendition.restAdress angepasst werden. Angepasst werden muss https und die Adresse: IP oder Domain Name.
  • Angepasst werden müssen die Service-Endpunkte von enaio® documentviewer in enaio® enterprise-manager. Hier muss der Common Name des Zertifikats eingetragen werden.

Danach müssen enaio® gateway, enaio® documentviewer, enaio® service-manager und enaio® appconnector neu gestartet werden.

SSL-Zertifikat für enaio® appconnector

Falls Sie ein SSL-Zertifikat für enaio® appconnector einbinden wollen, dann müssen Sie die Konfigurationsdatei server.xml aus dem Installationsverzeichnis \conf\ wie folgt anpassen:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true">
    <SSLHostConfig>
        <Certificate
            certificateKeystoreFile="<path_appconnector>\keystore.p12"
            type="PKCS12"
            certificateKeyPassword="keypw"
            certificateKeystorePassword="keystorepw"
        />
    </SSLHostConfig>
</Connector>

Der bestehende Connector muss deaktiviert werden.

Parameter, die angegeben werden müssen:

certificateKeystoreFile Pfad zum SSL‑Zertifikat
type Zertifikatstyp
certificateKeyPassword Schlüsselpasswort
certificateKeystorePassword Keystorepasswort

Weitere Anpassungen:

  • Der öffentlichen Schlüssel der Zertifikatskette muss im Java Keystore von enaio® gateway eingebunden werden.

Danach müssen enaio® gateway und enaio® appconnector neu gestartet werden.