Napraw błędy federacji „Nieudana weryfikacja certyfikatu SSL” w Matrix Synapse

Typowa awaria Matrix Synapse wydaje się pozornie prosta: lokalni klienci mogą się zalogować, serwer proxy odwrotny jest online, a sam Synapse może wydawać się sprawny, ale zdalne serwery domowe nie mogą się z Tobą sfederować. Logi po jednej stronie mogą zawierać frazy takie jak certificate verify failed, hostname mismatch, unable to get local issuer certificatelub ogólny błąd żądania federacji spowodowany weryfikacją TLS.

Najszybszym sposobem rozwiązania tego problemu jest sprawdzenie dokładnej nazwy hosta i portu, na które rozpoznaje się odnajdywanie federacji Matrix, a następnie naprawienie nieprawidłowego certyfikatu, łańcucha lub ścieżki odnajdywania. Nie należy zaczynać od wyłączenia sprawdzania certyfikatów. Ruch między serwerami Matrix odbywa się za pomocą protokołu HTTPS, a specyfikacja Matrix wymaga, aby miejsce docelowe przedstawiło certyfikat podpisany przez zaufany urząd certyfikacji. Synapse domyślnie włącza również weryfikację certyfikatów federacji wychodzącej. Zapoznaj się ze specyfikacją API Matrix Server-Server oraz aktualną dokumentacją konfiguracji Synapse .

1. Zidentyfikuj nazwę hosta, którą federacja faktycznie weryfikuje

Przed zmianą Nginx, Caddy, Synapse lub DNS, określ nazwę certyfikatu, jakiej oczekuje Matrix. Odpowiedź zależy od Twojego server_namei serwera wykrywania.

Jeśli nazwa serwera Matrix to example.comi nie delegujesz federacji, inne serwery domowe zazwyczaj próbują usługi federacyjnej powiązanej z tą nazwą, zazwyczaj na porcie TCP 8448. Jeśli obsługujesz https://example.com/.well-known/matrix/server, m.serverwartość może delegować federację do innej nazwy hosta, takiej jak matrix.example.com:443. W takim przypadku delegowana nazwa hosta jest częścią ścieżki walidacji TLS. Matrix obsługuje również wykrywanie oparte na SRV, ale dokumentacja Synapse zaleca .well-knowndelegowanie w typowych wdrożeniach, ponieważ ułatwia to wnioskowanie i poprawną konfigurację. Działanie autorytatywne jest udokumentowane w sekcji „ Wykrywanie serwerów” w specyfikacji Matrix oraz w sekcji „Delegacja federacji Synapse” .

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

Delegowana odpowiedź może wyglądać następująco:

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

Jeśli plik jest nieobecny lub nieprawidłowy, nie zakładaj, że to błąd TLS. Matrix ma awaryjne reguły wykrywania. Ważne jest, aby wiedzieć, z jaką nazwą hosta i portem ostatecznie skontaktuje się serwer zdalny.

2. Odtwórz błąd weryfikacji certyfikatu za pomocą OpenSSL

Po ustaleniu oczekiwanego punktu końcowego federacji, przetestuj go bezpośrednio za pomocą SNI i weryfikacji nazwy hosta. Pozwala to oddzielić problem z tożsamością TLS od problemu z aplikacją Synapse.

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

W przypadku hosta delegowanego na porcie 443 zmień zarówno cel połączenia, jak i oczekiwaną nazwę hosta:

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

Skoncentruj się na końcowym wyniku weryfikacji i alternatywnych nazwach podmiotu certyfikatu. Połączenie może się powieść na poziomie protokołów TCP i TLS, ale nadal nie przejść weryfikacji tożsamości. Dlatego „port jest otwarty” to za mało.

Co zazwyczaj oznaczają najczęstsze błędy OpenSSL

• Niezgodność nazwy hosta: odwrotny serwer proxy dostarczył certyfikat dla innej nazwy hosta lub rekord wykrywania kieruje federację do nazwy hosta nieobjętej certyfikatem.
• Nie można uzyskać lokalnego certyfikatu wystawcy / nie można zweryfikować pierwszego certyfikatu: serwerowi często brakuje pośredniego certyfikatu urzędu certyfikacji w łańcuchu lub magazyn zaufania klienta nie ufa wystawiającemu urzędowi certyfikacji.
• Certyfikat wygasł lub nie jest jeszcze ważny: odnów certyfikat i sprawdź zegar systemowy zarówno na serwerze, jak i na każdym ściśle kontrolowanym kliencie federacji prywatnej.
• Certyfikat podpisany samodzielnie: federacja publiczna zazwyczaj go odrzuci. W przypadku federacji prywatnej należy użyć prywatnego urzędu certyfikacji i jawnie skonfigurować zaufanie, zamiast globalnie wyłączać weryfikację.

3. Napraw niezgodność nazwy hosta na odwrotnym serwerze proxy

Niezgodność nazw hostów jest szczególnie powszechna, gdy witryna skierowana do klienta i punkt końcowy federacji korzystają z różnych hostów wirtualnych. Na przykład, example.comwitryna internetowa może hostować serwer matrix.example.comproxy Synapse. Jeśli .well-knownplik deleguje do matrix.example.com:443, punkt końcowy TLS na tym hoście musi obsługiwać certyfikat ważny dla matrix.example.com.

W przypadku serwera Nginx sprawdź aktywny wirtualny host, a nie tylko plik konfiguracyjny, którego zamierzasz użyć:

sudo nginx -T | less

Sprawdź ścieżki server_name, port nasłuchu i certyfikaty. Typowa sekcja TLS wykorzystuje pełny łańcuch certyfikatów:

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

Sprawdź poprawność i załaduj ponownie dopiero po pomyślnym zakończeniu testu konfiguracji:

sudo nginx -t && sudo systemctl reload nginx

Firma Synapse zaleca korzystanie z odwrotnego serwera proxy w przypadku typowych wdrożeń i rozróżnia standardowy port klienta 443 od domyślnego portu federacyjnego 8448. Aktualne wymagania dotyczące serwera proxy można znaleźć w oficjalnej dokumentacji odwrotnego serwera proxy firmy Synapse .

4. Obsługuj cały łańcuch certyfikatów

Certyfikat liściowy może wyglądać poprawnie w przeglądarce, z której już korzystasz, a mimo to nie zostać przesłany na inny serwer domowy, jeśli Twój serwer nie wyśle ​​wymaganego certyfikatu pośredniego. Dokumentacja Synapse wyraźnie stwierdza, że ​​gdy sam Synapse jest skonfigurowany z certyfikatem, plik PEM powinien zawierać pełny łańcuch; w przypadku Certbota oznacza to użycie fullchain.pemzamiast tylko cert.pem.

Ta sama zasada obowiązuje, gdy TLS kończy działanie na Nginx, Caddy, HAProxy lub innym serwerze proxy: skonfiguruj ten serwer proxy tak, aby prezentował poprawny pełny łańcuch. Sprawdź, co faktycznie jest obsługiwane, a nie tylko to, co znajduje się na dysku:

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

Powinieneś zobaczyć certyfikat potomny, a następnie wymagany certyfikat lub certyfikaty pośrednie. Serwer zazwyczaj nie musi wysyłać głównego urzędu certyfikacji, ponieważ klienci zazwyczaj ufają certyfikatom głównym za pośrednictwem swojego magazynu zaufanych certyfikatów.

5. Sprawdź DNS i wykrywanie macierzy pod kątem nieaktualnego lub podzielonego routingu

Jeśli certyfikat jest poprawny na jednym komputerze, ale zdalna federacja nadal zgłasza inny certyfikat, DNS może kierować niektórych klientów gdzie indziej. Sprawdź zarówno rekordy IPv4, jak i IPv6 i pamiętaj, że działający rekord A nie rekompensuje nieaktualnego rekordu AAAA, jeśli zdalne serwery domowe preferują IPv6.

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

Sprawdź także wszystkie rekordy SRV federacji, których celowo używasz:

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

Jeśli ostatnio dokonano zmiany .well-known, zezwól na buforowanie. Specyfikacja Matrix pozwala klientom buforować odpowiedzi wykrywania, a nawet nieudane próby wykrywania, przez określony czas. Oznacza to, że konfiguracja może być teraz poprawna, podczas gdy serwer zdalny tymczasowo kontynuuje korzystanie z wcześniej wykrytego routingu.

Jeśli istnieją zarówno A, jak i AAAA, w razie potrzeby uruchom sprawdzanie TLS dla każdej trasy. Jeśli moduł równoważenia obciążenia obsługuje wiele węzłów proxy, sprawdź, czy każdy węzeł ma ten sam aktualny certyfikat i łańcuch.

6. Napraw zaufanie prywatnego urzędu certyfikacji bez osłabiania federacji publicznej

Prywatna federacja to główny uzasadniony przypadek, w którym publiczny urząd certyfikacji może nie być odpowiedni. Synapse obsługuje federation_custom_ca_listniestandardowe urzędy certyfikacji. Aktualna dokumentacja zwraca uwagę na ważną kwestię: ta lista zastępuje certyfikaty urzędu certyfikacji dostarczane przez system operacyjny. Dlatego, jeśli ją ustawiasz, uwzględnij kompletny zestaw zaufania, którego faktycznie wymaga dane wdrożenie.

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

Po zmianie konfiguracji zaufania, uruchom ponownie Synapse, używając mechanizmu usługi dla swojej instalacji i sprawdź logi pod kątem błędów certyfikatów. Wdrożenia kontenerów również zasługują na szczególną uwagę: host może ufać prywatnemu urzędowi certyfikacji, podczas gdy kontener Synapse nie. Sprawdź, czy materiał zaufania jest zamontowany w kontenerze i czy skonfigurowana ścieżka jest czytelna z jego wnętrza.

Synapse również udostępnia federation_certificate_verification_whitelistglobalny federation_verify_certificatesprzełącznik, ale oficjalna dokumentacja ogranicza je do wyjątkowych scenariuszy. Globalne wyłączenie weryfikacji może spowodować zniknięcie błędu, pozostawiając problem z tożsamością nierozwiązany. W przypadku zwykłej federacji publicznej należy zamiast tego naprawić certyfikat lub routing.

7. Najpierw sprawdź naprawę na warstwie TLS

Po wprowadzeniu zmian powtórz dokładnie to samo polecenie OpenSSL, które wcześniej nie powiodło się. Celem jest pomyślna weryfikacja nazwy hosta i łańcucha dla punktu końcowego, do którego odnajduje się Matrix Discovery.

Następnie wyślij żądanie HTTPS do punktu końcowego federacji. W przypadku bezpośredniego punktu końcowego na porcie 8448:

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

W przypadku delegowanego punktu końcowego na porcie 443:

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

Prawidłowy wynik TLS powinien wskazywać, że certyfikat został pomyślnie zweryfikowany. Punkt końcowy Matrix powinien następnie zwrócić odpowiedź HTTP z serwera domowego lub ścieżki proxy, zamiast zgłaszać błąd podczas walidacji certyfikatu. Sam punkt końcowy wersji jest przydatny do testowania dostępności; nie dowodzi on, że każdy pokój lub serwer zdalny będzie poprawnie federowany.

8. Sprawdź logi Synapse i odróżnij TLS od błędów federacji wyższego poziomu

Jeśli weryfikacja TLS zakończy się sukcesem, ale federacja nadal nie działa, przestań traktować to jako problem z certyfikatem. Przesuń się wyżej w stosie i sprawdź logi Synapse pod kątem błędów DNS, przekroczeń limitu czasu połączenia, błędów stanu HTTP, problemów z kluczem podpisu, błędów autoryzacji lub wycofywania się zdalnego serwera.

W przypadku instalacji bazujących na systemd typowym punktem wyjścia jest:

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

W przypadku Dockera użyj logów kontenera dla usługi Synapse. Przeszukaj znacznik czasu nowej próby federacji, zamiast polegać na starych komunikatach o certyfikatach, które mogą być już nieaktualne.

Szybka tabela decyzyjna

Jak rozpoznać, że problem został naprawdę rozwiązany

Nie należy używać kryterium „usługa uruchomiona ponownie bez błędów” jako kryterium sukcesu. Niezawodna naprawa ma trzy obserwowalne oznaki: dokładna nazwa hosta federacji pomyślnie przechodzi weryfikację, obsługiwany łańcuch przechodzi weryfikację do zaufanego urzędu certyfikacji oraz nowe żądanie HTTPS federacji dociera do Synapse bez wyjątku weryfikacji TLS.

Jeśli po tych sprawdzeniach nadal występuje awaria tylko jednego zdalnego serwera domowego, rozważ buforowanie, magazyn zaufanych certyfikatów tego serwera zdalnego lub ścieżkę sieciową specyficzną dla punktu końcowego. Jeśli wiele niepowiązanych ze sobą publicznych serwerów domowych ulegnie awarii w ten sam sposób, najpierw ponownie sprawdź swój certyfikat, trasę IPv6, węzły modułu równoważenia obciążenia i konfigurację wykrywania.

W systemach produkcyjnych należy włączyć weryfikację certyfikatów i zapewnić obserwowalność odnawiania certyfikatów. Trwałe rozwiązanie nie polega na wyłączeniu weryfikacji, lecz na zapewnieniu, że wykrywanie Matrix, DNS, SNI, odwrotny serwer proxy i łańcuch certyfikatów opisują ten sam punkt końcowy federacji.