Certbot ile DNS-01 ile Wildcard Sertifikası

Bir wildcard sertifikası neden DNS-01 gerektirir

Bir 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 tek etiketli diğer tüm isimlerle eşleşir. Let's Encrypt, wildcard sertifikalarını yalnızca DNS-01 challenge yöntemiyle düzenler; bu nedenle Certbot, _acme-challenge.example.com adresine bir TXT kaydı ekleyerek alan adının DNS kontrolüne sahip olduğunu kanıtlamalıdır. HTTP-01 challenge yöntemi uygun değildir; çünkü bir token dosyasını sunmak, yalnızca doğrulama sunucusunun dosyayı çektiği tek bir hostname üzerinde kontrol sağladığınızı kanıtlar. Wildcard, alan adı altındaki her olası isim için bir beyandır ve tüm namespace adına konuşan tek genel kayıt DNS'in kendisidir.

Bu gereksinim, bu sayfadaki diğer tüm unsurları belirler. DNS-01 sürecini tamamlamak için, alan adı bölgesi içinde manuel olarak veya DNS sağlayıcınızın API'si (application programming interface) aracılığıyla TXT kayıtları oluşturabilmeniz gerekir. Manuel yöntem bir kez çalışır ancak yenileme sırasında, aşağıda belirtilen somut bir nedenden dolayı başarısız olur. Certbot DNS eklentisi aracılığıyla yapılan API yöntemi, yenileme işlemini otomatik olarak gerçekleştirir; ulaşılması gereken kurulum budur.

Bu, Certbot kılavuzlarımızın wildcard bölümüdür. Standart tek hostname sertifikaları, web sunucusu yapılandırması ve 80 portu kuralları Ubuntu 24.04 üzerinde nginx ile Certbot ve Ubuntu 24.04 üzerinde Apache ile Certbot bölümlerinde ele alınmaktadır.

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

Certbot *.example.com isteğinde bulunduğunda, Let's Encrypt rastgele bir token ile yanıt verir. Certbot bu token'ı ACME (automatic certificate management environment) hesap anahtarınızla birleştirir, sonucu SHA-256 ile hash'ler ve kısa bir metin değeri üretir. Bu değer, _acme-challenge.example.com adresinde bir TXT kaydı olarak görünmelidir. Let's Encrypt, kendi altyapısından alan adınızın yetkili name server'larına sorgu gönderir. Okunan kayıt beklenen değerle eşleşirse, zone kontrolüne sahip olduğunuz kanıtlanmış sayılır; zone kontrolü, altındaki tüm isimlerin kontrolü olarak kabul edilir.

Çoğu hata iki nedenden kaynaklanır:

• Aynı sertifika için example.com ve *.example.com istenmesi, iki ayrı challenge anlamına gelir ve her iki TXT kaydı da aynı isimde, _acme-challenge.example.com, bulunur. Her iki kayıt da aynı anda mevcut olmalıdır. İkinci kaydı eklemek doğru yöntemdir; birinci kaydı ikincisiyle değiştirmek birinci challenge işleminin başarısız olmasına neden olur.
• Doğrulama işlemi yetkili server'larınızı okur, ancak sağlayıcı kontrol panellerinin yeni bir kaydı bu server'lara iletmesi bir dakika veya daha fazla sürebilir. Doğrulama işlemini başlatmadan önce dışarıdan kontrol sağlayın:

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ırılmadığında bekleyin ve komutu tekrar çalıştırın.

Bir kez çalıştığını görün: manuel mod

Manuel mod, DNS düzenlemesini manuel olarak yapmanızı gerektirir. Bu, mekanizmayı otomatize etmeden önce 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, kabuğun (shell) * ifadesini bir dosya adı deseni olarak algılamasını 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

Bu TXT kaydını DNS sağlayıcınızın panelinde oluşturun, yukarıdaki dig komutu ile görünür olduğunu doğrulayın ve ancak ondan sonra Enter tuşuna basın. Bu çalıştırma hem yalın domaini hem de wildcard alanını istediği için Certbot iki kez komut verir; sertifika oluşturma işlemi bitene kadar her iki kaydı da yerinde tutun. Başarı, şu tanıdık satırlarla sonuçlanır:

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

Manuel modun neden kendi kendini yenileyemediği

Her yenileme işlemi yeni bir token gerektirir, bu nedenle TXT değeri her seferinde değişir. Bugün yapıştırdığınız kayıt 60 gün sonra geçersiz olacaktır. Certbot yenileme zamanlayıcısı günde iki kez arka planda çalışır. Yeni değeri yapıştıracak bir kullanıcı bulunmadığı için manuel olarak oluşturulan sertifikalar şu hatayı vererek yenileme işlemini gerçekleştiremez:

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

DNS sağlayıcınızın API'sini çağıran --manual-auth-hook scriptleri yazarak bu gereksinimi karşılayabilirsiniz; ancak bu durumda bir DNS pluginini manuel olarak yeniden inşa etmiş olursunuz. Manuel modu iş akışını öğrenmek için veya DNS otomasyonu henüz yapılamayan alan adları için tek seferlik işlemler için kullanın. Let's Encrypt artık son kullanma tarihi e-postaları göndermediği için 90. günden çok önce bir hatırlatıcı ayarlayın. Diğer tüm durumlar için bir plugin 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 sertifika oluşturma sırasında ve her yenileme işleminde TXT kaydı sürecini kendisi yönetir. Cloudflare, en çok ihtiyaç duyulan sağlayıcı eklentisi olduğu ve Ubuntu içinde paketlenmiş olarak bulunduğu için burada örnek olarak kullanılmaktadır.

Certbot kılavuzlarımız Ubuntu 24.04 üzerinde apt paketlerini önermektedir; bu durum Cloudflare için de geçerlidir:

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

Sürümler hakkında bir not. 24.04 arşivi, bu eklentiyi Certbot 2.9.0 ile birlikte 2.0.0 sürümünde sunar; apt policy python3-certbot-dns-cloudflare sizin sürümünüzü gösterir. Bu sürüm farkı sorun teşkil etmez ve kapsamlı (scoped) API tokenları çalışır; çünkü 24.04 içindeki temel python3-cloudflare kütüphanesi 2.11.1 sürümündedir ve bu sürüm, eklentinin token desteği için ihtiyaç duyduğu 2.3.1 sürümünün üzerindedir. Eski Ubuntu sürümlerinde bu kütüphane tokenlar için çok eskiydi; internette apt eklentisinin Global API Key kullanımına zorladığına dair bulabileceğiniz uyarılar buradan kaynaklanmaktadır. 24.04 üzerinde bu uyarılar artık geçerli değildir.

Cloudflare panelinde, Global API Key yerine kapsamlı bir API token oluşturun: My Profile, ardından API Tokens, sonra Create Token; tek izin olarak Zone / DNS / Edit seçilmeli ve sadece sertifika oluşturulacak bölge ile sınırlandırılmalıdır. Dosyayı sadece root kullanıcısının okuyabileceği şekilde 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 modunu kontrol eder ve dosya başkaları tarafından okunabiliyorsa Unsafe permissions on credentials configuration file hakkında uyarı verir. Şimdi işlemi başlatın:

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

Eklenti, TXT kayıtlarını API üzerinden oluşturur, kısa bir yayılma süresi bekler, doğrulamayı gerçekleştirir ve ardından kayıtları tekrar siler. Eğer bölgenizin name serverları değişiklikleri geç algılıyorsa, --dns-cloudflare-propagation-seconds 60 ile bekleme süresini artırın. Sertifika /etc/letsencrypt/live/example.com/ dizinine kaydedilir; nginx veya Apache yapılandırmasını, deploy hook dahil olmak üzere, temel kılavuzlarda gösterildiği gibi tam olarak fullchain.pem ve privkey.pem dizinlerine yönlendirin.

Sağlayıcı eklentisi apt içerisinde bulunmuyorsa

24.04 arşivi yalnızca sınırlı sayıda sağlayıcı için eklenti paketlemektedir; Cloudflare, Route 53, DigitalOcean ve genel RFC 2136 arayüzü bu sağlayıcılar arasındadır. Listeyi görmek için apt search certbot-dns komutunu çalıştırın. Sağlayıcınız listede yoksa, "önce apt" yaklaşımımız burada geçerliliğini yitirir: Certbot ve eklentiyi snap üzerinden kurun; iki yenileme zamanlayıcısının /etc/letsencrypt üzerinde çakışmaması için önce apt sürümündeki 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 sürümünü genişletemez, bu nedenle iki kurulum bir arada bulunmamalıdır. Eğer DNS sağlayıcınız hiçbir API sunmuyorsa, gerçekçi seçenekleriniz alan adının DNS ayarlarını API sunan bir sağlayıcıya taşımak veya kendi ad sunucunuzu çalıştırıp rfc2136 eklentisini buna yönlendirmektir.

Yenileme: 60 gün sonra değil, şimdi test edin

Certbot, her sertifikanın nasıl düzenlendiğini, authenticator = dns-cloudflare ve kimlik bilgileri yolu dahil olmak üzere /etc/letsencrypt/renewal/example.com.conf içerisinde kaydeder. Bu sayede 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 deneyin:

sudo certbot renew --dry-run

İşlemin başarılı olması, kimlik bilgilerinin çalıştığı ve doğrulamanın uçtan uca tamamlandığı anlamına gelir; 60 gün sonraki gerçek yenileme de aynı yolu izleyecektir. Bugün yapılması gereken iki takip adımı bulunmaktadır. Birincisi, disk üzerindeki yenilenmiş bir sertifika, web sunucusu yeniden yüklenene kadar bir değişiklik yaratmaz; bu nedenle nginx ve Apache kılavuzlarında açıklanan deploy hook yapısını kurun. İkincisi, kimlik bilgileri dosyasına dikkatli yaklaşın: dosyayı okuyabilen herkes DNS bölgenizi düzenleyebilir; bu durum e-postalarınızı yönlendirmek veya kendi DNS-01 zorluklarını geçmek için yeterlidir. Dosyayı /root altında mode 600 olarak tutun, token kapsamını tek bir bölge ile sınırlayın ve bir sızıntıdan şüphelenirseniz token'ı yenileyin.

Wildcard kullanımına ihtiyaç duyulmayan durumlar

Wildcard, çok sayıda alt alan adı veya tahmin edilemeyen alt alan adları için uygun bir araçtır. Diğer tüm durumlar için varsayılan olarak seçilmesi hatalıdır.

• Tek bir alt alan adı veya belirli sayıda bilinen alt alan adı için: normal bir SAN (subject alternative name) sertifikası daha basittir. certbot --nginx -d example.com -d www.example.com -d app.example.com, plain HTTP-01 üzerinden 100 isme kadar kapsama sağlar ve sunucuda hiçbir DNS API kimliği barındırılmaz.
• Wildcard, tam olarak bir etiketi eşleştirir. *.example.com, yalın example.com yapısını kapsamaz; bu nedenle yukarıdaki komutlar her ikisini de talep eder. Ayrıca a.b.example.com yapısını da kapsamaz; bunun için *.b.example.com gereklidir.
• Her alt alan adının arkasında bir özel anahtar (private key) bulunur. Bu anahtarı tutan makine ele geçirilirse, wildcard'ın kapsadığı tüm isimler aynı anda etkilenir.
• Eğer Traefik, konteynerleriniz için TLS (transport layer security) sonlandırması yapıyorsa, Certbot kullanımına gerek yoktur: Traefik, DNS-01 üzerinden wildcard sertifikalarını kendisi talep eder ve aynı türden bir sağlayıcı token'ı kullanır.

Wildcard'ın gerçekten faydalı olduğu durumlar: sertifikaların yeniden oluşturulma hızından daha hızlı oluşturulan müşteri veya uygulama bazlı alt alan adları ile bir WireGuard VPN üzerinden erişilebilen servisler gibi, 80 numaralı portu açık olmayan dahili hostlar. DNS-01, sertifikalandırılan host ile asla bağlantı kurmaz; bu sayede tamamen özel bir makine bile kamuya açık, güvenilir bir sertifika barındırabilir.

FAQ

Certbot, HTTP-01 ile wildcard sertifika oluşturabilir mi?

Hayır. HTTP-01 yöntemi tek bir hostname üzerinde kontrol sağlar; çünkü doğrulama sunucusu token dosyasını doğrudan o isme çeker. Wildcard sertifikalar alan adı altındaki tüm isimleri kapsar. Bu nedenle Let's Encrypt, wildcard için DNS-01 challenge yöntemini gerektirir. --nginx, --apache, --webroot ve --standalone doğrulayıcıları HTTP tabanlıdır. Tek yöntem, manuel olarak veya bir DNS eklentisiyle yerleştirilen _acme-challenge.example.com adresindeki TXT kaydıdır.

Wildcard sertifika kök domaini kapsar mı?

Hayır. Wildcard tam olarak bir etiketi eşleştirir. Bu nedenle *.example.com, www.example.com adresini kapsar ancak yalın example.com veya a.b.example.com adresini kapsamaz. -d example.com -d '*.example.com' kullanarak her iki ismi de tek bir sertifikada talep edin. Bu işlem iki challenge oluşturur. Her iki TXT kaydı da aynı _acme-challenge.example.com isminde bulunur; bu yüzden ikinci kaydı eklerken ilki silinmemelidir.

Wildcard sertifikam neden otomatik olarak yenilenmiyor?

Çünkü sertifika --manual ile oluşturulmuştur. Her yenileme işlemi yeni bir TXT değeri gerektirir. Otomatik zamanlayıcı bu değeri ekleyemez, bu yüzden yenileme işlemi 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 eklentisiyle yeniden oluşturun veya sağlayıcınızın API'si üzerinden kaydı düzenleyen --manual-auth-hook ve --manual-cleanup-hook betiklerini kullanın.

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

Bu süre DNS sağlayıcınıza bağlıdır; birkaç saniye ile birkaç dakika arasında değişebilir. Doğrulama işlemi zone yetkili sunucularını okur. Manuel işlemi sürdürmeden önce dig +short TXT _acme-challenge.example.com @1.1.1.1 ile kontrol edin ve beklenen değer görünene kadar bekleyin. Eğer doğrulama kaydın bulunamadığını bildirirse, bir eklenti kullanıyorsanız eklentinin yayılma (propagation) seçeneği olan --dns-cloudflare-propagation-seconds 60 ile bekleme süresini artırın.

Wildcard sertifika normal sertifikadan daha mı az güvenlidir?

Kriptografi aynıdır. Farklar operasyoneldir: Tek bir özel anahtar tüm alt alan adlarını kapsar, bu nedenle bir sızıntı daha geniş bir etki alanına ulaşır. Ayrıca otomasyonun gerektirdiği DNS API kimlik bilgileri, sunucuda saklanan hassas bir sırdır. Sadece birkaç bilinen alt alan adı kullanıyorsanız, SAN sertifikası her iki sorunu da ortadan kaldırır; bu rehberin wildcard yerine bunu önermesinin sebebi budur.