Eigene SSL Zertifikate verwenden

Dieses Kapitel beschreibt, wie du eigenen SSL Zertifikate für eine Schnittstelle definieren kannst. Dabei ersetzt du die internen Zertifikate und Schlüssel mit eigenen, welche beispielsweise durch die Certificate Authority der Firma erstellt und signiert wurden.

In der Konfiguration von Anwendungen welche eigene Zertifikate unterstützen, fügst du ein zusätzliches Modul SSL hinzu, das eines oder mehrere verschiedene Profile enthält. Für jedes dieser Profile legst du einen eindeutigen Bezeichner fest.

Innerhalb der Konfiguration für die Anwendung, findest du einen optionalen Wert sslProfile oder auch nur ssl. Diesen Wert setzt du auf den Bezeichner den du bei dem Profil im SSL Modul gewählt hast.

Schema der Konfiguration

Das folgende Schema zeigt die Struktur der Konfiguration:

Module

SSL

List

profiles

Complex list definition

Value

identifier

String

  • Must not be empty.

  • Maximum length: 64

Value

key

String

  • Must be an existing file.

Value

keyAlgorithm

Optional

String

  • Must be one of this: RSA, EC

Default Value:

RSA

Value

keyPassphrase

Optional

Password

Value

caCertificates

Optional

String

  • Must be an existing file.

Value

localCertificateChain

String

  • Must be an existing file.

Value

peerVerificationEnabled

Optional

Boolean

Default Value:

No

Value

ignoreHostNameMismatch

Optional

Boolean

Default Value:

Yes

Value

acceptedCommonName

Optional

String

  • Must be a valid regular expression.

Default Value:

.*

Die Liste profiles

Mit der Liste profiles definierst du eines oder mehrere SSL profile welche für die Anwendung verwendet werden. Jedes dieser Profile braucht einen eindeutigen Bezeichner, den du mit dem Wert identifier festlegst.

Der Wert identifier

Der Wert identifier legt den eindeutigen Bezeichner für das profil fest. Die maximale Länge des Bezeichners ist 64 Zeichen. Wähle hier einen möglichst kurzen und einfachen Namen für das Profil.

<List name="profiles">
    <ListEntry>
        <Value name="identifier">customRsa</Value>
        ...
    </ListEntry>
</List>

Der Wert key

Mit dem Wert key legst du den absoluten Pfad zu einer PEM codierten Datei mit einem RSA oder EC Schlüssel fest. Um relative Pfade zu verwenden, kannst du beispielsweise den Platzhalter ●thisDirectory● des Konfigurationssystems verwenden.

<List name="profiles">
    <ListEntry>
        ...
        <Value name="key">●thisDirectory●/example-key.pem</Value>
        ...
    </ListEntry>
</List>

Der Wert keyAlgorithm

Der optionale Wert keyAlgorithm wählt, welchen Schlüsseltyp du verwenden möchtest. Du hast dabei die Wahl zwischen den folgenden Werten:

RSA

Ein RSA Schlüssel.

EC

Ein EC Schlüssel.

Lässt du diesen Wert weg, wird RSA als Standartwert verwendet.

<List name="profiles">
    <ListEntry>
        ...
        <Value name="keyAlgorithm">RSA</Value>
        ...
    </ListEntry>
</List>

Der Wert keyPassphrase

Mit dem optionalen Wert keyPassphrase setzt du den Passphrase der für die Verschlüsslung des Schlüssels verwendet wird. Wenn du den Schlüssel ohne Verschlüsslung gespeichert hast, kannst du diesen Wert weglassen.

<List name="profiles">
    <ListEntry>
        ...
        <Value name="keyPassphrase">example</Value>
        ...
    </ListEntry>
</List>

Der Wert caCertificates

Der optionale Wert caCertificates setzt den absoluten Pfad zu einer Datei mit allen Certification Authority Zertifikaten im PEM Format. Lässt du diesen Wert weg, werden keine Certification Authority Zertifikate definiert und verwendet. Bei mehreren Zertifikaten, kopierst du einfach alle PEM Blöcke hintereinander in die Datei.

<List name="profiles">
    <ListEntry>
        ...
        <Value name="caCertificates">●thisDirectory●/example-ca.pem</Value>
        ...
    </ListEntry>
</List>

Der Wert localCertificateChain

Der Wert localCertificateChain setzt den absoluten Pfad zu der Datei mit dem Zertifikat des Profils, passend zu dem Schlüssel, und optionalen Zwischenzertifikaten im PEM Format. Bei mehreren Zertifikaten, kopierst du einfach alle PEM Blöcke hintereinander in die Datei.

Bei mehreren Zertifikaten muss das erste dabei immer das lokale Zertifikat sein.

<List name="profiles">
    <ListEntry>
        ...
        <Value name="localCertificateChain">●thisDirectory●/example-cert.pem</Value>
    </ListEntry>
</List>

Der Wert peerVerificationEnabled

Mit dem optionalen Wert peerVerificationEnabled, kannst du die Überprüfung des Peer-Zertifikat aktivieren. Es wird dann das Zertifikats des Clients der sich mit der Applikation verbindet überprüft.

Lässt du diesen Wert weg, wird das Client Zertifikat nicht überprüft. Wir empfehlen bei einer HTTPS Schnittstelle, diesen Wert wegzulassen oder auf No zu setzen.

<List name="profiles">
    <ListEntry>
        ...
        <Value name="peerVerificationEnabled">Yes</Value>
        ...
    </ListEntry>
</List>

Der Wert ignoreHostNameMismatch

Mit dem optionalen Wert ignoreHostNameMismatch steuerst du, ob der Hostname oder die IP-Adresse mit der im Zertifikat gespeicherten übereinstimmen muss. Setzt du diesen Wert auf Yes, wird eine Abweichung ignoriert. Setzt du ihn auf No, dann muss der Hostnamen oder die IP-Adresse mit der im Zertifikat gespeicherten übereinstimmen, sonst wird eine Verbindung abgelehnt. Lässt du den Wert weg, wird Yes verwendet, damit also Abweichungen ignoriert.

Für die maximale Sicherheit solltest du diesen Wert auf No setzen. Dies setzt jedoch voraus, dass alle Zertifikate korrekt für die jeweiligen Server erzeugt wurden. Wird ein Service auf einen neuen Server verschoben, muss auch ein neues Zertifikat erstellt werden.

Dieser Konfigurationswert wird nur berücksichtigt, wenn die „Peer Verification“ aktiviert ist (siehe Der Wert peerVerificationEnabled). Ist diese deaktiviert, werden alle Zertifikate akzeptiert.

<List name="profiles">
    <ListEntry>
        ...
        <Value name="ignoreHostNameMismatch">No</Value>
        ...
    </ListEntry>
</List>

Der Wert acceptedCommonName

Mit dem optionalen Wert acceptedCommonName definierst du einen Regulären Ausdruck der auf den „Common Name“ im Zertifikat passen muss. Lässt du diesen Wert weg, werden alle gültigen Zertifikate akzeptiert.

In einem Firmenumfeld mit einer eigenen CA kannst du mit diesem Konfigurationswert die Verbindung zu einem Server oder einer Gruppe von Clients weiter absichern. Selbst wenn der Server mit einem gültigen Zertifikat antwortet, welches von der Konfigurierten CA signiert wurde, muss so auch noch der „Common Name“ einem bestimmten Wert entsprechen.

<List name="profiles">
    <ListEntry>
        ...
        <Value name="acceptedCommonName">^my-service(?:1|2|3)\.example\.com$</Value>
        ...
    </ListEntry>
</List>

Beispielkonfiguration

Das folgende Beispiel enthält eine Konfiguration mit einem einzelnen Profil customRsa.

<Module name="SSL">
    <List name="profiles">
        <ListEntry>
            <Value name="identifier">customRsa</Value>
            <Value name="key">●thisDirectory●/example-key.pem</Value>
            <Value name="keyAlgorithm">RSA</Value>
            <Value name="keyPassphrase">example</Value>
            <Value name="localCertificateChain">●thisDirectory●/example-cert.pem</Value>
            <Value name="peerVerificationEnabled">Yes</Value>
            <Value name="ignoreHostNameMismatch">No</Value>
        </ListEntry>
    </List>
</Module>

Ein Beispiel der Schlüsseldatei im PEM Format findest du in dem folgenden Listing. Die Zeilen in der Mitte wurden entfernt, damit das Listing übersichtlich bleibt:

-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIJjjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIC+QGzdvJ30QCAggA
MBQGCCqGSIb3DQMHBAgtdX8xRSZQQgSCCUh+R6jbvbnuyo2pqFgTd/t0ONVSx7Ks
    [... 32 lines removed ...]
QKwWSA+mN5dG2wG4yW2s6ozZ3Xp/4q6SLK22yurYOJ74V1OR6DN8j6fdTvGMyPuF
2fbg9Cii/dn82DTgZBp4oXVXcaS88f5bpE/riFB3V+U6aG7EYoeSkiOCgIUiLFwD
eMw=
-----END ENCRYPTED PRIVATE KEY-----

Eine Zertifikatsdatei im PEM Format sieht ähnlich aus. Auch hier wurden einige Zeilen aus der Mitte entfernt.

-----BEGIN CERTIFICATE-----
MIIFmzCCA4OgAwIBAgIJAPNeQiH5juk4MA0GCSqGSIb3DQEBCwUAMGQxCzAJBgNV
BAYTAkNIMQ0wCwYDVQQIDARCZXJuMQ0wCwYDVQQHDARCZXJuMRUwEwYDVQQKDAxF
    [... 25 lines removed ...]
byIW3EurM+KuD85l2LumKlfdiKXTViVFhfeGYc8TC2YHnudgHDNGUQUyTfhPLZql
W+Xxf5m4ERtTqmLu25ksLhm8o9gdtBSP3gF/DF1W1xRKM2f9kCrnUNs1wXwLaQA=
-----END CERTIFICATE-----