إصلاح أخطاء "فشل التحقق من شهادة SSL" في Matrix Synapse

قد يبدو عطل Matrix Synapse الشائع بسيطًا للوهلة الأولى: إذ يمكن للعملاء المحليين تسجيل الدخول، ويكون خادم الوكيل العكسي الخاص بك متصلًا بالإنترنت، وقد يبدو Synapse نفسه سليمًا، ومع ذلك لا تستطيع الخوادم المنزلية البعيدة الاتصال بك. قد تحتوي سجلات أحد الجانبين على عبارات مثل certificate verify failed" فشل الاتصال hostname mismatch" أو unable to get local issuer certificate"فشل طلب الاتصال" أو "فشل طلب اتصال عام ناتج عن التحقق من TLS".

أسرع طريقة لحل هذه المشكلة هي اختبار اسم المضيف والمنفذ اللذين يُشير إليهما اكتشاف اتحاد Matrix، ثم إصلاح الشهادة أو سلسلة الشهادات أو مسار الاكتشاف الخاطئ. لا تبدأ بتعطيل عمليات التحقق من الشهادات. حركة مرور خادم Matrix من خادم إلى خادم تتم عبر HTTPS، وتتطلب مواصفات Matrix أن يُقدّم الوجهة شهادة موقعة من جهة إصدار شهادات موثوقة. كما يُبقي Synapse التحقق من شهادات الاتحاد الصادرة مُفعّلاً افتراضيًا. راجع مواصفات واجهة برمجة تطبيقات خادم-خادم Matrix ووثائق تكوين 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 .well-knownبالتفويض في عمليات النشر النموذجية لأنه أسهل في الفهم والتكوين بشكل صحيح. تم توثيق السلوك الموثوق في اكتشاف الخادم في مواصفات Matrix وتفويض الاتحاد في Synapse .

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

يمكن أن تبدو الاستجابة المفوضة على النحو التالي:

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

إذا كان الملف مفقودًا أو غير صالح، فلا تفترض أن ذلك بحد ذاته خلل في بروتوكول TLS. لدى Matrix قواعد اكتشاف احتياطية. المهم هو معرفة اسم المضيف والمنفذ اللذين سيتصل بهما الخادم البعيد في النهاية.

2. إعادة إنتاج فشل التحقق من الشهادة باستخدام OpenSSL

بمجرد معرفة نقطة نهاية الاتحاد المتوقعة، اختبرها مباشرةً باستخدام SNI والتحقق من اسم المضيف. هذا يفصل مشكلة هوية TLS عن مشكلة تطبيق 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

ركز على نتيجة التحقق النهائية والأسماء البديلة لموضوع الشهادة. قد ينجح الاتصال على مستوى بروتوكولي TCP وTLS مع فشل التحقق من الهوية. لذا، فإنّ "المنفذ مفتوح" ليس كافيًا.

ما تعنيه عادةً أكثر أخطاء OpenSSL شيوعًا

• عدم تطابق اسم المضيف: قام الخادم الوكيل العكسي بتقديم شهادة لاسم مضيف مختلف، أو أن سجل الاكتشاف الخاص بك يوجه الاتحاد إلى اسم مضيف غير مشمول بالشهادة.
• تعذر الحصول على شهادة المصدر المحلي / تعذر التحقق من الشهادة الأولى: غالبًا ما يكون الخادم يفتقر إلى شهادة CA وسيطة في السلسلة، أو أن مخزن ثقة العميل لا يثق في CA المصدر.
• انتهت صلاحية الشهادة / لم تصبح صالحة بعد: قم بتجديد الشهادة وتحقق أيضًا من ساعة النظام على كل من الخادم وأي عميل اتحاد خاص خاضع لرقابة مشددة.
• الشهادة الموقعة ذاتيًا: عادةً ما يرفضها الاتحاد العام. أما بالنسبة للاتحاد الخاص، فاستخدم جهة إصدار شهادات خاصة وقم بضبط الثقة بشكل صريح بدلاً من تعطيل التحقق بشكل عام.

3. إصلاح عدم تطابق اسم المضيف في الخادم الوكيل العكسي

يُعدّ عدم تطابق اسم المضيف شائعًا بشكل خاص عندما يستخدم الموقع المُوجّه للعميل ونقطة نهاية الاتحاد مضيفات افتراضية مختلفة. على سبيل المثال، example.comقد يستضيف موقع ويب بينما matrix.example.comيقوم خادم وكيل Synapse بذلك. إذا كان .well-knownملفك يُفوّض إلى matrix.example.com:443، فيجب أن تُقدّم نقطة نهاية TLS على ذلك المضيف شهادة صالحة لـ matrix.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.

ينطبق المبدأ نفسه عندما ينتهي بروتوكول TLS عند Nginx أو Caddy أو HAProxy أو أي خادم وكيل آخر: اضبط هذا الخادم الوكيل لعرض سلسلة الخوادم الكاملة الصحيحة. افحص ما يتم تقديمه فعليًا، وليس فقط ما هو موجود على القرص.

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

يجب أن ترى شهادة الطرفية متبوعةً بالشهادة أو الشهادات الوسيطة المطلوبة. لا يحتاج الخادم عادةً إلى إرسال شهادة المرجع المصدق الجذرية لأن العملاء عادةً ما يثقون بالفعل في شهادات المرجع المصدق الجذرية من خلال مخزن الثقة الخاص بهم.

5. تحقق من نظام أسماء النطاقات (DNS) واكتشاف المصفوفة بحثًا عن توجيهات قديمة أو مجزأة

إذا كانت الشهادة صحيحة على جهاز واحد، ولكن الاتحاد البعيد لا يزال يُبلغ عن شهادة مختلفة، فقد يكون نظام أسماء النطاقات (DNS) يُوجّه بعض العملاء إلى مكان آخر. تحقق من سجلات IPv4 وIPv6، وتذكر أن سجل A صالحًا لا يُعوّض عن سجل AAAA قديم إذا كانت خوادم الإنترنت البعيدة تُفضّل IPv6.

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. إصلاح الثقة في هيئات التصديق الخاصة دون إضعاف الاتحاد العام

يُعدّ الاتحاد الخاص الحالة الرئيسية المشروعة التي قد لا يكون فيها استخدام هيئة إصدار شهادات عامة مناسبًا. يوفر Synapse federation_custom_ca_listإمكانية تخصيص هيئات إصدار الشهادات. تشير الوثائق الحالية إلى سلوك مهم: تحل هذه القائمة محل شهادات هيئة إصدار الشهادات التي توفرها بيئة التشغيل. لذلك، إذا قمتَ بتعيينها، فتأكد من تضمين مجموعة الثقة الكاملة التي يتطلبها النشر الخاص بك.

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

بعد تغيير إعدادات الثقة، أعد تشغيل Synapse باستخدام آلية الخدمة الخاصة بتثبيتك، وتحقق من سجلات النظام بحثًا عن أخطاء في الشهادات. يجب إيلاء اهتمام خاص أيضًا لعمليات نشر الحاويات: فقد يثق المضيف بشهادة مصادقة خاصة بينما لا تثق بها حاوية Synapse. تأكد من تحميل مواد الثقة داخل الحاوية، وأن المسار المُكوّن قابل للقراءة من داخلها.

يُتيح برنامج Synapse أيضًا إمكانية تعطيل التحقق federation_certificate_verification_whitelistالعام federation_verify_certificates، لكن الوثائق الرسمية تُقيّد استخدامه في حالات استثنائية. قد يؤدي تعطيل التحقق العام إلى اختفاء الخطأ مع بقاء مشكلة الهوية الأساسية دون حل. في حالة الاتحاد العام العادي، يُنصح بإصلاح الشهادة أو التوجيه.

7. تحقق من الإصلاح على مستوى طبقة TLS أولاً

بعد إجراء التغييرات، كرر تنفيذ أمر OpenSSL الذي فشل سابقًا. الهدف هو التحقق بنجاح من اسم المضيف وسلسلة التحقق لنقطة النهاية التي يُشير إليها اكتشاف المصفوفة.

ثم قم بإرسال طلب 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 الخاصة بك. ابحث في نطاق الطابع الزمني لمحاولة ربط جديدة بدلاً من الاعتماد على رسائل الشهادات القديمة التي قد لا تكون ذات صلة.

جدول اتخاذ القرارات السريعة

كيف تتأكد من حل المشكلة فعلاً؟

لا تستخدم عبارة "أُعيد تشغيل الخدمة بدون أخطاء" كمعيار للنجاح. للإصلاح الموثوق ثلاث علامات واضحة: اجتياز اسم مضيف الاتحاد لعملية التحقق من اسم المضيف، وتأكيد صحة سلسلة الخدمة لدى جهة إصدار شهادات موثوقة، ووصول طلب HTTPS جديد من الاتحاد إلى Synapse بدون استثناء في عملية التحقق من TLS.

إذا استمر فشل خادم منزلي بعيد واحد فقط بعد هذه الفحوصات، ففكّر في التخزين المؤقت، أو مخزن الشهادات الموثوقة الخاص بذلك الخادم البعيد، أو مسار الشبكة الخاص بنقطة النهاية. أما إذا فشلت عدة خوادم منزلية عامة غير مرتبطة بنفس الطريقة، فأعد فحص شهادتك، ومسار IPv6، وعُقد موازن الأحمال، وإعدادات الاكتشاف أولاً.

بالنسبة لأنظمة الإنتاج، أبقِ التحقق من الشهادات مُفعّلاً واجعل عملية تجديد الشهادات قابلة للمراقبة. الحل الأمثل ليس تعطيل التحقق، بل ضمان أن يصف كل من اكتشاف المصفوفة، ونظام أسماء النطاقات (DNS)، ومؤشر اسم الخادم (SNI)، والوكيل العكسي، وسلسلة الشهادات، نقطة نهاية الاتحاد نفسها.