Certbot ile DNS-01 kullanarak wildcard sertifikası alma

Wildcard sertifikası neden DNS-01 gerektirir

Wildcard sertifikası, bir alan adının tüm birinci seviye alt alan adlarını kapsar: *.example.com, app.example.com, blog.example.com ve bir etiket derinliğindeki diğer tüm isimlerle eşleşir. Let’s Encrypt, wildcard sertifikalarını yalnızca DNS-01 doğrulaması ile düzenler; bu nedenle Certbot, _acme-challenge.example.com adresinde bir TXT kaydı yayınlayarak alan adının DNS kontrolüne sahip olduğunu kanıtlamalıdır. HTTP-01 doğrulaması bu işlem için uygun değildir; çünkü bir token dosyası sunmak, yalnızca doğrulama sunucusunun dosyayı çektiği tek bir ana bilgisayar adının kontrolünü kanıtlar. Wildcard, alan adının bir seviye altındaki tüm olası isimler için bir hak iddiasıdır ve tüm isim alanını temsil eden tek genel kayıt DNS'in kendisidir.

Bu tek gereksinim, bu sayfadaki diğer her şeyi belirler. DNS-01 doğrulamasını geçmek için, alan adının bölgesinde veya _acme-challenge ile CNAME üzerinden işaret edilen (aşağıda açıklanmıştır) ayrı bir doğrulama bölgesinde, manuel olarak veya DNS sağlayıcınızın API'si (uygulama programlama arayüzü) aracılığıyla TXT kayıtları oluşturabilmeniz gerekir. Manuel yöntem bir kez çalışır ancak yenileme sırasında başarısız olur; bunun somut nedeni aşağıda gösterilmiştir. Bir Certbot DNS eklentisi aracılığıyla kullanılan API yöntemi ise otomatik olarak yenilenir ve ulaşmanız gereken yapı budur.

Bu bölüm, Certbot rehberlerimizin wildcard kısmıdır. Sıradan tek ana bilgisayar adli sertifikalar, web sunucusu yapılandırması ve 80 numaralı port kuralları Ubuntu 24.04 üzerinde nginx ile Certbot ve Ubuntu 24.04 üzerinde Apache ile Certbot başlıklarında ele alınmıştır.

_acme-challenge TXT kaydı nasıl çalışır

Certbot *.example.com talebinde bulunduğunda, Let's Encrypt rastgele bir token ile yanıt verir. Certbot bu token'ı ACME (otomatik sertifika yönetim ortamı) hesap anahtarınızla birleştirir, sonucu SHA-256 ile özetler ve kısa bir metin değeri üretir. Bu değerin _acme-challenge.example.com adresinde bir TXT kaydı olarak görünmesi gerekir. Let's Encrypt daha sonra kendi altyapısından alan adınızın yetkili isim sunucularını sorgular. Okuduğu kayıt beklediği değerle eşleşirse, bölgeyi kontrol ettiğinizi kanıtlamış olursunuz; bölge kontrolü, altındaki her ismin kontrolü olarak kabul edilir.

İki ayrıntı çoğu hataya neden olur:

• Aynı sertifika üzerinde example.com ve *.example.com talep etmek, iki ayrı sınama anlamına gelir ve her iki TXT kaydı da aynı isimde, yani _acme-challenge.example.com adresinde bulunur. Her ikisinin de aynı anda mevcut olması gerekir. İkinci kaydı eklemek doğrudur; birincisini ikincisiyle değiştirmek ilk sınamanın başarısız olmasına neden olur.
• Doğrulama işlemi yetkili sunucularınızı okur, ancak sağlayıcı kontrol panellerinin yeni bir kaydı bu sunuculara yansıtması bir dakika veya daha uzun sürebilir. Doğrulamanın çalışmasına izin vermeden önce dışarıdan kontrol edin:

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

Bu komut Certbot'un istediği değeri yazdırdığında, doğrulama başarılı olabilir. Hiçbir şey yazdırmıyorsa bekleyin ve tekrar çalıştırın.

Çalıştığını bir kez görün: manuel mod

Manuel mod, DNS düzenlemesini kendiniz yapmanızı gerektirir; bu, otomatize etmeden önce mekanizmayı anlamanın en iyi yoludur:

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

Wildcard etrafındaki tırnak işaretleri, shell'in * ifadesini bir dosya adı kalıbı olarak işlemesini engeller. Certbot, talimatlarla birlikte duraklatılır:

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

DNS sağlayıcınızın panelinde ilgili TXT kaydını oluşturun, yukarıdaki dig komutu ile görünür olduğunu doğrulayın ve ancak o zaman Enter tuşuna basın. Bu çalıştırma hem çıplak alan adı hem de wildcard için istekte bulunduğundan, Certbot iki kez komut istemi görüntüler; sertifika düzenleme işlemi bitene kadar her iki kaydı da yerinde tutun. Başarılı sonuç, tanıdık satırlarla biter:

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

Manuel mod neden otomatik yenilenemez

Her yenileme işlemi yeni bir token ile gerçekleştirilen yeni bir sınamadır, bu nedenle TXT değeri her seferinde değişir. Bugün eklediğiniz kayıt 60 gün sonra geçersiz olacaktır. Yenileme zamanlayıcısı Certbot aracını günde iki kez otomatik olarak çalıştırır; ancak yeni değeri girecek bir kullanıcı başında bulunmadığından, manuel olarak oluşturulan bir sertifika bu hata ile yenilenemez:

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.')

Bu gereksinimi, DNS sağlayıcınızın API'sini çağıran --manual-auth-hook betikleri yazarak karşılayabilirsiniz; ancak bu durumda bir DNS eklentisini manuel olarak yeniden oluşturmuş olursunuz. Manuel modu süreci öğrenmek için veya DNS otomasyonu henüz mümkün olmayan bir alan adı için tek seferlik bir işlem olarak kullanın. 90. günden çok önce bir hatırlatıcı kurun, çünkü Let's Encrypt artık süre sonu e-postaları göndermemektedir. Diğer tüm durumlar için bir eklenti kullanın.

Eklenti yolu: Ubuntu 24.04 üzerinde certbot-dns-cloudflare

Bir DNS eklentisi, DNS sağlayıcınız için bir API kimlik bilgisi tutar ve hem sertifika alımı sırasında hem de her yenilemede TXT kaydı işlemlerinin tamamını kendisi gerçekleştirir. Cloudflare, çoğu kullanıcının ihtiyaç duyduğu sağlayıcı eklentisi olduğu ve Ubuntu paket depolarında yer aldığı için burada örnek olarak ele alınmıştır.

Certbot rehberlerimiz Ubuntu 24.04 üzerinde apt paketlerinin kullanılmasını önermektedir; bu yaklaşım Cloudflare için de geçerlidir:

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

Sürümler hakkında dürüst bir not: 24.04 arşivi, bu eklentiyi Certbot 2.9.0 sürümünün yanında 2.0.0 sürümüyle sunar; apt policy python3-certbot-dns-cloudflare komutu kendi sürümünüzü gösterir. Bu uyumsuzluk zararsızdır ve kapsamlı API token'ları çalışır; çünkü 24.04 içindeki temel python3-cloudflare kütüphanesi 2.11.1 sürümündedir ve bu, eklentinin token desteği için ihtiyaç duyduğu 2.3.1 sürümünün üzerindedir. Daha eski Ubuntu sürümlerinde bu kütüphane token kullanımı için çok eskiydi; internette bulabileceğiniz, apt eklentisinin Global API Key kullanımını zorunlu kıldığına dair uyarılar bu durumdan kaynaklanmaktadır. 24.04 sürümünde bu uyarılar artık geçerli değildir.

Cloudflare panelinde Global API Key yerine kapsamlı (scoped) bir API token oluşturun: My Profile, ardından API Tokens, ardından Create Token yolunu izleyin. Yalnızca ilgili zone için Zone / DNS / Edit iznini verin ve kapsamı sertifika alacağınız tek bir zone ile sınırlandırın. Bu bilgiyi yalnızca root kullanıcısının okuyabileceği bir dosyaya kaydedin:

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 dosya izinlerini kontrol eder ve dosya başkaları tarafından okunabilir durumdaysa Unsafe permissions on credentials configuration file hakkında uyarı verir. Şimdi sertifikayı oluşturun:

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

Eklenti, API aracılığıyla TXT kayıtlarını oluşturur, kısa bir yayılma süresi bekler, doğrulamanın tamamlanmasını sağlar ve ardından kayıtları siler. Zone isim sunucularınız değişiklikleri yavaş algılıyorsa, bekleme süresini --dns-cloudflare-propagation-seconds 60 ile artırın. Sertifika /etc/letsencrypt/live/example.com/ dizinine kaydedilir; nginx veya Apache yapılandırmanızda, temel rehberlerde gösterildiği gibi deploy hook dahil olmak üzere fullchain.pem ve privkey.pem yollarını kullanın.

Sağlayıcınızın eklentisi apt içinde yoksa

24.04 arşivi, Cloudflare, Route 53, DigitalOcean ve genel RFC 2136 arayüzü dahil olmak üzere yalnızca sınırlı sayıda sağlayıcı için eklenti paketler. Listeyi görmek için apt search certbot-dns komutunu çalıştırın. Eğer sağlayıcınız listede yoksa, "önce apt" tavsiyemizin dışına çıkmanız gereken tek durum budur: Certbot ve eklentiyi bunun yerine snap üzerinden kurun ve iki yenileme zamanlayıcısının /etc/letsencrypt üzerinde çakışmaması için apt ile kurulan Certbot'u kaldırın:

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

Bir snap eklentisi yalnızca snap Certbot ile bağlantı kurar; apt ile kurulan sürümü genişletemez, bu yüzden iki kurulum bir arada bulunmamalıdır. Eğer DNS sağlayıcınız hiçbir API sunmuyorsa, üç gerçekçi seçeneğiniz vardır. Alan adınızın DNS'ini API desteği olan bir sağlayıcıya taşıyabilirsiniz. Kendi isim sunucunuzu çalıştırıp rfc2136 eklentisini ona yönlendirebilirsiniz. Veya mevcut DNS sağlayıcınızda kalıp _acme-challenge.example.com adresinden, API desteği olan bir doğrulama bölgesine (barındırılan bir acme-dns servisi veya kendi çalıştırdığınız bir acme-dns sunucusu gibi) tek seferlik bir CNAME ekleyebilirsiniz. Let’s Encrypt doğrulama sırasında bu CNAME'i takip eder, böylece TXT kayıtları devredilen bölgede tutulur ve ana bölgeniz bir daha asla değişmez.

Yenileme: 60 gün sonra değil, şimdi doğrulayın

Certbot, her sertifikanın nasıl düzenlendiğini /etc/letsencrypt/renewal/example.com.conf içerisinde, authenticator = dns-cloudflare ve kimlik bilgileri yolu dahil olmak üzere kaydeder; böylece standart günde iki kez çalışan zamanlayıcı, sizin müdahalenize gerek kalmadan yenileme işlemini gerçekleştirir. Tüm süreci staging ortamında test edin:

sudo certbot renew --dry-run

Başarılı bir sonuç, kimlik bilgilerinin çalıştığını ve doğrulamanın uçtan uca tamamlandığını gösterir; 60 gün sonra gerçekleşecek gerçek yenileme de aynı yolu izleyecektir. Bugün yapılması gereken iki ek adım bulunmaktadır. Birincisi, diskteki yenilenmiş bir sertifika, web sunucusu tarafından yeniden yüklenene kadar hiçbir şeyi değiştirmez; bu nedenle nginx ve Apache kılavuzlarında açıklanan deploy hook mekanizmasını yapılandırın. İkincisi, kimlik bilgileri dosyasına dikkat edin: dosyayı okuyabilen herkes DNS bölgenizi düzenleyebilir; bu da e-postalarınızı yönlendirmek veya kendi DNS-01 sınamalarını geçmek için yeterlidir. Dosyayı /root altında 600 modunda tutun, token yetkisini tek bir bölge ile sınırlandırın ve sızıntı şüphesi durumunda anahtarı yenileyin.

Wildcard gerekmediği durumlar

Wildcard, birçok alt alan adı veya önceden tahmin edilemeyen alt alan adları için doğru araçtır. Diğer tüm durumlar için varsayılan olarak kullanılması yanlıştır.

• Tek bir alt alan adı veya bilinen birkaç tanesi için: Normal bir SAN (subject alternative name) sertifikası daha basittir. certbot --nginx -d example.com -d www.example.com -d app.example.com, düz HTTP-01 üzerinden 100 adede kadar ismi kapsar ve sunucuda herhangi bir DNS API kimlik bilgisi tutulmasına gerek kalmaz.
• Bir wildcard tam olarak tek bir etiketi eşleştirir. *.example.com, çıplak example.com alan adını kapsamaz; yukarıdaki komutların her ikisini de talep etmesinin nedeni budur. Ayrıca a.b.example.com adresini de kapsamaz; bunun için *.b.example.com gerekir.
• Her alt alan adının arkasında tek bir özel anahtar bulunur. Bu anahtarı barındıran makine ele geçirilirse, wildcard tarafından kapsanan tüm isimler aynı anda tehlikeye girer.
• Eğer Traefik, container'larınız için TLS (transport layer security) sonlandırması yapıyorsa, Certbot'a hiç ihtiyacınız yoktur: Traefik, wildcard sertifikalarını DNS-01 üzerinden kendisi talep eder ve aynı sağlayıcı token'ını kullanır.

Wildcard'ın gerçekten gerekli olduğu durumlar: Sertifika yenileme hızından daha hızlı oluşturulan müşteri bazlı veya uygulama bazlı alt alan adları ve bir WireGuard VPN üzerinden erişilebilen servisler gibi 80 numaralı portu dış dünyaya açık olmayan dahili ana makinelerdir. DNS-01, sertifikalandırılan ana makineye hiçbir zaman bağlanmaz; bu sayede tamamen özel bir makine bile genel olarak güvenilen bir sertifikaya sahip olabilir.

FAQ

Certbot, HTTP-01 ile wildcard sertifikası düzenleyebilir mi?

Hayır. HTTP-01, doğrulama sunucusu tam olarak o isimden bir token dosyası çektiği için tek bir ana bilgisayar adının kontrolünü kanıtlar. Wildcard, alan adı altındaki tüm birinci seviye isimleri kapsar, bu yüzden Let’s Encrypt bunun için DNS-01 doğrulaması gerektirir; --nginx, --apache, --webroot ve --standalone doğrulayıcılarının tümü HTTP tabanlıdır. Tek yol, manuel olarak veya bir DNS eklentisi ile _acme-challenge.example.com adresine (veya CNAME ile devredilen bölgeye) bir TXT kaydı yerleştirmektir.

Wildcard sertifikası kök alan adını kapsar mı?

Hayır. Wildcard tam olarak bir etiketle eşleşir; bu nedenle *.example.com, www.example.com adresini kapsar ancak çıplak example.com adresini ve a.b.example.com adresini kapsamaz. Her iki ismi de tek bir sertifikada talep etmek için -d example.com -d '*.example.com' kullanın. Bu, iki doğrulama oluşturur ve her iki TXT kaydı da aynı _acme-challenge.example.com isminde yer alır; bu yüzden ilkini silmeden ikinci kaydı ekleyin.

Wildcard sertifikam neden otomatik olarak yenilenmiyor?

Çünkü --manual ile düzenlenmiştir. Her yenileme yepyeni bir TXT değeri gerektirir ve otomatik zamanlayıcının bunu yapıştırma imkanı yoktur, bu yüzden yenileme An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively hatasıyla durur. Sertifikayı certbot-dns-cloudflare gibi bir DNS eklentisi ile yeniden düzenleyin veya kaydı sağlayıcınızın API'si üzerinden düzenleyen --manual-auth-hook ve --manual-cleanup-hook betiklerini sağlayın.

_acme-challenge TXT kaydının görünmesi ne kadar sürer?

DNS sağlayıcınıza bağlı olarak saniyelerden birkaç dakikaya kadar sürebilir. Doğrulama, bölgenizin yetkili sunucularını okur; bu nedenle dig +short TXT _acme-challenge.example.com @1.1.1.1 ile kontrol edin ve manuel bir işlem yapmadan önce beklenen değerin göründüğünden emin olun. Bir eklenti kullanıyorsanız, doğrulama kaydın bulunamadığını bildirirse, eklentinin yayılma seçeneği (örneğin --dns-cloudflare-propagation-seconds 60) ile yerleşik bekleme süresini artırın.

Wildcard sertifikası normal bir sertifikadan daha az mı güvenlidir?

Kriptografi aynıdır. Farklar operasyoneldir: tek bir özel anahtar tüm alt alan adlarını kapsar, bu nedenle bir ihlal durumunda etki alanı daha geniştir ve otomasyonun gerektirdiği DNS API kimlik bilgisi, sunucuda saklanan hassas bir sırdır. Yalnızca birkaç bilinen alt alan adı çalıştırıyorsanız, bir SAN sertifikası her iki sorunu da önler; bu rehberin wildcard kullanmaktan kaçınmayı önerdiği durum tam olarak budur.