شهادات Certbot wildcard عبر DNS-01

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

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

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

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

كيف يعمل سجل TXT الخاص بـ _acme-challenge

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

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

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

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

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

شاهد الآلية تعمل مرة واحدة: الوضع اليدوي

الوضع اليدوي (manual mode) يجعلك تقوم بتعديل DNS بنفسك، وهذه أفضل طريقة لفهم الآلية قبل أن تؤتمتها:

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

علامات الاقتباس حول wildcard تمنع الصَّدَفة (shell) لديك من معاملة * كنمط أسماء ملفات. يتوقف 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 الخاص به، واضبط تذكيرًا قبل اليوم التسعين بوقت كافٍ، لأن 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 محدودة النطاق (scoped) تعمل بلا مشكلة، لأن مكتبة python3-cloudflare التي تعتمد عليها الإضافة في 24.04 هي 2.11.1، وهي أعلى من 2.3.1 التي تحتاجها الإضافة لدعم الرموز. في إصدارات Ubuntu الأقدم كانت تلك المكتبة أقدم من أن تدعم الرموز، وهذا مصدر التحذيرات التي قد تجدها على الإنترنت حول إجبار إضافة apt على استخدام Global API Key. على 24.04 لم تعد تلك التحذيرات تنطبق.

في لوحة تحكم Cloudflare أنشئ رمز API محدود النطاق، لا 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، وتنتظر تأخيرًا قصيرًا للانتشار (propagation)، ثم تسمح للتحقق بالعمل، ثم تحذف السجلات مجددًا. إن كانت خوادم الأسماء في منطقتك بطيئة في استقبال التغييرات، ارفع مدة الانتظار بالخيار --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؛ ولا يمكنها أن تمتد إلى ذلك المثبَّت عبر apt، ولهذا يجب ألا يتعايش التثبيتان معًا. وإن كان مضيف DNS لديك لا يوفر أي API على الإطلاق، فخياراتك الواقعية هي نقل DNS النطاق إلى مزوّد يوفر واحدة، أو تشغيل خادم أسماء خاص بك وتوجيه إضافة rfc2136 إليه.

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

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

sudo certbot renew --dry-run

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

متى لا تحتاج إلى wildcard

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

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

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

FAQ

هل يمكن لـ Certbot إصدار شهادة wildcard عبر HTTP-01؟

لا. يثبت HTTP-01 السيطرة على اسم مضيف واحد فقط، لأن خادم التحقق يجلب ملف رمز من ذلك الاسم بعينه. تغطي شهادة 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 أقل أمانًا من شهادة عادية؟

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