Matrix Synapse의 'SSL 인증서 확인 실패' 페더레이션 오류 해결

Matrix Synapse에서 흔히 발생하는 오류는 겉보기에는 간단해 보입니다. 로컬 클라이언트는 로그인할 수 있고, 리버스 프록시도 온라인 상태이며, Synapse 자체도 정상적으로 작동하는 것처럼 보이지만, 원격 홈 서버는 사용자 서버와 페더레이션할 수 없습니다. 한쪽 서버의 로그에는 certificate verify failed, hostname mismatch, 와 같은 문구 unable to get local issuer certificate나 TLS 검증으로 인한 일반적인 페더레이션 요청 실패 메시지가 나타날 수 있습니다.

이 문제를 해결하는 가장 빠른 방법은 Matrix 페더레이션 검색이 확인되는 정확한 호스트 이름과 포트를 테스트한 다음 잘못된 인증서, 인증서 체인 또는 검색 경로를 수정하는 것입니다. 인증서 검사를 비활성화하는 것부터 시작하지 마십시오. Matrix 서버 간 트래픽은 HTTPS이며, Matrix 사양은 대상이 신뢰할 수 있는 인증 기관에서 서명한 인증서를 제시해야 합니다. Synapse는 기본적으로 아웃바운드 페더레이션 인증서 확인을 활성화합니다. Matrix 서버 간 API 사양 및 최신 Synapse 구성 문서를 참조하십시오 .

1. 실제로 페더레이션이 유효성 검사를 수행하는 호스트 이름을 식별합니다.

Nginx, Caddy, Synapse 또는 DNS를 변경하기 전에 Matrix에서 예상하는 인증서 이름을 확인하십시오. 이 이름은 사용자의 설정 server_name과 서버 검색 방식에 따라 다릅니다.

Matrix 서버 이름이 인 경우 example.com, 페더레이션을 위임하지 않으면 다른 홈서버는 일반적으로 해당 이름과 연결된 페더레이션 서비스(주로 TCP 8448 포트)를 시도합니다. 만약 서버 이름이 인 경우 https://example.com/.well-known/matrix/server, m.server페더레이션을 다른 호스트 이름(예: )으로 위임할 수 있습니다 matrix.example.com:443. 이 경우 위임된 호스트 이름은 TLS 유효성 검사 경로에 포함됩니다. Matrix는 SRV 기반 검색도 지원하지만, Synapse 설명서에서는 일반적인 배포 환경에서 위임 방식을 권장합니다 . 위임 방식이 이해하기 쉽고 올바르게 구성하기 편리하기 때문입니다. 권한 있는 동작에 대한 자세한 내용은 Matrix 사양의 서버 검색 및 Synapse 페더레이션 위임 설명서를.well-known 참조하십시오 .

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

위임된 응답은 다음과 같은 형태일 수 있습니다.

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

파일이 없거나 유효하지 않다고 해서 그것이 TLS 버그라고 단정짓지 마십시오. Matrix에는 대체 검색 규칙이 있습니다. 중요한 것은 원격 서버가 최종적으로 어떤 호스트 이름과 포트에 연결할지 아는 것입니다.

2. OpenSSL을 사용하여 인증서 검증 실패를 재현하십시오.

예상되는 페더레이션 엔드포인트를 파악했으면 SNI 및 호스트 이름 검증을 통해 직접 테스트하십시오. 이렇게 하면 TLS ID 문제와 Synapse 애플리케이션 문제를 구분할 수 있습니다.

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

443 포트의 위임된 호스트의 경우 연결 대상과 예상 호스트 이름을 모두 변경하십시오.

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

최종 검증 결과와 인증서 주체 대체 이름(CAN)에 집중하세요. TCP 및 TLS 프로토콜 수준에서는 연결이 성공하더라도 신원 검증에 실패할 수 있습니다. 따라서 "포트가 열려 있다"는 것만으로는 충분하지 않습니다.

가장 흔한 OpenSSL 오류의 일반적인 의미는 무엇일까요?

• 호스트 이름 불일치: 역방향 프록시가 다른 호스트 이름에 대한 인증서를 제공했거나, 검색 레코드가 인증서에 포함되지 않은 호스트 이름으로 페더레이션을 지시합니다.
• 로컬 발급자 인증서를 가져올 수 없음 / 첫 번째 인증서를 확인할 수 없음: 서버에 중간 CA 인증서가 누락되었거나 클라이언트 신뢰 저장소가 발급 CA를 신뢰하지 않는 경우가 많습니다.
• 인증서가 만료되었거나 아직 유효하지 않습니다. 인증서를 갱신하고 서버와 엄격하게 관리되는 개인 연합 클라이언트 모두에서 시스템 시계를 확인하십시오.
• 자체 서명 인증서: 공용 페더레이션은 일반적으로 이를 거부합니다. 개인 페더레이션의 경우, 검증을 전역적으로 비활성화하는 대신 개인 CA를 사용하고 신뢰를 명시적으로 구성하십시오.

3. 리버스 프록시에서 호스트 이름 불일치를 수정합니다.

클라이언트 측 사이트와 페더레이션 엔드포인트가 서로 다른 가상 호스트를 사용하는 경우 호스트 이름 불일치가 특히 흔히 발생합니다. 예를 들어, 는 example.com웹사이트를 호스팅하고 는 Synapse를 프록시할 수 있습니다 . 파일에서 로 위임하는 matrix.example.com경우 , 해당 호스트의 TLS 엔드포인트는 에 유효한 인증서를 제공해야 합니다 ..well-knownmatrix.example.com:443matrix.example.com

Nginx의 경우, 사용하려던 설정 파일만 검사하는 것이 아니라 활성화된 가상 호스트를 검사해야 합니다.

sudo nginx -T | less

server_name수신 포트와 인증서 경로를 확인하십시오 . 일반적인 TLS 섹션에서는 전체 인증서 체인을 사용합니다.

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

구성 테스트가 성공한 후에만 유효성을 검사하고 다시 로드하십시오.

sudo nginx -t && sudo systemctl reload nginx

Synapse는 일반적인 배포 환경에 리버스 프록시 사용을 권장하며, 일반 클라이언트 포트 443과 기본 페더레이션 포트 8448을 구분합니다. 최신 프록시 요구 사항은 Synapse 공식 리버스 프록시 문서를 참조하십시오.

4. 전체 인증서 체인을 제공합니다.

리프 인증서는 이미 사용 중인 브라우저에서는 올바르게 보일 수 있지만, 서버에서 필요한 중간 인증서를 보내지 않으면 다른 홈서버에서는 작동하지 않을 수 있습니다. Synapse 설명서에는 Synapse 자체를 인증서로 구성할 때 PEM 파일에 전체 인증서 체인이 포함되어야 한다고 명시적으로 나와 있습니다. Certbot을 사용하는 경우 이는 fullchain.pem단순히 .이 아닌 .을 사용해야 함을 의미합니다 cert.pem.

Nginx, Caddy, HAProxy 또는 다른 프록시에서 TLS가 종료되는 경우에도 동일한 원칙이 적용됩니다. 해당 프록시가 올바른 전체 TLS 체인을 표시하도록 구성하십시오. 디스크에 저장된 내용뿐만 아니라 실제로 제공되는 내용을 검사하십시오.

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

리프 인증서 다음에 필요한 중간 인증서가 표시될 것입니다. 클라이언트는 일반적으로 트러스트 스토어를 통해 루트 CA를 이미 신뢰하므로 서버에서 루트 CA를 보낼 필요는 없습니다.

5. DNS 및 Matrix 검색에서 오래된 라우팅 또는 분할 라우팅이 있는지 확인합니다.

한 컴퓨터에서는 인증서가 올바른데도 원격 페더레이션에서 다른 인증서를 보고하는 경우, DNS가 일부 클라이언트를 다른 곳으로 리디렉션하고 있을 수 있습니다. IPv4 및 IPv6 레코드를 모두 확인하고, 원격 홈 서버가 IPv6를 선호하는 경우 유효한 A 레코드가 오래된 AAAA 레코드를 대체할 수 없다는 점을 기억하십시오.

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

또한 의도적으로 사용하는 모든 페더레이션 SRV 레코드를 검사하십시오.

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

최근에 설정을 변경했다면 .well-known캐싱을 허용하세요. Matrix 사양에 따르면 클라이언트는 검색 응답과 실패한 검색 시도까지 일정 기간 동안 캐시할 수 있습니다. 즉, 현재 구성이 올바르더라도 원격 서버는 일시적으로 이전에 검색된 라우팅을 계속 사용할 수 있습니다.

A와 AAAA 인증서가 모두 존재하는 경우, 필요한 경우 각 경로에 대해 TLS 검사를 실행하십시오. 로드 밸런서가 여러 프록시 노드 앞에 있는 경우, 모든 노드가 동일한 최신 인증서와 인증서 체인을 가지고 있는지 확인하십시오.

6. 공개 연합을 약화시키지 않고 개인 CA 신뢰 문제를 해결합니다.

프라이빗 페더레이션은 공용 CA가 적합하지 않을 수 있는 주요한 합법적인 경우입니다. Synapse는 federation_custom_ca_list사용자 지정 인증 기관을 지원합니다. 최신 문서에는 중요한 동작 사항이 명시되어 있습니다. 이 목록은 운영 환경에서 제공하는 CA 인증서를 대체합니다. 따라서 이 목록을 설정하는 경우 실제 배포에 필요한 전체 신뢰 세트를 포함해야 합니다.

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

신뢰 구성을 변경한 후에는 설치 환경에 맞는 서비스 메커니즘을 사용하여 Synapse를 다시 시작하고 로그에서 인증서 오류를 확인하십시오. 컨테이너 배포 환경 또한 특별히 주의해야 합니다. 호스트는 개인 CA를 신뢰하지만 Synapse 컨테이너는 그렇지 않을 수 있습니다. 신뢰 자료가 컨테이너에 마운트되었는지, 그리고 구성된 경로를 컨테이너 내부에서 읽을 수 있는지 확인하십시오.

federation_certificate_verification_whitelistSynapse는 전역 스위치 도 제공 federation_verify_certificates하지만, 공식 문서에서는 이러한 기능을 예외적인 시나리오로 제한하고 있습니다. 전역적으로 인증을 비활성화하면 오류는 사라지지만 근본적인 ID 문제는 해결되지 않습니다. 일반적인 공용 페더레이션의 경우, 인증서 또는 라우팅을 복구하는 것이 좋습니다.

7. 먼저 TLS 계층에서 복구를 확인합니다.

변경 사항을 적용한 후, 이전에 실패했던 OpenSSL 명령어를 정확히 다시 실행하십시오. 목표는 Matrix 검색이 확인하는 엔드포인트에 대한 호스트 이름 및 SSL 인증서 검증이 성공적으로 완료되는 것입니다.

다음으로 페더레이션 엔드포인트에 HTTPS 요청을 보냅니다. 8448 포트의 직접 엔드포인트의 경우 다음과 같습니다.

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

443 포트의 위임된 엔드포인트의 경우:

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

정상적인 TLS 결과는 인증서 검증이 성공적으로 완료되었음을 보여줘야 합니다. 그러면 Matrix 엔드포인트는 인증서 유효성 검사 중에 실패하는 대신 홈서버 또는 프록시 경로에서 HTTP 응답을 반환해야 합니다. 버전 엔드포인트 자체는 연결성 테스트에 유용하지만, 모든 회의실이나 원격 서버가 올바르게 연동된다는 것을 보장하는 것은 아닙니다.

8. Synapse 로그를 확인하고 TLS 오류와 상위 레벨 페더레이션 오류를 구분하십시오.

TLS 검증은 성공했지만 페더레이션이 여전히 실패하는 경우, 이를 인증서 문제로 간주하지 마십시오. 상위 계층으로 이동하여 Synapse 로그에서 DNS 오류, 연결 시간 초과, HTTP 상태 오류, 서명 키 문제, 권한 부여 실패 또는 원격 서버 백오프 문제를 확인하십시오.

systemd 기반 설치에서 일반적인 시작점은 다음과 같습니다.

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

Docker 환경에서는 Synapse 서비스의 컨테이너 로그를 사용하세요. 더 이상 관련성이 없을 수 있는 이전 인증서 메시지에 의존하기보다는 최근 페더레이션 시도 시점의 타임스탬프 주변을 검색하는 것이 좋습니다.

빠른 의사 결정표

문제가 정말로 해결되었는지 어떻게 알 수 있을까요?

"서비스가 오류 없이 재시작됨"을 성공 기준으로 사용하지 마십시오. 안정적인 복구에는 다음 세 가지 확인 가능한 징후가 있습니다. 정확한 페더레이션 호스트 이름이 호스트 이름 검증을 통과해야 하고, 제공된 체인이 신뢰할 수 있는 CA에 대해 유효성 검사를 통과해야 하며, 새로운 페더레이션 HTTPS 요청이 TLS 검증 예외 없이 Synapse에 도달해야 합니다.

이러한 점검 후에도 원격 홈서버 중 하나만 오류가 발생하는 경우, 캐싱, 해당 원격 서버의 트러스트 스토어 또는 엔드포인트별 네트워크 경로 문제를 고려해 보세요. 여러 개의 공용 홈서버에서 동일한 오류가 발생하는 경우, 먼저 자체 인증서, IPv6 경로, 로드 밸런싱 노드 및 검색 구성을 다시 확인하십시오.

운영 시스템에서는 인증서 검증을 활성화 상태로 유지하고 인증서 갱신 과정을 모니터링할 수 있도록 하십시오. 가장 근본적인 해결책은 검증을 비활성화하는 것이 아니라 Matrix 검색, DNS, SNI, 리버스 프록시 및 인증서 체인이 모두 동일한 페더레이션 엔드포인트를 가리키도록 하는 것입니다.