הנפקת תעודת wildcard ב-Certbot עם 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 מוכיח שליטה על hostname אחד בלבד, זה ששרת האימות משך ממנו את הקובץ. wildcard הוא טענה לגבי כל שם אפשרי תחת הדומיין, והרשומה הציבורית היחידה שמייצגת את כל מרחב השמות היא ה-DNS עצמו.

דרישה זו קובעת את כל שאר הפרקים בעמוד זה. כדי לעבור את DNS-01 עליך להיות מסוגל ליצור רשומות TXT באזור (zone) של הדומיין, באופן ידני או באמצעות ה-API של ספק ה-DNS שלך. הדרך הידנית עובדת פעם אחת ואז נכשלת בזמן החידוש, מסיבה מוגדרת להלן. הדרך באמצעות ה-API, באמצעות plugin DNS של Certbot, מאפשרת חידוש אוטומטי, וזו ההגדרה המומלצת.

זהו פרק ה-wildcard במדריכי ה-Certbot שלנו. תעודות רגילות עבור hostname בודד, הגדרות web server וכללי port 80 מפורטים ב-Certbot with nginx on Ubuntu 24.04 וב-Certbot with Apache on Ubuntu 24.04.

אופן הפעולה של רשומת ה- _acme-challenge TXT

כאשר Certbot מבקש את *.example.com, Let's Encrypt משיבה עם טוקן (token) אקראי. Certbot משלב את הטוקן עם מפתח חשבון ה-ACME (automatic certificate management environment) שלך, מבצע hash לתוצאה באמצעות SHA-256, ומייצר ערך טקסט קצר. ערך זה חייב להופיע כרשומת TXT ב-_acme-challenge.example.com. לאחר מכן, Let's Encrypt מבצע שאילתה לשרתי השמות (authoritative name servers) של הדומיין שלך מתוך התשתית שלה. אם הרשומה שנקראת תואמת לערך הצפוי, הוכחת שאתה שולט ב-zone, ושליטה ב-zone נחשבת לשליטה בכל השמות תחתיו.

שני פרטים גורמים לרוב הכשלים:

• בקשת example.com ו-*.example.com באותו תעודה פירושה שני אתגרים נפרדים, ושתי רשומות ה-TXT נמצאות תחת אותו שם, _acme-challenge.example.com. שתיהן חייבות להתקיים בו-זמנית. הוספת הרשומה השנייה היא הפעולה הנכונה; החלפת הרשומה הראשונה בשנייה תגרום לכשל באתגר הראשון.
• תהליך האימות קורא מהשרתים המורשים שלך, אך ללוחות הבקרה של ספקי השירות עשוי לקחת דקה או יותר כדי להפיץ רשומה חדשה אליהם. בדקו מבחוץ לפני שתפעילו את האימות:

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

כאשר הפקודה מדפיסה את הערך ש-Certbot ביקש, האימות יכול להצליח. אם היא לא מדפיסה דבר, המתינו והריצו אותה שוב.

See it work once: manual mode

Manual mode requires you to perform the DNS edit manually. This is the best way to understand the mechanism before automating it:

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

הגרשיים סביב ה-wildcard מונעים מה-shell להתייחס ל-* כאל תבנית שם קובץ (filename pattern). Certbot ישהה את הפעולה ויציג הוראות:

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

צור את רשומת ה-TXT בלוח הבקרה של ספק ה-DNS שלך. ודא שהיא נראית באמצעות הפקודה dig המופיעה לעיל, ורק אז לחץ על Enter. מכיוון שפעולה זו מבקשת גם את ה-bare domain וגם את ה-wildcard, Certbot יבקש פעמיים; השאר את שתי הרשומות פעילות עד לסיום תהליך ההנפקה. ההצלחה תופיע עם השורות המוכרות:

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

מדוע מצב ידני (manual mode) אינו יכול להתחדש באופן עצמאי

כל חידוש הוא אתגר חדש עם token חדש, לכן ערך ה-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.')

ניתן לעמוד בדרישה זו על ידי כתיבת scripts של --manual-auth-hook שקוראים ל-API של ספק ה-DNS שלך, אך במצב זה אתה בונה DNS plugin באופן ידני. השתמש במצב ידני כדי ללמוד את תהליך העבודה, או עבור מקרה חד-פעמי אמיתי עבור דומיין שעדיין לא ניתן לאוטומציה של ה-DNS שלו, וקבע תזכורת הרבה לפני היום ה-90, מכיוון ש-Let's Encrypt כבר לא שולחת אימיילים על פקיעת תוקף. לכל שאר המקרים, השתמש ב-plugin.

הדרך באמצעות תוסף: certbot-dns-cloudflare ב-Ubuntu 24.04

תוסף DNS מחזיק בפרטי אימות (API credentials) של ספק ה-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 מציגה את הגרסה המותקנת אצלך. חוסר התאמה זה אינו מזיק, ו-scoped API tokens יעבדו, מכיוון שספריית ה-python3-cloudflare בגרסה 24.04 היא 2.11.1, גבוהה מהגרסה 2.3.1 שהתוסף דורש לתמיכה ב-tokens. בגרסאות Ubuntu ישנות יותר, הספרייה הייתה ישנה מדי עבור tokens, וזה המקור לאזהרות שניתן למצוא באינטרנט לגבי שימוש ב-Global API Key בתוסף ה-apt. בגרסה 24.04 אזהרות אלו כבר אינן רלוונטיות.

בממשק הניהול של Cloudflare, צור scoped API token ולא את ה-Global API Key: בחר ב-My Profile, לאחר מכן ב-API Tokens, ואז ב-Create Token. הגדר הרשאה אחת בלבד: Zone / DNS / Edit, המוגבלת לאזור (zone) שאתה מנפק עבורו. שמור את הנתונים בקובץ שרק משתמש 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), מאפשר לתהליך האימות לרוץ, ולאחר מכן מוחק את הרשומות. אם שרתי ה-name servers של ה-zone שלך איטיים בקליטת שינויים, הגדל את זמן ההמתנה באמצעות --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 כדי ששני timers של חידוש לא יתנגשו על /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 מתחבר אך ורק ל-snap Certbot; הוא אינו יכול להרחיב את הגרסה של apt, ולכן שתי ההתקנות אינן יכולות להתקיים יחד. אם מארח ה-DNS שלך אינו מציע API כלל, האפשרויות המציאותיות שלך הן להעביר את ה-DNS של הדומיין לספק עם API, או להריץ name server משלך ולכוון את התוסף rfc2136 אליו.

חידוש: בדקו זאת עכשיו, לא בעוד 60 יום

Certbot מתעד את אופן הנפקת כל תעודה ב-/etc/letsencrypt/renewal/example.com.conf, כולל authenticator = dns-cloudflare ונתיב האישורים (credentials path). בזכות זאת, ה-timer הסטנדרטי הפועל פעמיים ביום מחדש את התעודה ללא צורך בהתערבותכם. ניתן לבצע תרגול מלא מול סביבת ה-staging:

sudo certbot renew --dry-run

הצלחה בתהליך פירושה שהאישורים תקינים ותהליך האימות הושלם במלואו; החידוש האמיתי בעוד 60 יום יתבצע באותו אופן. מומלץ לבצע שני צעדים נוספים כבר היום. ראשית, תעודה חדשה שנשמרת על הדיסק לא תשנה דבר עד שהשרת (web server) יטען אותה מחדש; לכן, יש להגדיר את ה-deploy hook המתואר במדריכים של nginx ו-Apache. שנית, יש לשמור על קובץ האישורים: לכל מי שיש לו הרשאת קריאה לקובץ, יש יכולת לערוך את אזור ה-DNS שלכם, מה שמאפשר להם להפנות מחדש את המייל שלכם או לעבור את אתגרי DNS-01 משלהם. שמרו על הרשאות mode 600 תחת /root, הגדירו את ה-token לאזור (zone) אחד בלבד, ורעננו אותו (rotate) אם יש חשד לדליפה.

מתי אין צורך ב-wildcard

wildcard הוא הכלי המתאים עבור מספר רב של subdomains, או עבור subdomains שאינם ניתנים לחיזוי. הוא אינו הבחירה הנכונה כברירת מחדל לכל דבר אחר.

• subdomain אחד, או קבוצה קטנה של subdomains ידועים: תעודת SAN (subject alternative name) רגילה היא פשוטה יותר. certbot --nginx -d example.com -d www.example.com -d app.example.com תומכת בעד 100 שמות באמצעות HTTP-01, ולא נדרש להחזיק הרשאות DNS API על השרת.
• wildcard מתאים בדיוק ל-label אחד. *.example.com אינו מכסה את example.com, ולכן הפקודות לעיל מבקשות את שניהם, והוא אינו מכסה גם את a.b.example.com; לכך נדרש *.b.example.com.
• לכל subdomain יש מפתח פרטי (private key) משלו. אם המכונה המחזיקה אותו נפרצת, כל השמות שה-wildcard מכסה נפגעים בבת אחת.
• אם Traefik מבצע TLS (transport layer security) עבור ה-containers שלך, אין צורך ב-Certbot: Traefik מבקש תעודות wildcard בעצמו באמצעות DNS-01, תוך שימוש באותו סוג של provider token.

מתי wildcard באמת משתלם: עבור subdomains של לקוחות או אפליקציות שנוצרים במהירות גבוהה מדי עבור הנפקת תעודות מחדש, ועבור hosts פנימיים ללא port 80 פתוח לציבור, כגון שירותים הנגישים רק דרך WireGuard VPN. DNS-01 אינו מתחבר למכונה שעליה מונפקת התעודה, לכן גם מכונה פרטית לחלוטין יכולה להחזיק תעודה המהימנה על ידי גורם ציבורי.

FAQ

האם Certbot יכול להנפיק wildcard certificate באמצעות HTTP-01?

לא. HTTP-01 מוכיח שליטה על hostname אחד בלבד, מכיוון ששרת האימות מוריד קובץ token מהשם הספציפי הזה. wildcard מכסה כל שם תחת הדומיין, לכן Let's Encrypt מחייבת את ה-DNS-01 challenge עבורו. המאמתים --nginx, --apache, --webroot ו---standalone הם כולם מבוססי HTTP. הדרך היחידה היא רשומת TXT ב-_acme-challenge.example.com, שמוצבת ידנית או באמצעות DNS plugin.

האם wildcard certificate מכסה את ה-root domain?

לא. ה-wildcard מתאים בדיוק ל-label אחד, לכן *.example.com מכסה את www.example.com אך לא את ה-bare example.com, ולא את a.b.example.com. ניתן לבקש את שני השמות תחת תעודה אחת באמצעות -d example.com -d '*.example.com'. פעולה זו יוצרת שני challenges, ושתי רשומות ה-TXT נמצאות תחת אותו שם _acme-challenge.example.com, לכן יש להוסיף את הרשומה השנייה מבלי למחוק את הראשונה.

מדוע ה-wildcard certificate שלי לא מתחדש באופן אוטומטי?

מכיוון שהוא הונפק עם --manual. כל חידוש דורש ערך TXT חדש לחלוטין, ולטיימר ה-unattended אין אפשרות להדביק אותו, לכן החידוש נעצר עם השגיאה An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. ניתן להנפיק מחדש את התעודה באמצעות DNS plugin כגון certbot-dns-cloudflare, או לספק סקריפטים של --manual-auth-hook ו---manual-cleanup-hook שעורכים את הרשומה דרך ה-API של הספק שלך.

כמה זמן לוקח לרשומת ה-_acme-challenge TXT להופיע?

זה תלוי בספק ה-DNS שלך: בין שניות בודדות לכמה דקות. תהליך האימות קורא מהשרתים ה-authoritative של ה-zone שלך, לכן יש לוודא מול dig +short TXT _acme-challenge.example.com @1.1.1.1 ולהמתין עד שהערך הצפוי מופיע לפני המשך הרצה ידנית. בשימוש ב-plugin, ניתן להגדיל את זמן ההמתנה המובנה באמצעות אופציית ה-propagation של ה-plugin, לדוגמה --dns-cloudflare-propagation-seconds 60, אם האימות מדווח שהרשומה לא נמצאה.

האם wildcard certificate פחות מאובטח מתעודה רגילה?

הקריפטוגרפיה זהה. ההבדלים הם תפעוליים: מפתח פרטי אחד מכסה כל subdomain, ולכן פריצה יכולה להגיע לתחום רחב יותר. בנוסף, פרטי ה-DNS API הנדרשים לאוטומציה הם סוד רגיש המאוחסן על השרת. אם אתה מפעיל רק מספר subdomains ידועים, תעודת SAN תמנע את שתי הבעיות הללו, וזה המצב שבו המדריך הזה ממליץ לדלג על ה-wildcard.