Matrix Synapse-Verbundfehler „SSL-Zertifikatprüfung fehlgeschlagen“ beheben

Ein häufiger Fehler in Matrix Synapse sieht trügerisch einfach aus: Lokale Clients können sich anmelden, Ihr Reverse-Proxy ist online und Synapse selbst scheint in Ordnung zu sein, dennoch können entfernte Homeserver keine Verbindung zu Ihnen herstellen. Die Protokolle auf einer Seite können Meldungen wie „“ certificate verify failed, hostname mismatch„“ unable to get local issuer certificate, „“ oder einen allgemeinen Fehler bei der Föderationsanfrage aufgrund der TLS-Verifizierung enthalten.

Am schnellsten lässt sich das Problem beheben, indem Sie den genauen Hostnamen und Port testen, zu dem die Matrix-Verbundermittlung aufgelöst wird, und anschließend das fehlerhafte Zertifikat, die Zertifikatskette oder den Ermittlungspfad korrigieren. Deaktivieren Sie nicht zunächst die Zertifikatsprüfung. Der Server-zu-Server-Verkehr von Matrix erfolgt über HTTPS, und die Matrix-Spezifikation verlangt, dass das Ziel ein von einer vertrauenswürdigen Zertifizierungsstelle signiertes Zertifikat vorlegt. Synapse aktiviert die ausgehende Verbundzertifikatsprüfung standardmäßig. Weitere Informationen finden Sie in der Matrix-Server-zu-Server-API-Spezifikation und der aktuellen Synapse-Konfigurationsdokumentation .

1. Ermitteln Sie, welchen Hostnamen die Föderation tatsächlich validiert.

Bevor Sie Änderungen an Nginx, Caddy, Synapse oder DNS vornehmen, ermitteln Sie den von Matrix erwarteten Zertifikatsnamen. Die Antwort hängt von Ihrer server_nameKonfiguration und der Servererkennung ab.

Wenn Ihr Matrix-Servername lautet example.comund Sie die Föderation nicht delegieren, versuchen andere Homeserver normalerweise, den mit diesem Namen verknüpften Föderationsdienst zu erreichen, üblicherweise über TCP 8448. Wenn Sie den Hostnamen verwenden https://example.com/.well-known/matrix/server, kann der m.serverWert die Föderation an einen anderen Hostnamen wie beispielsweise matrix.example.com:443delegieren. In diesem Fall ist der delegierte Hostname Teil des TLS-Validierungspfads. Matrix unterstützt auch die SRV-basierte Erkennung, die Synapse-Dokumentation empfiehlt jedoch für typische Bereitstellungen die Delegierung, da diese einfacher zu verstehen und korrekt zu konfigurieren ist. Das autoritative Verhalten ist in der Matrix-Spezifikation unter Servererkennung und in der Synapse-Föderationsdelegierung unter Synapse.well-known dokumentiert .

curl -fsS https://example.com/.well-known/matrix/server

Eine delegierte Antwort könnte folgendermaßen aussehen:

{
  "m.server": "matrix.example.com:443"
}

Wenn die Datei fehlt oder ungültig ist, gehen Sie nicht automatisch davon aus, dass dies der TLS-Fehler ist. Matrix verfügt über alternative Erkennungsregeln. Wichtig ist, den Hostnamen und Port zu kennen, mit dem ein Remote-Server letztendlich kommuniziert.

2. Reproduzieren Sie den Zertifikatsverifizierungsfehler mit OpenSSL.

Sobald Sie den erwarteten Föderationsendpunkt kennen, testen Sie ihn direkt mit SNI und Hostnamenverifizierung. Dadurch lässt sich ein TLS-Identitätsproblem von einem Problem der Synapse-Anwendung unterscheiden.

openssl s_client   -connect example.com:8448   -servername example.com   -verify_hostname example.com   -showcerts </dev/null

Ändern Sie bei einem delegierten Host auf Port 443 sowohl das Verbindungsziel als auch den erwarteten Hostnamen:

openssl s_client   -connect matrix.example.com:443   -servername matrix.example.com   -verify_hostname matrix.example.com   -showcerts </dev/null

Konzentrieren Sie sich auf das endgültige Verifizierungsergebnis und die alternativen Zertifikatssubjektnamen. Eine Verbindung kann auf TCP- und TLS-Protokollebene erfolgreich sein, während die Identitätsprüfung dennoch fehlschlägt. Daher reicht die Aussage „Der Port ist geöffnet“ nicht aus.

Was die häufigsten OpenSSL-Fehler in der Regel bedeuten

• Hostname-Konflikt: Der Reverse-Proxy hat ein Zertifikat für einen anderen Hostnamen bereitgestellt, oder Ihr Discovery-Eintrag leitet die Föderation an einen Hostnamen weiter, der nicht vom Zertifikat abgedeckt wird.
• Das lokale Ausstellerzertifikat konnte nicht abgerufen werden / das erste Zertifikat konnte nicht verifiziert werden: Auf dem Server fehlt häufig ein Zwischenzertifikat einer Zertifizierungsstelle in der Zertifikatskette, oder der Truststore des Clients vertraut der ausstellenden Zertifizierungsstelle nicht.
• Das Zertifikat ist abgelaufen / noch nicht gültig: Erneuern Sie das Zertifikat und überprüfen Sie außerdem die Systemuhr sowohl auf dem Server als auch auf jedem streng kontrollierten privaten Verbundclient.
• Selbstsignierte Zertifikate werden von öffentlichen Föderationen in der Regel abgelehnt. Verwenden Sie für eine private Föderation eine private Zertifizierungsstelle und konfigurieren Sie die Vertrauensstellung explizit, anstatt die Überprüfung global zu deaktivieren.

3. Beheben Sie einen Hostnamenkonflikt am Reverse-Proxy.

Ein Hostnamenkonflikt tritt besonders häufig auf, wenn die Clientseite und der Verbundendpunkt unterschiedliche virtuelle Hosts verwenden. Beispielsweise example.comkann eine Website auf einem virtuellen Host gehostet werden, während matrix.example.comSynapse als Proxy fungiert. Wenn Ihre .well-knownKonfigurationsdatei an einen solchen Host delegiert matrix.example.com:443, muss der TLS-Endpunkt auf diesem Host ein für diesen Host gültiges Zertifikat bereitstellen matrix.example.com.

Bei Nginx sollten Sie den aktiven virtuellen Host überprüfen und nicht nur die Konfigurationsdatei, die Sie verwenden wollten:

sudo nginx -T | less

Überprüfen Sie den server_nameListening-Port und die Zertifikatspfade. Ein typischer TLS-Abschnitt verwendet die vollständige Zertifikatskette:

server {
    listen 443 ssl;
    server_name matrix.example.com;

    ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;

    location /_matrix {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

Erst nach erfolgreichem Konfigurationstest validieren und neu laden:

sudo nginx -t && sudo systemctl reload nginx

Synapse empfiehlt für gängige Bereitstellungen einen Reverse-Proxy und unterscheidet den üblichen Client-Port 443 vom standardmäßigen Verbundport 8448. Die aktuellen Proxy-Anforderungen finden Sie in der offiziellen Synapse-Dokumentation zum Reverse-Proxy .

4. Die vollständige Zertifikatskette bereitstellen.

Ein Endbenutzerzertifikat kann in einem bereits verwendeten Browser korrekt angezeigt werden, aber dennoch auf einem anderen Homeserver fehlschlagen, wenn Ihr Server das erforderliche Zwischenzertifikat nicht sendet. Die Synapse-Dokumentation gibt ausdrücklich an, dass die PEM-Datei die vollständige Zertifikatskette enthalten muss, wenn Synapse selbst mit einem Zertifikat konfiguriert ist; mit Certbot bedeutet dies, fullchain.pemanstelle von nur einer einzigen Datei die vollständige Zertifikatskette zu verwenden cert.pem.

Dasselbe Prinzip gilt, wenn TLS bei Nginx, Caddy, HAProxy oder einem anderen Proxy terminiert: Konfigurieren Sie diesen Proxy so, dass er die korrekte vollständige Kette darstellt. Überprüfen Sie, was tatsächlich ausgeliefert wird, nicht nur, was auf der Festplatte vorhanden ist.

openssl s_client   -connect matrix.example.com:443   -servername matrix.example.com   -showcerts </dev/null

Sie sollten das Endbenutzerzertifikat und anschließend das/die benötigte(n) Zwischenzertifikat(e) sehen. Die Stammzertifizierungsstelle muss im Allgemeinen nicht vom Server gesendet werden, da Clients Stammzertifizierungsstellen normalerweise bereits über ihren Vertrauensspeicher vertrauen.

5. Überprüfen Sie die DNS- und Matrix-Erkennung auf veraltete oder aufgeteilte Routing-Informationen.

Wenn das Zertifikat auf einem Rechner korrekt ist, die Remote-Federation aber ein anderes Zertifikat meldet, leitet das DNS möglicherweise einige Clients auf andere Server um. Überprüfen Sie sowohl IPv4- als auch IPv6-Einträge und beachten Sie, dass ein funktionierender A-Eintrag einen veralteten AAAA-Eintrag nicht kompensieren kann, wenn Remote-Heimserver IPv6 bevorzugen.

dig +short A example.com
dig +short AAAA example.com
dig +short A matrix.example.com
dig +short AAAA matrix.example.com

Überprüfen Sie außerdem alle SRV-Einträge der Föderation, die Sie absichtlich verwenden:

dig +short SRV _matrix-fed._tcp.example.com

Wenn Sie kürzlich Änderungen vorgenommen haben .well-known, aktivieren Sie das Caching. Die Matrix-Spezifikation erlaubt es Clients, Discovery-Antworten und sogar fehlgeschlagene Discovery-Versuche für eine gewisse Zeit zwischenzuspeichern. Das bedeutet, dass eine Konfiguration aktuell korrekt sein kann, während ein Remote-Server vorübergehend weiterhin das zuvor ermittelte Routing verwendet.

Sind sowohl A- als auch AAAA-Zertifikate vorhanden, führen Sie gegebenenfalls eine TLS-Prüfung für jede Route durch. Falls ein Load Balancer mehrere Proxy-Knoten vorschaltet, stellen Sie sicher, dass jeder Knoten über dasselbe aktuelle Zertifikat und dieselbe Zertifikatskette verfügt.

6. Behebung des Vertrauensproblems zwischen privaten Zertifizierungsstellen, ohne die öffentliche Föderation zu schwächen

Private Federation ist der wichtigste legitime Anwendungsfall, in dem eine öffentliche Zertifizierungsstelle (CA) ungeeignet sein kann. Synapse bietet federation_custom_ca_listdie Möglichkeit, benutzerdefinierte Zertifizierungsstellen zu verwenden. Die aktuelle Dokumentation weist auf ein wichtiges Verhalten hin: Diese Liste ersetzt die vom Betriebssystem bereitgestellten CA-Zertifikate. Wenn Sie diese Liste also festlegen, geben Sie unbedingt alle für Ihre Bereitstellung erforderlichen Vertrauensstellungen an.

federation_custom_ca_list:
  - /etc/synapse/ca/private-federation-ca.pem

Nach der Änderung der Vertrauenskonfiguration starten Sie Synapse über den Dienstmechanismus Ihrer Installation neu und prüfen Sie die Protokolle auf Zertifikatsfehler. Container-Bereitstellungen erfordern besondere Aufmerksamkeit: Der Host kann einer privaten Zertifizierungsstelle vertrauen, der Synapse-Container jedoch nicht. Stellen Sie sicher, dass die Vertrauensinformationen in den Container eingebunden sind und der konfigurierte Pfad innerhalb des Containers lesbar ist.

Synapse bietet zwar auch die Möglichkeit, federation_certificate_verification_whitelistdie globale federation_verify_certificatesVerifizierung zu deaktivieren, die offizielle Dokumentation beschränkt deren Verwendung jedoch auf Ausnahmefälle. Das globale Deaktivieren der Verifizierung kann den Fehler zwar beheben, das zugrundeliegende Identitätsproblem bleibt aber bestehen. Bei normalen öffentlichen Föderationen sollten Sie stattdessen das Zertifikat oder das Routing reparieren.

7. Überprüfen Sie die Reparatur zuerst auf der TLS-Ebene.

Nach den vorgenommenen Änderungen muss der zuvor fehlgeschlagene OpenSSL-Befehl erneut ausgeführt werden. Ziel ist eine erfolgreiche Hostnamen- und Kettenverifizierung für den Endpunkt, zu dem die Matrix-Erkennung aufgelöst wird.

Senden Sie anschließend eine HTTPS-Anfrage an einen Verbundendpunkt. Für einen direkten Endpunkt auf Port 8448:

curl -v https://example.com:8448/_matrix/federation/v1/version

Für einen delegierten Endpunkt auf Port 443:

curl -v https://matrix.example.com/_matrix/federation/v1/version

Ein positives TLS-Ergebnis zeigt an, dass das Zertifikat erfolgreich verifiziert wurde. Der Matrix-Endpunkt sollte dann eine HTTP-Antwort vom Homeserver oder Proxy-Pfad zurückgeben, anstatt bei der Zertifikatsvalidierung einen Fehler auszugeben. Der Versionsendpunkt selbst ist für Erreichbarkeitstests nützlich; er beweist jedoch nicht, dass jeder Raum oder Remote-Server korrekt mit der Föderation funktioniert.

8. Überprüfen Sie die Synapse-Protokolle und unterscheiden Sie TLS-Fehler von Fehlern der übergeordneten Föderation.

Wenn die TLS-Verifizierung nun erfolgreich ist, die Föderation aber weiterhin fehlschlägt, gehen Sie nicht länger von einem Zertifikatsproblem aus. Überprüfen Sie stattdessen die Synapse-Protokolle auf DNS-Fehler, Verbindungstimeouts, HTTP-Statusfehler, Probleme mit dem Signaturschlüssel, Autorisierungsfehler oder Verzögerungen des Remote-Servers.

Bei Installationen, die auf systemd basieren, ist ein üblicher Ausgangspunkt:

journalctl -u matrix-synapse -n 200 --no-pager

Verwenden Sie für Docker die Containerprotokolle Ihres Synapse-Dienstes. Suchen Sie nach Informationen zum Zeitpunkt eines aktuellen Verbindungsversuchs, anstatt sich auf alte Zertifikatsmeldungen zu verlassen, die möglicherweise nicht mehr relevant sind.

Schnellentscheidungstabelle

Woran man erkennt, dass das Problem wirklich behoben ist

Verwenden Sie „Der Dienst wurde fehlerfrei neu gestartet“ nicht als Erfolgskriterium. Eine zuverlässige Reparatur weist drei erkennbare Anzeichen auf: Der exakte Hostname des Verbunddienstes besteht die Hostnamenprüfung, die bereitgestellte Kette wird von einer vertrauenswürdigen Zertifizierungsstelle validiert, und eine neue HTTPS-Anfrage an den Verbunddienst erreicht Synapse ohne TLS-Verifizierungsausnahme.

Wenn nach diesen Prüfungen nur noch ein Remote-Homeserver ausfällt, sollten Sie Caching, den Truststore dieses Remoteservers oder einen endpunktspezifischen Netzwerkpfad in Betracht ziehen. Falls mehrere unabhängige öffentliche Homeserver auf dieselbe Weise ausfallen, überprüfen Sie zunächst Ihr eigenes Zertifikat, die IPv6-Route, die Load-Balancer-Knoten und die Discovery-Konfiguration.

Für Produktionssysteme sollte die Zertifikatsprüfung aktiviert bleiben und die Zertifikatserneuerung nachvollziehbar sein. Die dauerhafte Lösung besteht nicht darin, die Prüfung zu unterdrücken, sondern sicherzustellen, dass Matrix Discovery, DNS, SNI, der Reverse-Proxy und die Zertifikatskette denselben Verbundendpunkt beschreiben.