Correction des erreurs de fédération « Échec de la vérification du certificat SSL » de Matrix Synapse

Une panne courante de Matrix Synapse peut paraître d'une simplicité trompeuse : les clients locaux peuvent se connecter, votre proxy inverse est en ligne et Synapse lui-même semble fonctionner correctement, pourtant les serveurs distants ne parviennent pas à se fédérer avec vous. Les journaux d'un côté peuvent contenir des phrases telles que certificate verify failed« [erreur hostname mismatch] », « [ unable to get local issuer certificateerreur] » ou une erreur générique de requête de fédération due à la vérification TLS.

La méthode la plus rapide pour résoudre ce problème consiste à tester le nom d'hôte et le port exacts utilisés par la découverte de fédération Matrix, puis à corriger le certificat, la chaîne ou le chemin de découverte erroné. Ne commencez pas par désactiver la vérification des certificats. Le trafic entre serveurs Matrix utilise le protocole HTTPS, et la spécification Matrix exige que la destination présente un certificat signé par une autorité de certification de confiance. Synapse active également par défaut la vérification des certificats de fédération sortants. Consultez la spécification de l'API serveur-serveur Matrix et la documentation de configuration Synapse .

1. Identifier le nom d'hôte que la fédération valide réellement.

Avant de modifier Nginx, Caddy, Synapse ou le DNS, déterminez le nom du certificat attendu par Matrix. La réponse dépend de votre configuration server_nameet de la découverte des serveurs.

Si le nom de votre serveur Matrix est `/matrix/server` example.comet que vous ne déléguez pas la fédération, les autres serveurs d'accueil tentent généralement d'utiliser le service de fédération associé à ce nom, généralement sur le port TCP 8448. Si vous utilisez `/matrix/server` https://example.com/.well-known/matrix/server, la m.servervaleur `délégue` peut déléguer la fédération à un autre nom d'hôte, tel que ` /matrix/server` matrix.example.com:443. Dans ce cas, le nom d'hôte délégué fait partie du chemin de validation TLS. Matrix prend également en charge la découverte basée sur les SRV, mais la documentation Synapse recommande .well-knownla délégation pour les déploiements classiques, car elle est plus simple à appréhender et à configurer. Le comportement faisant autorité est documenté dans la section « Découverte de serveurs » de la spécification Matrix et dans la section « Délégation de fédération Synapse » .

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

Une réponse déléguée peut ressembler à ceci :

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

Si le fichier est absent ou invalide, ne présumez pas qu'il s'agit là du bug TLS. Matrix dispose de règles de découverte de secours. L'important est de savoir quel nom d'hôte et quel port le serveur distant contactera finalement.

2. Reproduisez l'échec de la vérification du certificat avec OpenSSL.

Une fois le point de terminaison de fédération attendu identifié, testez-le directement avec SNI et la vérification du nom d'hôte. Cela permet de distinguer un problème d'identité TLS d'un problème lié à l'application Synapse.

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

Pour un hôte délégué sur le port 443, modifiez à la fois la cible de connexion et le nom d'hôte attendu :

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

Concentrez-vous sur le résultat final de la vérification et sur les noms alternatifs du sujet du certificat. Une connexion peut réussir au niveau des protocoles TCP et TLS tout en échouant à la vérification d'identité. C'est pourquoi « le port est ouvert » ne suffit pas.

Que signifient généralement les erreurs OpenSSL les plus courantes ?

• Incompatibilité de nom d'hôte : le proxy inverse a servi un certificat pour un nom d'hôte différent, ou votre enregistrement de découverte dirige la fédération vers un nom d'hôte non couvert par le certificat.
• Impossible d'obtenir le certificat de l'émetteur local / impossible de vérifier le premier certificat : le serveur ne dispose souvent pas d'un certificat d'autorité de certification intermédiaire dans la chaîne, ou le magasin de certificats de confiance du client ne fait pas confiance à l'autorité de certification émettrice.
• Le certificat a expiré / n'est pas encore valide : renouvelez le certificat et vérifiez également l'horloge système sur le serveur et sur tout client de fédération privée étroitement contrôlé.
• Certificat auto-signé : une fédération publique le rejettera généralement. Pour une fédération privée, utilisez une autorité de certification privée et configurez explicitement la confiance plutôt que de désactiver globalement la vérification.

3. Corrigez une incohérence de nom d'hôte au niveau du proxy inverse.

Une incompatibilité de nom d'hôte est particulièrement fréquente lorsque le site exposé au client et le point de terminaison de fédération utilisent des hôtes virtuels différents. Par exemple, un serveur example.compeut héberger un site web tandis matrix.example.comqu'un proxy Synapse est utilisé. Si votre .well-knownfichier délègue à un autre serveur matrix.example.com:443, le point de terminaison TLS sur cet hôte doit fournir un certificat valide pour ce serveur matrix.example.com.

Pour Nginx, examinez l'hôte virtuel actif plutôt que le seul fichier de configuration que vous aviez l'intention d'utiliser :

sudo nginx -T | less

Vérifiez le server_nameport d'écoute et les chemins d'accès aux certificats. Une section TLS classique utilise la chaîne de certificats complète :

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;
    }
}

Validez et rechargez uniquement après la réussite du test de configuration :

sudo nginx -t && sudo systemctl reload nginx

Synapse recommande l'utilisation d'un proxy inverse pour les déploiements courants et distingue le port client habituel (443) du port de fédération par défaut (8448). Consultez la documentation officielle de Synapse relative aux proxys inverses pour connaître les exigences actuelles.

4. Fournir la chaîne de certificats complète

Un certificat final peut sembler valide dans un navigateur que vous utilisez déjà, mais être invalide pour un autre serveur si celui-ci n'envoie pas le certificat intermédiaire requis. La documentation de Synapse indique clairement que lorsque Synapse est configuré avec un certificat, le fichier PEM doit contenir la chaîne complète ; avec Certbot, cela signifie utiliser le certificat final fullchain.pemplutôt que le certificat intermédiaire cert.pem.

Le même principe s'applique lorsque TLS se termine au niveau d'un proxy comme Nginx, Caddy, HAProxy ou autre : configurez ce proxy pour qu'il présente la chaîne complète correcte. Vérifiez ce qui est réellement servi, et pas seulement ce qui est présent sur le disque.

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

Vous devriez voir le certificat final suivi du ou des certificats intermédiaires nécessaires. Le serveur n'a généralement pas besoin d'envoyer l'autorité de certification racine, car les clients font déjà confiance aux autorités de certification racines via leur magasin de certificats de confiance.

5. Vérifiez le DNS et la découverte Matrix pour détecter les problèmes de routage obsolètes ou fractionnés.

Si le certificat est correct sur une machine mais que la fédération distante signale toujours un certificat différent, il est possible que le DNS redirige certains clients vers un autre serveur. Vérifiez les enregistrements IPv4 et IPv6 et n'oubliez pas qu'un enregistrement A valide ne compense pas un enregistrement AAAA obsolète si les serveurs distants privilégient IPv6.

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

Vérifiez également tous les enregistrements SRV de fédération que vous utilisez intentionnellement :

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

Si vous avez récemment effectué des modifications .well-known, activez la mise en cache. La spécification Matrix permet aux clients de mettre en cache les réponses de découverte, voire les tentatives de découverte infructueuses, pendant un certain temps. Ainsi, une configuration peut être correcte actuellement, tandis qu'un serveur distant continue temporairement d'utiliser le routage précédemment découvert.

En présence des certificats A et AAAA, effectuez une vérification TLS sur chaque route si nécessaire. Si un équilibreur de charge protège plusieurs nœuds proxy, vérifiez que chaque nœud possède le même certificat et la même chaîne de certificats à jour.

6. Renforcer la confiance entre les autorités de certification privées sans affaiblir la fédération publique

La fédération privée est le principal cas légitime où une autorité de certification publique peut ne pas convenir. Synapse permet federation_custom_ca_listde définir des autorités personnalisées. La documentation actuelle souligne un point important : cette liste remplace les certificats d'autorité de certification fournis par l'environnement d'exploitation. Par conséquent, si vous la configurez, assurez-vous d'inclure l'ensemble complet des certificats de confiance requis par votre déploiement.

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

Après avoir modifié la configuration de confiance, redémarrez Synapse à l'aide du mécanisme de service de votre installation et consultez les journaux pour détecter d'éventuelles erreurs de certificat. Les déploiements conteneurisés nécessitent également une attention particulière : l'hôte peut faire confiance à une autorité de certification privée alors que le conteneur Synapse ne le fait pas. Vérifiez que les éléments de confiance sont montés dans le conteneur et que le chemin configuré est accessible en lecture depuis celui-ci.

Synapse propose également federation_certificate_verification_whitelistune option de désactivation globale federation_verify_certificates, mais la documentation officielle limite son utilisation à des cas exceptionnels. Désactiver la vérification globalement peut masquer l'erreur sans pour autant résoudre le problème d'identité sous-jacent. Pour une fédération publique classique, il est préférable de réparer le certificat ou le routage.

7. Vérifiez d'abord la réparation au niveau de la couche TLS.

Après avoir effectué les modifications, répétez exactement la commande OpenSSL qui a échoué précédemment. L'objectif est de réussir la vérification du nom d'hôte et de la chaîne pour le point de terminaison auquel la découverte Matrix résout.

Ensuite, effectuez une requête HTTPS vers un point de terminaison de fédération. Pour un point de terminaison direct sur le port 8448 :

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

Pour un point de terminaison délégué sur le port 443 :

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

Un résultat TLS positif devrait indiquer que le certificat est validé avec succès. Le point de terminaison Matrix devrait alors renvoyer une réponse HTTP du serveur principal ou du proxy, au lieu d'échouer lors de la validation du certificat. Le point de terminaison de version est utile pour les tests d'accessibilité ; il ne garantit cependant pas que chaque salle ou serveur distant sera correctement fédéré.

8. Consultez les journaux Synapse et distinguez les erreurs TLS des erreurs de fédération de niveau supérieur.

Si la vérification TLS réussit mais que la fédération échoue toujours, cessez de considérer cela comme un problème de certificat. Remontez dans la pile et examinez les journaux Synapse pour détecter d'éventuelles erreurs DNS, des délais d'attente de connexion, des erreurs d'état HTTP, des problèmes de clé de signature, des échecs d'autorisation ou des interruptions de serveur distant.

Sur les installations basées sur systemd, un point de départ courant est :

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

Pour Docker, utilisez les journaux du conteneur pour votre service Synapse. Effectuez vos recherches autour de l'horodatage d'une nouvelle tentative de fédération plutôt que de vous fier à d'anciens messages de certificat qui pourraient ne plus être pertinents.

Tableau de décision rapide

Comment savoir si le problème est réellement résolu ?

N’utilisez pas « le service a redémarré sans erreur » comme critère de réussite. Une réparation fiable présente trois signes observables : le nom d’hôte de la fédération est validé par une autorité de certification de confiance, la chaîne servie est validée par une autorité de certification de confiance et une nouvelle requête HTTPS de fédération parvient à Synapse sans exception lors de la vérification TLS.

Si un seul serveur distant présente toujours une défaillance après ces vérifications, envisagez la mise en cache, le magasin de certificats de confiance de ce serveur ou un chemin réseau spécifique au point de terminaison. Si plusieurs serveurs publics non liés présentent la même défaillance, vérifiez d'abord votre certificat, votre route IPv6, vos nœuds d'équilibrage de charge et votre configuration de découverte.

Pour les systèmes de production, maintenez la vérification des certificats activée et assurez-vous que leur renouvellement est visible. La solution durable ne consiste pas à désactiver la vérification, mais à garantir que la découverte Matrix, le DNS, SNI, le proxy inverse et la chaîne de certificats décrivent tous le même point de terminaison de fédération.