شهادة wildcard مع Certbot عبر تحدي DNS-01

لماذا تحتاج الشهادة العامة إلى DNS-01

تغطي الشهادة العامة كل نطاق فرعي من المستوى الأول لنطاق معيّن: يطابق *.example.com ‏app.example.com وblog.example.com وأي اسم آخر يقع على بُعد تسمية واحدة. تُصدر Let's Encrypt الشهادات العامة من خلال تحدي DNS-01 فقط، لذلك يجب على Certbot إثبات التحكم في DNS الخاص بالنطاق عبر نشر سجل TXT في _acme-challenge.example.com. لا يمكن لتحدي HTTP-01 استيفاء هذا الشرط، لأن تقديم ملف رمز يثبت التحكم في اسم مضيف واحد، وهو الاسم الذي جلب خادم التحقق الملف منه. الشهادة العامة ادعاء يشمل كل اسم محتمل ضمن النطاق، والسجل العام الوحيد الذي يمثّل مساحة الأسماء بأكملها هو DNS نفسه.

يحدد هذا الشرط كل ما يأتي في هذه الصفحة. لاجتياز DNS-01، يجب أن تتمكن من إنشاء سجلات TXT في منطقة النطاق، يدويًا أو من خلال واجهة برمجة التطبيقات الخاصة بموفر DNS. ينجح المسار اليدوي مرة واحدة ثم يفشل عند التجديد، لسبب محدد موضح أدناه. أما مسار واجهة برمجة التطبيقات، من خلال إضافة DNS لـ Certbot، فيجدد الشهادة دون تدخل، وهو الإعداد الذي ينبغي أن تنتهي إليه.

هذا هو فصل الشهادات العامة في أدلة Certbot لدينا. تتناول Certbot مع nginx على Ubuntu 24.04 وCertbot مع Apache على Ubuntu 24.04 الشهادات العادية لاسم مضيف واحد، وإعداد خادم الويب، وقواعد المنفذ 80.

كيفية عمل سجل TXT لـ _acme-challenge

عندما يطلب Certbot *.example.com، يرد Let's Encrypt برمز عشوائي. يدمج Certbot هذا الرمز مع مفتاح حساب ACME (بيئة إدارة الشهادات تلقائيًا)، ثم يحسب تجزئة للنتيجة باستخدام SHA-256، وينشئ قيمة نصية قصيرة. يجب أن تظهر هذه القيمة كسجل TXT في _acme-challenge.example.com. بعد ذلك، يستعلم Let's Encrypt عن خوادم أسماء النطاق الموثوقة من بنيته التحتية. إذا تطابق السجل الذي يقرأه مع القيمة المتوقعة، فقد أثبتَّ أنك تتحكم في المنطقة، ويُقبل التحكم في المنطقة باعتباره تحكمًا في كل اسم ضمنها.

يتسبب تفصيلان في معظم حالات الفشل:

• يؤدي طلب example.com و*.example.com ضمن الشهادة نفسها إلى تحديين منفصلين، ويكون كلا سجلي TXT في الاسم نفسه، _acme-challenge.example.com. يجب أن يكون السجلان موجودين في الوقت نفسه. إضافة السجل الثاني صحيحة، أما استبدال السجل الأول بالثاني فيؤدي إلى فشل التحدي الأول.
• تقرأ عملية التحقق خوادمك الموثوقة، لكن قد تستغرق لوحات التحكم لدى موفري الخدمة دقيقة أو أكثر لدفع سجل جديد إليها. تحقّق من خارج الشبكة قبل تشغيل التحقق:

dig +short TXT _acme-challenge.example.com @1.1.1.1

عندما يطبع هذا الأمر القيمة التي طلبها Certbot، يمكن أن تنجح عملية التحقق. وعندما لا يطبع شيئًا، انتظر وشغّله مرة أخرى.

راجع التنفيذ مرة واحدة: الوضع اليدوي

يجعلك الوضع اليدوي تعدّل DNS بنفسك. وهذه أفضل طريقة لفهم الآلية قبل أتمتتها:

sudo certbot certonly --manual --preferred-challenges dns -d example.com -d '*.example.com'

تمنع علامات الاقتباس حول wildcard الصدفة من التعامل مع * كنمط لأسماء الملفات. يتوقف Certbot ويعرض التعليمات:

Please deploy a DNS TXT record under the name:
_acme-challenge.example.com.
with the following value:
Jx9mQ2wLr8vTn5cKp0aYdG3hB7fZs4eN1oiRuXqMk6E

أنشئ سجل TXT هذا في لوحة موفر DNS لديك، وتحقق من ظهوره باستخدام الأمر dig أعلاه، ثم اضغط Enter فقط بعد ذلك. يطلب هذا التشغيل النطاق الأساسي وwildcard، لذلك يعرض Certbot المطالبة مرتين. اترك السجلين موجودين حتى يكتمل الإصدار. ينتهي التنفيذ الناجح بالأسطر المعتادة:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem

لماذا لا يستطيع الوضع اليدوي تجديد الشهادة تلقائيًا

كل عملية تجديد هي تحدٍّ جديد باستخدام رمز مميز جديد، لذلك تتغير قيمة TXT في كل مرة. تصبح السجل الذي ألصقته اليوم عديم الفائدة بعد 60 يومًا. يشغّل مؤقت التجديد Certbot دون تدخل مرتين يوميًا، ولا يوجد أحد أمام لوحة المفاتيح للصق القيمة الجديدة. لذلك يفشل تجديد الشهادة التي أُصدرت يدويًا ويظهر هذا الخطأ بالضبط:

Failed to renew certificate example.com with error: The manual plugin is not
working; there may be problems with your existing configuration.
The error was: PluginError('An authentication script must be provided with
--manual-auth-hook when using the manual plugin non-interactively.')

يمكنك تلبية هذا المتطلب بكتابة نصوص --manual-auth-hook تستدعي API الخاص بموفر DNS، لكنك عندئذ تعيد بناء إضافة DNS يدويًا. استخدم الوضع اليدوي لتعلّم سير العملية، أو لإصدار واحد فعلي لنطاق لا يمكنك أتمتة DNS الخاص به بعد. اضبط تذكيرًا قبل اليوم 90 بوقت كافٍ، لأن Let's Encrypt لم يعد يرسل رسائل بريد إلكتروني بانتهاء الصلاحية. في جميع الحالات الأخرى، استخدم إضافة.

مسار الإضافة: certbot-dns-cloudflare على Ubuntu 24.04

تحتفظ إضافة DNS ببيانات اعتماد API الخاصة بمزوّد DNS لديك، وتنفّذ عملية سجل TXT كاملة بنفسها عند الإصدار، ثم عند كل تجديد. نستخدم Cloudflare هنا كمثال تطبيقي، لأنها إضافة المزوّد التي يحتاج إليها معظم المستخدمين، ولأنها متوفرة ضمن حزم Ubuntu.

توصي أدلة Certbot لدينا باستخدام حزم apt على Ubuntu 24.04، وينطبق ذلك أيضًا على Cloudflare:

sudo apt update
sudo apt install certbot python3-certbot-dns-cloudflare

ملاحظة مهمة بشأن الإصدارات. يوفّر مستودع 24.04 هذه الإضافة بالإصدار 2.0.0 إلى جانب Certbot 2.9.0؛ ويعرض apt policy python3-certbot-dns-cloudflare الإصدار الموجود لديك. لا يسبب اختلاف الإصدار مشكلة، وتعمل رموز API المقيّدة، لأن مكتبة python3-cloudflare الأساسية في 24.04 هي بالإصدار 2.11.1، وهو أحدث من الإصدار 2.3.1 الذي تحتاج إليه الإضافة لدعم الرموز. في إصدارات Ubuntu الأقدم، كانت هذه المكتبة قديمة جدًا ولا تدعم الرموز. ومن هنا ظهرت التحذيرات المتداولة على الإنترنت بشأن إجبار إضافة apt على استخدام Global API Key. لا تنطبق هذه التحذيرات على 24.04.

أنشئ رمز API مقيّد النطاق في لوحة Cloudflare، وليس Global API Key: افتح My Profile، ثم API Tokens، ثم Create Token، وحدد الإذن الوحيد Zone / DNS / Edit، وقيّده بالمنطقة الوحيدة التي ستصدر الشهادة لها. ضعه في ملف لا يستطيع قراءته إلا root:

sudo mkdir -p /root/.secrets
sudo tee /root/.secrets/cloudflare.ini > /dev/null <<'EOF'
dns_cloudflare_api_token = paste_your_scoped_token_here
EOF
sudo chmod 600 /root/.secrets/cloudflare.ini

يتحقق Certbot من الوضع، ويصدر تحذيرًا بشأن Unsafe permissions on credentials configuration file إذا كان الملف قابلًا للقراءة من مستخدمين آخرين. أصدر الشهادة الآن:

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
  -d example.com -d '*.example.com'

تنشئ الإضافة سجلات TXT عبر API، وتنتظر فترة قصيرة لانتشار التغيير، ثم تسمح بإجراء التحقق، وبعد ذلك تحذف السجلات. إذا كانت خوادم الأسماء في منطقتك بطيئة في التقاط التغييرات، فزد مدة الانتظار باستخدام --dns-cloudflare-propagation-seconds 60. تُحفظ الشهادة في /etc/letsencrypt/live/example.com/، ثم توجّه nginx أو Apache إلى fullchain.pem وprivkey.pem تمامًا كما توضّح الأدلة الأساسية، بما في ذلك deploy hook.

إذا لم تكن إضافة مزودك موجودة في apt

يحتوي أرشيف 24.04 على إضافات لعدد محدود من المزودين فقط، ومن بينها Cloudflare وRoute 53 وDigitalOcean والواجهة العامة RFC 2136. شغّل apt search certbot-dns لعرض القائمة. إذا لم يكن مزودك موجودًا، فهذه هي الحالة الوحيدة التي نعدل فيها نصيحتنا باتباع apt أولًا: ثبّت Certbot والإضافة من snap بدلًا من ذلك، وأزل Certbot المثبت من apt أولًا حتى لا يتنافس مؤقتا تجديد على /etc/letsencrypt:

sudo apt remove certbot python3-certbot-dns-cloudflare
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-dns-yourprovider

تتصل إضافة snap ببرنامج Certbot المثبت من snap فقط. ولا يمكنها توسيع Certbot المثبت من apt. لذلك يجب ألا يتعايش التثبيتان. وإذا لم يوفر مضيف DNS لديك أي واجهة API، فخياراتك العملية هي نقل DNS للنطاق إلى مزود يوفر واجهة API، أو تشغيل خادم أسماء خاص بك وتوجيه إضافة rfc2136 إليه.

التجديد: أثبته الآن، لا بعد 60 يومًا

يسجل Certbot كيفية إصدار كل شهادة في /etc/letsencrypt/renewal/example.com.conf، بما في ذلك authenticator = dns-cloudflare ومسار بيانات الاعتماد، لذلك يجدّدها المؤقت القياسي الذي يعمل مرتين يوميًا من دون أي تدخل منك. اختبر العملية كاملة باستخدام بيئة التجهيز:

sudo certbot renew --dry-run

تعني نتيجة النجاح أن بيانات الاعتماد تعمل وأن عملية التحقق اكتملت من البداية إلى النهاية؛ وسيسلك التجديد الفعلي بعد 60 يومًا المسار نفسه. هناك خطوتان إضافيتان يجدر تنفيذُهما اليوم. أولًا، لا يغيّر تجديد الشهادة الموجودة على القرص شيئًا حتى يعيد خادم الويب تحميلها، لذلك اربط deploy hook الموضّح في دليلي nginx وApache. ثانيًا، تعامل مع ملف بيانات الاعتماد بحذر: يستطيع أي شخص يمكنه قراءته تعديل منطقة DNS، وهذا يكفي لإعادة توجيه بريدك أو اجتياز تحديات DNS-01 الخاصة به. اضبط صلاحياته على mode 600 داخل /root، وقيّد الرمز المميز بمنطقة واحدة، وقم بتدويره إذا اشتبهت في أي وقت بتسرّبه.

متى لا تحتاج إلى شهادة wildcard

تُعد شهادة wildcard الخيار المناسب للعديد من النطاقات الفرعية، أو للنطاقات الفرعية التي لا يمكنك التنبؤ بها. لكنها ليست الخيار الافتراضي الصحيح في الحالات الأخرى.

• نطاق فرعي واحد، أو عدد قليل من النطاقات الفرعية المعروفة: تكون شهادة SAN (subject alternative name) العادية أبسط. تغطي certbot --nginx -d example.com -d www.example.com -d app.example.com ما يصل إلى 100 اسم عبر HTTP-01 العادي، ولا توجد بيانات اعتماد لواجهة DNS API على الخادم.
• تطابق شهادة wildcard مستوى واحدًا فقط. لا تغطي *.example.com النطاق الأساسي example.com، ولذلك تطلب الأوامر أعلاه كليهما، كما أنها لا تغطي a.b.example.com أيضًا؛ وهذا يتطلب *.b.example.com.
• يوجد مفتاح خاص واحد خلف كل نطاق فرعي. إذا تعرض الجهاز الذي يحتفظ به للاختراق، تتأثر جميع الأسماء التي تغطيها شهادة wildcard في الوقت نفسه.
• إذا كان Traefik ينهي TLS (أمان طبقة النقل) لحاوياتك، فلا تحتاج إلى Certbot على الإطلاق: يطلب Traefik شهادات wildcard بنفسه عبر DNS-01، باستخدام النوع نفسه من رمز موفر الخدمة.

تظهر فائدة شهادة wildcard فعليًا في النطاقات الفرعية الخاصة بكل عميل أو تطبيق، والتي تُنشأ بسرعة أكبر مما تريد معه إعادة إصدار الشهادات، وفي المضيفات الداخلية التي لا تحتوي على المنفذ العام 80، مثل الخدمات التي لا يمكن الوصول إليها إلا عبر شبكة WireGuard VPN. لا يتصل DNS-01 أبدًا بالمضيف الذي تُصدر له الشهادة، ولذلك يمكن حتى لجهاز خاص بالكامل الاحتفاظ بشهادة موثوقة علنًا.

FAQ

هل يستطيع Certbot إصدار شهادة wildcard باستخدام HTTP-01؟

لا. يثبت HTTP-01 التحكم في اسم مضيف واحد، لأن خادم التحقق يجلب ملف token من ذلك الاسم المحدد. تغطي wildcard كل الأسماء ضمن النطاق، لذلك تتطلب Let's Encrypt تحدي DNS-01، بينما تعتمد أدوات المصادقة --nginx و--apache و--webroot و--standalone جميعها على HTTP. المسار الوحيد هو إنشاء سجل TXT في _acme-challenge.example.com، يدويًا أو باستخدام إضافة DNS.

هل تغطي شهادة wildcard النطاق الجذر؟

لا. تطابق wildcard تسمية واحدة بالضبط، لذلك تغطي *.example.com ‏www.example.com، لكنها لا تغطي example.com المجرد، ولا a.b.example.com. اطلب الاسمين في شهادة واحدة باستخدام -d example.com -d '*.example.com'. يؤدي ذلك إلى إنشاء تحديين، ويكون سجلا TXT كلاهما في الاسم _acme-challenge.example.com نفسه، لذلك أضف السجل الثاني من دون حذف الأول.

لماذا لا تتجدد شهادة wildcard تلقائيًا؟

لأنها أُصدرت باستخدام --manual. يحتاج كل تجديد إلى قيمة TXT جديدة تمامًا، ولا يستطيع المؤقت غير التفاعلي إدخالها، لذلك يتوقف التجديد مع الخطأ An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. أعد إصدار الشهادة باستخدام إضافة DNS مثل certbot-dns-cloudflare، أو وفّر نصي --manual-auth-hook و--manual-cleanup-hook لتعديل السجل عبر API الخاص بموفر الخدمة.

كم يستغرق ظهور سجل TXT ‏_acme-challenge؟

يعتمد ذلك على موفر DNS لديك، وقد يستغرق من بضع ثوانٍ إلى عدة دقائق. يقرأ التحقق خوادم الأسماء الموثوقة لمنطقتك، لذلك افحص باستخدام dig +short TXT _acme-challenge.example.com @1.1.1.1 وانتظر حتى تظهر القيمة المتوقعة قبل متابعة التشغيل اليدوي. عند استخدام إضافة، زد مدة الانتظار المضمنة عبر خيار انتشار الإضافة، مثل --dns-cloudflare-propagation-seconds 60، إذا أبلغ التحقق عن عدم العثور على السجل.

هل شهادة wildcard أقل أمانًا من الشهادة العادية؟

التشفير متماثل. تكمن الاختلافات في التشغيل: يغطي مفتاح خاص واحد كل النطاقات الفرعية، لذلك يمتد أثر الاختراق إلى نطاق أوسع، كما أن بيانات اعتماد DNS API التي تتطلبها الأتمتة تُعد سرًا حساسًا مخزنًا على الخادم. إذا كنت تشغّل عددًا قليلًا من النطاقات الفرعية المعروفة، فتتجنب شهادة SAN كلا المشكلتين، ولذلك يوصي هذا الدليل بتجاوز wildcard في هذه الحالة.