Solucionar los errores de federación de Matrix Synapse 'Error de verificación del certificado SSL'

Un fallo común de Matrix Synapse parece engañosamente simple: los clientes locales pueden iniciar sesión, su proxy inverso está en línea y Synapse puede parecer que funciona correctamente, pero los servidores remotos no pueden federarse con usted. Los registros de un lado pueden contener frases como certificate verify failed, hostname mismatch, unable to get local issuer certificate, o un fallo genérico de solicitud de federación causado por la verificación TLS.

La forma más rápida de solucionar esto es comprobar el nombre de host y el puerto exactos a los que se resuelve el descubrimiento de federación de Matrix, y luego corregir el certificado, la cadena o la ruta de descubrimiento que sea incorrecta. No comience por deshabilitar las comprobaciones de certificados. El tráfico de servidor a servidor de Matrix es HTTPS, y la especificación de Matrix requiere que el destino presente un certificado firmado por una autoridad de certificación de confianza. Synapse también mantiene la verificación de certificados de federación saliente habilitada de forma predeterminada. Consulte la especificación de la API de servidor a servidor de Matrix y la documentación de configuración actual de Synapse .

1. Identificar el nombre de host que la federación está validando realmente.

Antes de modificar Nginx, Caddy, Synapse o DNS, determine el nombre del certificado que espera Matrix. La respuesta depende de su configuración server_namey del descubrimiento del servidor.

Si el nombre de su servidor Matrix es example.comy no delega la federación, otros servidores domésticos normalmente intentan el servicio de federación asociado con ese nombre, comúnmente en TCP 8448. Si sirve https://example.com/.well-known/matrix/server, el m.servervalor puede delegar la federación a otro nombre de host como matrix.example.com:443. En ese caso, el nombre de host delegado es parte de la ruta de validación TLS. Matrix también admite el descubrimiento basado en SRV, pero la documentación de Synapse recomienda .well-knownla delegación para implementaciones típicas porque es más fácil de entender y configurar correctamente. El comportamiento autoritativo está documentado en el descubrimiento de servidores en la especificación Matrix y la delegación de federación de Synapse .

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

Una respuesta delegada puede tener este aspecto:

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

Si el archivo no existe o es inválido, no asuma que se trata de un error de TLS. Matrix cuenta con reglas de detección alternativas. Lo importante es saber qué nombre de host y puerto utilizará finalmente el servidor remoto.

2. Reproduzca el fallo de verificación del certificado con OpenSSL.

Una vez que conozca el punto final de federación esperado, pruébelo directamente con SNI y verificación de nombre de host. Esto permite diferenciar un problema de identidad TLS de un problema de la aplicación Synapse.

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

Para un host delegado en el puerto 443, cambie tanto el destino de la conexión como el nombre de host esperado:

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

Concéntrese en el resultado de la verificación final y en los nombres alternativos del sujeto del certificado. Una conexión puede ser exitosa a nivel de protocolo TCP y TLS, pero aun así fallar la verificación de identidad. Por eso, decir que "el puerto está abierto" no es suficiente.

Qué suelen significar los errores más comunes de OpenSSL.

• Discrepancia en el nombre de host: el proxy inverso emitió un certificado para un nombre de host diferente, o bien su registro de descubrimiento dirige la federación a un nombre de host no cubierto por el certificado.
• No se puede obtener el certificado del emisor local / no se puede verificar el primer certificado: a menudo, al servidor le falta un certificado de CA intermedio en la cadena, o el almacén de confianza del cliente no confía en la CA emisora.
• El certificado ha caducado o aún no es válido: renueve el certificado y verifique también la hora del sistema tanto en el servidor como en cualquier cliente de federación privada estrictamente controlado.
• Certificado autofirmado: la federación pública normalmente lo rechazará. Para una federación privada, utilice una CA privada y configure la confianza explícitamente en lugar de desactivar la verificación globalmente.

3. Solucione la discrepancia en el nombre de host en el proxy inverso.

Una discrepancia en el nombre de host es especialmente común cuando el sitio orientado al cliente y el punto final de la federación utilizan hosts virtuales diferentes. Por ejemplo, example.compuede alojar un sitio web mientras que matrix.example.comactúa como proxy para Synapse. Si su .well-knownarchivo delega en matrix.example.com:443, el punto final TLS en ese host debe proporcionar un certificado válido para matrix.example.com.

Para Nginx, inspeccione el host virtual activo en lugar de solo el archivo de configuración que pretendía utilizar:

sudo nginx -T | less

Verifique el server_namepuerto de escucha y las rutas del certificado. Una sección TLS típica utiliza la cadena de certificados completa:

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

Valide y recargue solo después de que la prueba de configuración sea exitosa:

sudo nginx -t && sudo systemctl reload nginx

Synapse recomienda un proxy inverso para implementaciones comunes y distingue el puerto de cliente habitual 443 del puerto de federación predeterminado 8448. Consulte la documentación oficial del proxy inverso de Synapse para conocer los requisitos actuales del proxy.

4. Servir la cadena de certificados completa

Un certificado hoja puede parecer correcto en un navegador que ya usas y aun así fallar para otro servidor doméstico si tu servidor no envía el certificado intermedio requerido. La documentación de Synapse dice explícitamente que cuando Synapse se configura con un certificado, el archivo PEM debe contener la cadena completa; con Certbot, eso significa usar fullchain.pemen lugar de solo cert.pem.

El mismo principio se aplica cuando TLS finaliza en Nginx, Caddy, HAProxy u otro proxy: configure ese proxy para que presente la cadena completa correcta. Inspeccione lo que realmente se está sirviendo, no solo lo que existe en el disco:

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

Debería ver el certificado hoja seguido del certificado o certificados intermedios necesarios. Por lo general, el servidor no necesita enviar la CA raíz, ya que los clientes normalmente ya confían en las raíces a través de su almacén de confianza.

5. Compruebe el DNS y el descubrimiento de Matrix para detectar enrutamiento obsoleto o dividido.

Si el certificado es correcto en una máquina, pero la federación remota sigue informando de un certificado diferente, es posible que el DNS esté redirigiendo a algunos clientes a otra ubicación. Verifique los registros IPv4 e IPv6 y recuerde que un registro A que funcione no compensa un registro AAAA obsoleto si los servidores remotos prefieren IPv6.

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

Inspeccione también cualquier registro SRV de federación que utilice intencionadamente:

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

Si realizó cambios recientemente .well-known, habilite el almacenamiento en caché. La especificación Matrix permite que los clientes almacenen en caché las respuestas de descubrimiento e incluso los intentos de descubrimiento fallidos durante un período de tiempo. Esto significa que una configuración puede ser correcta ahora, mientras que un servidor remoto continúa utilizando temporalmente el enrutamiento descubierto previamente.

Cuando existan tanto A como AAAA, ejecute la comprobación TLS en cada ruta si es necesario. Si un balanceador de carga gestiona varios nodos proxy, verifique que cada nodo tenga el mismo certificado y cadena vigentes.

6. Solucionar el problema de confianza con las CA privadas sin debilitar la federación pública.

La federación privada es el principal caso legítimo en el que una CA pública podría no ser apropiada. Synapse permite federation_custom_ca_listel uso de autoridades personalizadas. La documentación actual destaca un comportamiento importante: esta lista reemplaza los certificados de CA proporcionados por el entorno operativo. Por lo tanto, si la configura, incluya el conjunto completo de confianza que su implementación realmente requiere.

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

Tras modificar la configuración de confianza, reinicie Synapse utilizando el mecanismo de servicio correspondiente a su instalación e inspeccione los registros en busca de errores de certificado. Las implementaciones en contenedores también requieren especial atención: el host puede confiar en una CA privada, mientras que el contenedor de Synapse no. Confirme que el material de confianza esté montado en el contenedor y que la ruta configurada sea legible desde su interior.

Synapse también ofrece la opción de desactivar federation_certificate_verification_whitelistla verificación globalmente federation_verify_certificates, pero la documentación oficial la restringe a situaciones excepcionales. Desactivar la verificación globalmente puede hacer desaparecer el error, pero sin resolver el problema de identidad subyacente. Para la federación pública habitual, repare el certificado o el enrutamiento.

7. Verifique primero la reparación en la capa TLS.

Tras realizar los cambios, repita el comando OpenSSL exacto que falló anteriormente. El objetivo es lograr una verificación exitosa del nombre de host y la cadena para el punto final al que se resuelve el descubrimiento de Matrix.

Luego, realice una solicitud HTTPS a un punto final de federación. Para un punto final directo en el puerto 8448:

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

Para un punto final delegado en el puerto 443:

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

Un resultado TLS correcto debería indicar que el certificado se verifica con éxito. El punto final de Matrix debería entonces devolver una respuesta HTTP desde el servidor principal o la ruta del proxy, en lugar de fallar durante la validación del certificado. El punto final de versión es útil para probar la accesibilidad; no garantiza que todas las salas o servidores remotos se federen correctamente.

8. Revise los registros de Synapse y distinga los errores de TLS de los errores de federación de nivel superior.

Si la verificación TLS ahora se realiza correctamente, pero la federación sigue fallando, deje de tratarlo como un problema de certificado. Continúe revisando los registros de Synapse en busca de fallos de DNS, tiempos de espera de conexión, errores de estado HTTP, problemas con la clave de firma, fallos de autorización o retroceso del servidor remoto.

En las instalaciones basadas en systemd, un punto de partida común es:

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

Para Docker, utilice los registros del contenedor de su servicio Synapse. Busque en torno a la marca de tiempo de un nuevo intento de federación en lugar de basarse en mensajes de certificados antiguos que podrían ya no ser relevantes.

Tabla de decisiones rápidas

Cómo saber si el problema está realmente solucionado

No utilice el criterio de éxito de que el servicio se haya reiniciado sin errores. Una reparación fiable presenta tres señales observables: el nombre de host de la federación exacto supera la verificación, la cadena servida se valida con una CA de confianza y una nueva solicitud HTTPS de federación llega a Synapse sin excepciones de verificación TLS.

Si tras estas comprobaciones solo falla un servidor remoto, considere la posibilidad de usar caché, el almacén de confianza de dicho servidor o una ruta de red específica para el punto final. Si varios servidores públicos independientes fallan de la misma manera, revise primero su certificado, la ruta IPv6, los nodos del balanceador de carga y la configuración de detección.

Para sistemas de producción, mantenga habilitada la verificación de certificados y haga que la renovación de certificados sea observable. La solución definitiva no consiste en suprimir la verificación, sino en garantizar que el descubrimiento de Matrix, DNS, SNI, el proxy inverso y la cadena de certificados describan el mismo punto final de federación.