Quando i log di Matrix Synapse mostrano errori SSL: CERTIFICATE_VERIFY_FAILEDdurante la federazione, un'adesione potrebbe bloccarsi, un server remoto potrebbe rifiutare la connessione o i messaggi potrebbero non arrivare. Innanzitutto, individua quale certificato non funziona: il certificato di un server remoto durante una richiesta in uscita o il certificato del tuo endpoint di federazione quando si connette un altro server. Quindi, ripara la catena di certificati, il nome host o la configurazione di attendibilità identificati dal log e da un test di federazione. Non disabilitare la verifica TLS come soluzione generale.
Il traffico server-to-server di Matrix utilizza HTTPS e la specifica Matrix richiede che la destinazione presenti un certificato TLS firmato da un'autorità di certificazione riconosciuta. Un errore di verifica di solito significa che il certificato presentato è scaduto, incompleto, emesso per un nome host diverso o firmato da un'autorità di certificazione di cui il server di connessione non si fida. Anche un proxy inverso può fornire il certificato sbagliato, persino quando la configurazione di Synapse sembra corretta.
1. Identificare il lato difettoso prima di modificare la configurazione
Controlla la voce del registro di Synapse relativa all'errore e annota il nome del server remoto e l'errore esatto del certificato. Se Synapse segnala l'errore durante una richiesta a un altro server domestico, il problema potrebbe risiedere nel certificato del server remoto o nell'autorità di certificazione (CA) utilizzata dal processo Synapse. Se altri server non riescono a federarsi con il tuo dominio, controlla invece l'endpoint TLS pubblico e il rilevamento dei server.
Conferma il nome del tuo server Matrix da homeserver.yaml, in particolare server_name. Questa è la parte di dominio degli ID Matrix locali e determina come gli altri homeserver ti raggiungono. Non confonderla con il nome host interno della macchina o del container. La documentazione di installazione di Synapse attualmente disponibile spiega che il nome del server è un'identità di federazione e consiglia di sceglierlo prima dell'installazione.
2. Testare il certificato pubblico e il percorso di federazione
Utilizza Matrix Federation Tester con il nome del tuo server Matrix. Questo strumento verifica il rilevamento della federazione e la connettività e può rivelare se il certificato visibile esternamente o il routing presentano problemi. Risolvi il problema identificato prima di modificare le impostazioni di attendibilità in uscita di Synapse.
Da una macchina in grado di raggiungere l'endpoint di federazione, esamina il certificato TLS. Sostituiscilo matrix.example.orgcon il nome host che dovrebbe presentare il certificato e utilizza la porta di federazione effettiva. La porta 8448 è comune, ma un proxy inverso o un server delegato potrebbero utilizzare un'altra porta.
openssl s_client -connect matrix.example.org:8448 \
-servername matrix.example.org -showcerts </dev/null
Questa -servernameopzione invia l'SNI (Server Name Indication), consentendo a un proxy virtuale di scegliere il certificato per il nome richiesto. Verificare l'esito positivo della verifica nell'output, quindi esaminare l'oggetto e le date di validità del certificato:
openssl s_client -connect matrix.example.org:8448 \
-servername matrix.example.org </dev/null 2>/dev/null | \
openssl x509 -noout -subject -issuer -dates -ext subjectAltName
Il nome utilizzato dalla federazione Matrix deve corrispondere a un nome DNS nel Subject Alternative Name (SODN) del certificato. Verificare inoltre che il certificato sia attualmente valido e che l'endpoint invii i relativi certificati intermedi. Se si utilizza un proxy inverso, testare l'indirizzo proxy pubblico: un file di certificato corretto sull'host Synapse non è sufficiente se il proxy fornisce un certificato obsoleto o non pertinente.
3. Correggere il certificato di Synapse
Se il tester segnala un problema con il certificato del tuo server, rinnova o riemetti il certificato per l'hostname di federazione e configura l'endpoint TLS pubblico per servire la catena completa. Il manuale di configurazione corrente di Synapse specifica che tls_certificate_pathdeve puntare a un certificato PEM che includa i certificati intermedi; per Certbot, usa fullchain.pem, non cert.pem. Conserva la chiave privata in un tls_private_key_pathfile separato e proteggila dall'accesso pubblico.
Quando la connessione TLS termina su Nginx, Caddy o un altro reverse proxy, aggiorna il certificato e la catena di certificati nella configurazione di tale proxy, quindi ricarica il proxy utilizzando il metodo appropriato per la tua installazione. In questa configurazione, i percorsi dei certificati TLS di Synapse potrebbero non controllare il certificato visualizzato dai peer della federazione. Segui la documentazione ufficiale di Synapse relativa al reverse proxy per la configurazione del listener e del proxy che utilizzi.
Verifica anche il rilevamento dei server DNS e Matrix. La federazione può risolvere direttamente il nome del tuo server oppure seguire una /.well-known/matrix/serverdelega a un hostname e una porta diversi. Il certificato deve essere valido per l'hostname raggiunto tramite tale percorso di rilevamento. Un record DNS obsoleto o una delega errata possono indirizzare i peer a un endpoint che presenta un certificato non correlato.
4. Ripristino della fiducia in uscita per una federazione privata
Se il certificato non valido appartiene a un homeserver remoto su una rete privata, verificare innanzitutto che il certificato sia stato emesso intenzionalmente dalla propria autorità di certificazione (CA) privata. Se possibile, installare e mantenere tale CA sull'host Synapse. Synapse supporta anche federation_custom_ca_listcertificati CA personalizzati per la federazione. Questa opzione prevede file PEM e sostituisce l'elenco di CA fornito dal sistema operativo, pertanto è necessario includere tutte le CA necessarie per la propria implementazione, anziché aggiungere una sola CA privata senza verificarne la validità.
federation_custom_ca_list:
- /etc/matrix-synapse/certs/private-root-ca.pem
Imposta il percorso a un certificato CA, non alla chiave privata del server. Assicurati che il processo Synapse possa leggerlo, convalida la formattazione YAML e riavvia o ricarica Synapse in base al metodo di implementazione utilizzato. Il manuale di configurazione di Synapse indica che questa opzione è generalmente destinata alle reti domestiche private.
Non impostare federation_verify_certificates: falsela modalità di silenziamento per gli errori di federazione pubblici. Il valore predefinito è true; disattivandolo si rimuove la verifica del certificato per la federazione in uscita e si indebolisce la protezione contro l'impersonificazione. Questa opzione separata federation_certificate_verification_whitelistesiste per casi specifici e circoscritti, come i servizi nascosti di Tor o le configurazioni private controllate, non come sostituto per la riparazione di un certificato pubblico. Per le infrastrutture private, è generalmente preferibile un'autorità di certificazione privata fidata.
5. Controlla l'ora e riprova
Se le date del certificato risultano non valide anche se il certificato è valido, verificare l'orologio di sistema e la sincronizzazione dell'ora sull'host Synapse e su qualsiasi proxy. Un orologio significativamente errato può far apparire un certificato valido come non ancora valido o scaduto. Verificare inoltre che l'automazione del rinnovo abbia effettivamente aggiornato il file condiviso pubblicamente; il rinnovo del certificato su disco non garantisce che il proxy lo abbia ricaricato.
Dopo la correzione, esegui nuovamente il Federation Tester e ripeti la connessione che ha fallito. Verifica che il tester visualizzi il nome host previsto, date valide e una catena attendibile, e controlla i log di Synapse per individuare nuovi tentativi di federazione senza l'errore di verifica del certificato. Se il tester ha esito positivo ma un server remoto continua a non funzionare, acquisisci il nome di tale server, il timestamp e la relativa voce di log (opportunamente modificata): il problema potrebbe risiedere nel suo certificato o nell'ambiente attendibile. Non condividere chiavi private, token di accesso o contenuti dei messaggi utente durante la risoluzione dei problemi.