Corrigir erros de federação "Falha na verificação do certificado SSL" no Matrix Synapse

Uma falha comum no Matrix Synapse parece enganosamente simples: os clientes locais conseguem fazer login, seu proxy reverso está online e o próprio Synapse pode parecer estar funcionando corretamente, mas os servidores domésticos remotos não conseguem se federar com você. Os logs de um dos lados podem conter frases como certificate verify failed" <endereço inválido>", hostname mismatch"< unable to get local issuer certificateendereço inválido>", "<endereço inválido>" ou uma falha genérica na solicitação de federação causada pela verificação TLS.

A maneira mais rápida de corrigir isso é testar o nome do host e a porta exatos para os quais a descoberta de federação do Matrix resolve e, em seguida, corrigir o certificado, a cadeia ou o caminho de descoberta incorreto. Não comece desativando as verificações de certificado. O tráfego servidor-servidor do Matrix é HTTPS e a especificação do Matrix exige que o destino apresente um certificado assinado por uma autoridade de certificação confiável. O Synapse também mantém a verificação de certificado de federação de saída ativada por padrão. Consulte a especificação da API servidor-servidor do Matrix e a documentação de configuração atual do Synapse .

1. Identifique o nome de host que a federação está realmente validando.

Antes de alterar o Nginx, Caddy, Synapse ou DNS, determine o nome do certificado que o Matrix espera. A resposta depende da sua configuração server_namee da descoberta de servidores.

Se o nome do seu servidor Matrix for ` example.com<nome_do_servidor>` e você não delegar a federação, outros servidores domésticos normalmente tentarão o serviço de federação associado a esse nome, geralmente na porta TCP 8448. Se você usar `<nome_do_servidor>` https://example.com/.well-known/matrix/server, o m.servervalor pode delegar a federação para outro nome de host, como matrix.example.com:443`<nome_do_host>`. Nesse caso, o nome de host delegado faz parte do caminho de validação TLS. O Matrix também oferece suporte à descoberta baseada em SRV, mas a documentação do Synapse recomenda .well-knowna delegação para implantações típicas, pois é mais fácil de entender e configurar corretamente. O comportamento autoritativo está documentado na seção de descoberta de servidores na especificação do Matrix e na delegação de federação do Synapse .

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

Uma resposta delegada pode ter a seguinte aparência:

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

Se o arquivo estiver ausente ou inválido, não presuma que isso seja devido a um bug do TLS. O Matrix possui regras de descoberta alternativas. O importante é saber qual nome de host e porta um servidor remoto irá contatar.

2. Reproduza a falha na verificação do certificado com o OpenSSL.

Após identificar o endpoint de federação esperado, teste-o diretamente com SNI e verificação de nome de host. Isso permite diferenciar um problema de identidade TLS de um problema da aplicação Synapse.

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

Para um host delegado na porta 443, altere tanto o destino da conexão quanto o nome do host esperado:

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

Concentre-se no resultado final da verificação e nos nomes alternativos do sujeito do certificado. Uma conexão pode ser bem-sucedida nos níveis dos protocolos TCP e TLS, mesmo que a verificação de identidade falhe. É por isso que "a porta está aberta" não é suficiente.

O que geralmente significam os erros mais comuns do OpenSSL

• Incompatibilidade de nome de host: o proxy reverso forneceu um certificado para um nome de host diferente ou seu registro de descoberta direciona a federação para um nome de host não coberto pelo certificado.
• Não foi possível obter o certificado da autoridade emissora local / não foi possível verificar o primeiro certificado: geralmente, o servidor não possui um certificado de autoridade certificadora (CA) intermediário na cadeia, ou o repositório de certificados confiáveis ​​do cliente não confia na CA emissora.
• O certificado expirou/ainda não é válido: renove o certificado e verifique também o relógio do sistema tanto no servidor quanto em qualquer cliente de federação privada rigorosamente controlado.
• Certificado autoassinado: uma federação pública normalmente o rejeitará. Para uma federação privada, use uma CA privada e configure a confiança explicitamente, em vez de desativar a verificação globalmente.

3. Corrija uma incompatibilidade de nome de host no proxy reverso.

Uma incompatibilidade de nomes de host é especialmente comum quando o site voltado para o cliente e o endpoint de federação usam hosts virtuais diferentes. Por exemplo, um host example.compode hospedar um site enquanto matrix.example.comoutro host serve como proxy para o Synapse. Se o seu .well-knownarquivo delega para o Synapse matrix.example.com:443, o endpoint TLS nesse host deve fornecer um certificado válido para o Synapse matrix.example.com.

Para o Nginx, inspecione o host virtual ativo em vez de apenas o arquivo de configuração que você pretendia usar:

sudo nginx -T | less

Verifique o server_nameendereço IP, a porta de escuta e os caminhos dos certificados. Uma seção TLS típica utiliza a cadeia 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 e recarregue somente após o teste de configuração ser bem-sucedido:

sudo nginx -t && sudo systemctl reload nginx

A Synapse recomenda o uso de um proxy reverso para implantações comuns e distingue a porta usual do cliente (443) da porta de federação padrão (8448). Consulte a documentação oficial da Synapse sobre proxy reverso para obter os requisitos atuais do proxy.

4. Apresentar a cadeia de certificados completa.

Um certificado de folha pode parecer correto em um navegador que você já usa e ainda assim falhar em outro servidor doméstico se o seu servidor não enviar o certificado intermediário necessário. A documentação do Synapse afirma explicitamente que, quando o próprio Synapse é configurado com um certificado, o arquivo PEM deve conter a cadeia completa; com o Certbot, isso significa usar o certificado completo fullchain.pemem vez de apenas o certificado de folha cert.pem.

O mesmo princípio se aplica quando o TLS termina no Nginx, Caddy, HAProxy ou outro proxy: configure esse proxy para apresentar a cadeia completa correta. Inspecione o que está sendo efetivamente servido, e não apenas o que existe no disco.

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

Você deverá ver o certificado folha seguido do(s) certificado(s) intermediário(s) necessário(s). Geralmente, o servidor não precisa enviar a CA raiz, pois os clientes normalmente já confiam nas raízes por meio de seu repositório de certificados confiáveis.

5. Verifique se o DNS e a descoberta do Matrix estão desatualizados ou com roteamento dividido.

Se o certificado estiver correto em uma máquina, mas a federação remota ainda reportar um certificado diferente, o DNS pode estar direcionando alguns clientes para outro lugar. Verifique os registros IPv4 e IPv6 e lembre-se de que um registro A funcionando não compensa um registro AAAA desatualizado se os servidores remotos preferirem IPv6.

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

Inspecione também quaisquer registros SRV de federação que você utilize intencionalmente:

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

Se você alterou recentemente alguma configuração .well-known, habilite o armazenamento em cache. A especificação Matrix permite que os clientes armazenem em cache as respostas de descoberta e até mesmo as tentativas de descoberta com falha por um período de tempo. Isso significa que uma configuração pode estar correta agora, enquanto um servidor remoto continua usando temporariamente o roteamento descoberto anteriormente.

Quando A e AAAA existirem, execute a verificação TLS em cada rota, se necessário. Se um balanceador de carga estiver à frente de vários nós proxy, verifique se todos os nós possuem o mesmo certificado e cadeia de certificados atuais.

6. Corrigir a confiança entre autoridades certificadoras privadas sem enfraquecer a federação pública.

A federação privada é o principal caso legítimo em que uma AC pública pode não ser apropriada. O Synapse oferece federation_custom_ca_listsuporte a autoridades personalizadas. A documentação atual observa um comportamento importante: esta lista substitui os certificados de AC fornecidos pelo ambiente operacional. Portanto, se você a configurar, inclua o conjunto completo de certificados de confiança que sua implementação realmente exige.

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

Após alterar a configuração de confiança, reinicie o Synapse usando o mecanismo de serviço da sua instalação e verifique os logs em busca de erros de certificado. Implantações em contêineres também merecem atenção especial: o host pode confiar em uma CA privada, enquanto o contêiner do Synapse não. Confirme se o material de confiança está montado no contêiner e se o caminho configurado é legível de dentro dele.

O Synapse também expõe federation_certificate_verification_whitelista federation_verify_certificatesopção de configuração global, mas a documentação oficial restringe seu uso a cenários excepcionais. Desativar a verificação globalmente pode fazer o erro desaparecer, mas deixa o problema de identidade subjacente sem solução. Para federações públicas comuns, corrija o certificado ou o roteamento.

7. Verifique primeiro o reparo na camada TLS.

Após efetuar as alterações, repita exatamente o comando OpenSSL que falhou anteriormente. O objetivo é obter sucesso na verificação do nome do host e da cadeia de endereços para o endpoint para o qual a descoberta do Matrix resolve.

Em seguida, faça uma solicitação HTTPS para um endpoint de federação. Para um endpoint direto na porta 8448:

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

Para um ponto de extremidade delegado na porta 443:

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

Um resultado TLS válido deve mostrar que o certificado foi verificado com sucesso. O endpoint do Matrix deve então retornar uma resposta HTTP do servidor principal ou do caminho do proxy, em vez de falhar durante a validação do certificado. O endpoint de versão em si é útil para testes de acessibilidade; ele não comprova que todas as salas ou servidores remotos se federarão corretamente.

8. Verifique os logs do Synapse e diferencie erros de TLS de erros de federação de nível superior.

Se a verificação TLS for bem-sucedida, mas a federação ainda falhar, pare de tratar o problema como uma falha de certificado. Analise os logs do Synapse em busca de falhas de DNS, tempos limite de conexão, erros de status HTTP, problemas com a chave de assinatura, falhas de autorização ou atrasos do servidor remoto.

Em instalações baseadas em systemd, um ponto de partida comum é:

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

Para o Docker, utilize os logs do contêiner do seu serviço Synapse. Busque informações próximas ao registro de data e hora de uma nova tentativa de federação, em vez de se basear em mensagens de certificado antigas que podem não ser mais relevantes.

Tabela de decisão rápida

Como saber se o problema foi realmente resolvido?

Não utilize "o serviço foi reiniciado sem erros" como critério de sucesso. Uma reparação confiável apresenta três sinais observáveis: o nome de host da federação passa na verificação de nome de host, a cadeia servida é validada por uma CA confiável e uma nova solicitação HTTPS da federação chega ao Synapse sem uma exceção de verificação TLS.

Se apenas um servidor doméstico remoto ainda apresentar falhas após essas verificações, considere o uso de cache, o armazenamento de certificados confiáveis ​​desse servidor remoto ou um caminho de rede específico para o endpoint. Se vários servidores domésticos públicos não relacionados apresentarem falhas da mesma forma, verifique novamente seu próprio certificado, rota IPv6, nós do balanceador de carga e configuração de descoberta.

Para sistemas de produção, mantenha a verificação de certificados ativada e torne a renovação de certificados observável. A solução definitiva não é suprimir a verificação, mas sim garantir que a descoberta do Matrix, o DNS, o SNI, o proxy reverso e a cadeia de certificados descrevam o mesmo ponto de extremidade de federação.