Certbot Wildcard dengan DNS-01: Panduan Sertifikat

Mengapa sertifikat wildcard memerlukan DNS-01

Sertifikat wildcard mencakup setiap subdomain tingkat pertama dari suatu domain: *.example.com cocok dengan app.example.com, blog.example.com, dan nama lain apa pun yang memiliki kedalaman satu label. Let's Encrypt menerbitkan sertifikat wildcard hanya melalui challenge DNS-01. Karena itu, Certbot harus membuktikan kendali atas DNS domain dengan menerbitkan record TXT di _acme-challenge.example.com. Challenge HTTP-01 tidak dapat digunakan karena penyajian file token hanya membuktikan kendali atas satu hostname, yaitu hostname tempat server validasi mengambil file tersebut. Wildcard merupakan klaim tentang setiap nama yang mungkin berada di bawah domain. Satu-satunya record publik yang mewakili seluruh namespace tersebut adalah DNS.

Persyaratan ini menentukan semua hal lain di halaman ini. Untuk melewati DNS-01, Anda harus dapat membuat record TXT di zone domain, secara manual atau melalui API (application programming interface) penyedia DNS Anda. Cara manual hanya berhasil sekali, lalu gagal saat renewal karena alasan yang dijelaskan secara konkret di bawah. Cara melalui API, dengan plugin DNS Certbot, dapat melakukan renewal tanpa pengawasan. Itulah konfigurasi yang sebaiknya Anda gunakan.

Ini adalah bab wildcard dalam panduan Certbot kami. Sertifikat biasa untuk satu hostname, konfigurasi web server, dan aturan port 80 dibahas dalam Certbot dengan nginx di Ubuntu 24.04 dan Certbot dengan Apache di Ubuntu 24.04.

Cara kerja record TXT _acme-challenge

Saat Certbot meminta *.example.com, Let's Encrypt menjawab dengan token acak. Certbot menggabungkan token tersebut dengan kunci akun ACME (automatic certificate management environment) Anda, melakukan hashing pada hasilnya menggunakan SHA-256, lalu menghasilkan nilai teks singkat. Nilai tersebut harus muncul sebagai record TXT di _acme-challenge.example.com. Selanjutnya, Let's Encrypt meminta informasi dari server nama otoritatif domain Anda melalui infrastrukturnya sendiri. Jika record yang dibaca sesuai dengan nilai yang diharapkan, Anda telah membuktikan bahwa Anda mengendalikan zona tersebut. Pengendalian zona diterima sebagai pengendalian atas setiap nama di dalamnya.

Dua hal berikut paling sering menyebabkan kegagalan:

• Meminta example.com dan *.example.com dalam sertifikat yang sama berarti ada dua challenge terpisah. Kedua record TXT berada pada nama yang sama, yaitu _acme-challenge.example.com. Keduanya harus ada secara bersamaan. Menambahkan record kedua sudah benar. Mengganti record pertama dengan record kedua menyebabkan challenge pertama gagal.
• Validasi membaca server otoritatif Anda, tetapi panel kontrol penyedia dapat memerlukan waktu satu menit atau lebih untuk meneruskan record baru ke server tersebut. Periksa dari luar sebelum menjalankan validasi:

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

Jika perintah tersebut menampilkan nilai yang diminta Certbot, validasi dapat berhasil. Jika tidak menampilkan apa pun, tunggu lalu jalankan kembali.

Sekali Melihat Prosesnya: Mode Manual

Mode manual mengharuskan Anda mengedit DNS sendiri. Ini adalah cara terbaik untuk memahami mekanismenya sebelum mengotomatiskannya:

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

Tanda kutip di sekitar wildcard mencegah shell memperlakukan * sebagai pola nama file. Certbot berhenti dan menampilkan petunjuk:

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

Buat record TXT tersebut di panel penyedia DNS Anda. Pastikan record itu terlihat dengan perintah dig di atas, lalu tekan Enter. Karena proses ini meminta domain dasar dan wildcard, Certbot menampilkan prompt dua kali. Biarkan kedua record tetap ada sampai penerbitan selesai. Keberhasilan ditandai dengan baris yang sudah dikenal:

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

Mengapa mode manual tidak dapat memperbarui sertifikat secara otomatis

Setiap pembaruan adalah tantangan baru dengan token baru, sehingga nilai TXT berubah setiap kali. Record yang Anda tempel hari ini tidak berguna lagi dalam 60 hari. Pengatur waktu pembaruan menjalankan Certbot tanpa pengawasan dua kali sehari, dan tidak ada orang di depan keyboard untuk menempelkan nilai baru. Akibatnya, pembaruan sertifikat yang diterbitkan secara manual gagal dengan kesalahan berikut:

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

Anda dapat memenuhi persyaratan tersebut dengan menulis skrip --manual-auth-hook yang memanggil API penyedia DNS Anda. Namun, pada tahap itu Anda sebenarnya membuat ulang plugin DNS secara manual. Gunakan mode manual untuk mempelajari alurnya, atau untuk penerbitan satu kali pada domain yang DNS-nya belum dapat Anda otomatisasi. Atur pengingat jauh sebelum hari ke-90, karena Let's Encrypt tidak lagi mengirim email kedaluwarsa. Untuk keperluan lainnya, gunakan plugin.

Rute plugin: certbot-dns-cloudflare di Ubuntu 24.04

Plugin DNS menyimpan kredensial API untuk penyedia DNS Anda dan menangani seluruh proses record TXT secara otomatis, saat penerbitan dan setiap kali perpanjangan. Cloudflare digunakan sebagai contoh karena plugin untuk penyedia ini paling banyak dibutuhkan dan tersedia dalam paket Ubuntu.

Panduan Certbot kami merekomendasikan paket apt di Ubuntu 24.04, dan rekomendasi itu juga berlaku untuk Cloudflare:

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

Catatan penting tentang versi. Arsip 24.04 menyediakan plugin ini pada versi 2.0.0 bersama Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare menampilkan versi yang Anda gunakan. Perbedaan versi tersebut tidak bermasalah, dan token API dengan cakupan terbatas dapat digunakan karena pustaka python3-cloudflare yang mendasarinya di 24.04 adalah versi 2.11.1, lebih baru daripada versi 2.3.1 yang diperlukan plugin untuk mendukung token. Pada rilis Ubuntu yang lebih lama, pustaka tersebut terlalu lama untuk mendukung token. Karena itu, Anda mungkin menemukan peringatan daring bahwa plugin apt memaksa penggunaan Global API Key. Peringatan tersebut tidak lagi berlaku di 24.04.

Di dasbor Cloudflare, buat token API dengan cakupan terbatas, bukan Global API Key: My Profile, lalu API Tokens, kemudian Create Token, dengan satu izin Zone / DNS / Edit. Batasi token itu ke satu zona yang digunakan untuk penerbitan sertifikat. Simpan token tersebut dalam file yang hanya dapat dibaca oleh 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 memeriksa mode file tersebut dan memperingatkan tentang Unsafe permissions on credentials configuration file jika file dapat dibaca oleh pengguna lain. Sekarang terbitkan sertifikat:

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

Plugin membuat record TXT melalui API, menunggu propagasi singkat, menjalankan validasi, lalu menghapus record tersebut. Jika name server zona Anda lambat menerapkan perubahan, tambah waktu tunggu dengan --dns-cloudflare-propagation-seconds 60. Sertifikat disimpan di /etc/letsencrypt/live/example.com/. Arahkan nginx atau Apache ke fullchain.pem dan privkey.pem persis seperti yang ditunjukkan dalam panduan dasar, termasuk deploy hook.

Jika plugin penyedia Anda tidak ada di apt

Arsip 24.04 hanya menyediakan paket plugin untuk beberapa penyedia, termasuk Cloudflare, Route 53, DigitalOcean, dan antarmuka RFC 2136 generik. Jalankan apt search certbot-dns untuk melihat daftarnya. Jika penyedia Anda tidak ada, inilah satu-satunya kondisi ketika saran kami untuk memprioritaskan apt tidak berlaku: instal Certbot dan pluginnya dari snap, lalu hapus Certbot dari apt terlebih dahulu agar dua pengatur waktu pembaruan tidak pernah berebut /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

Plugin snap hanya terhubung ke Certbot dari snap. Plugin tersebut tidak dapat memperluas Certbot dari apt. Karena itu, kedua instalasi tersebut tidak boleh ada secara bersamaan. Jika host DNS Anda tidak menyediakan API sama sekali, pilihan realistis Anda adalah memindahkan DNS domain ke penyedia yang memilikinya, atau menjalankan server nama sendiri dan mengarahkan plugin rfc2136 ke server tersebut.

Perpanjangan: buktikan sekarang, bukan dalam 60 hari

Certbot mencatat cara setiap sertifikat diterbitkan di /etc/letsencrypt/renewal/example.com.conf, termasuk authenticator = dns-cloudflare dan path kredensial, sehingga timer standar yang berjalan dua kali sehari dapat memperpanjangnya tanpa bantuan Anda. Uji seluruh proses terhadap lingkungan staging:

sudo certbot renew --dry-run

Keberhasilan berarti kredensial berfungsi dan validasi selesai dari awal hingga akhir. Perpanjangan sebenarnya dalam 60 hari akan mengikuti jalur yang sama. Ada dua tindak lanjut yang sebaiknya dilakukan hari ini. Pertama, sertifikat yang diperpanjang di disk tidak mengubah apa pun sampai web server memuat ulang sertifikat tersebut. Karena itu, konfigurasikan deploy hook yang dijelaskan dalam panduan nginx dan Apache. Kedua, lindungi file kredensial dengan baik. Siapa pun yang dapat membacanya dapat mengedit zona DNS Anda. Hal ini cukup untuk mengalihkan email atau menyelesaikan challenge DNS-01 mereka sendiri. Tetapkan mode 600 pada file tersebut di bawah /root, batasi token ke satu zona, dan lakukan rotasi jika Anda pernah mencurigai adanya kebocoran.

Saat Anda tidak memerlukan wildcard

Wildcard merupakan pilihan yang tepat untuk banyak subdomain atau subdomain yang tidak dapat Anda prediksi. Namun, wildcard bukan pilihan default yang tepat untuk semua kondisi lainnya.

• Satu subdomain atau beberapa subdomain yang sudah diketahui: sertifikat SAN (subject alternative name) biasa lebih sederhana. certbot --nginx -d example.com -d www.example.com -d app.example.com mencakup hingga 100 nama melalui HTTP-01 biasa, dan kredensial API DNS tidak pernah tersimpan di server.
• Wildcard hanya cocok dengan satu label. *.example.com tidak mencakup example.com tanpa subdomain. Karena itu, perintah di atas meminta keduanya. Wildcard juga tidak mencakup a.b.example.com; untuk itu diperlukan *.b.example.com.
• Satu kunci privat digunakan oleh semua subdomain. Jika mesin yang menyimpan kunci tersebut dibobol, semua nama yang dicakup wildcard akan terdampak sekaligus.
• Jika Traefik menangani terminasi TLS (transport layer security) untuk container Anda, Anda sama sekali tidak memerlukan Certbot: Traefik meminta sertifikat wildcard sendiri melalui DNS-01, menggunakan jenis token provider yang sama.

Wildcard benar-benar berguna untuk subdomain per pelanggan atau per aplikasi yang dibuat lebih cepat daripada penerbitan ulang sertifikat, serta host internal tanpa port publik 80, seperti layanan yang hanya dapat diakses melalui VPN WireGuard. DNS-01 tidak pernah terhubung ke host yang sertifikatnya sedang divalidasi. Karena itu, mesin yang sepenuhnya privat pun dapat menyimpan sertifikat yang dipercaya secara publik.

FAQ

Apakah Certbot dapat menerbitkan sertifikat wildcard dengan HTTP-01?

Tidak. HTTP-01 membuktikan kendali atas satu nama host karena server validasi mengambil file token dari nama tersebut. Sertifikat wildcard mencakup semua nama di bawah domain, sehingga Let's Encrypt mengharuskan challenge DNS-01 untuk sertifikat tersebut. Sementara itu, --nginx, --apache, --webroot, dan --standalone semuanya merupakan authenticator berbasis HTTP. Satu-satunya cara adalah menambahkan record TXT di _acme-challenge.example.com, secara manual atau dengan plugin DNS.

Apakah sertifikat wildcard mencakup domain root?

Tidak. Wildcard hanya cocok dengan satu label. Jadi, *.example.com mencakup www.example.com, tetapi tidak mencakup example.com tanpa subdomain dan juga tidak mencakup a.b.example.com. Minta kedua nama tersebut dalam satu sertifikat dengan -d example.com -d '*.example.com'. Tindakan ini membuat dua challenge. Kedua record TXT berada pada nama _acme-challenge.example.com yang sama, jadi tambahkan record kedua tanpa menghapus record pertama.

Mengapa sertifikat wildcard saya tidak diperbarui secara otomatis?

Karena sertifikat tersebut diterbitkan dengan --manual. Setiap pembaruan memerlukan nilai TXT yang benar-benar baru. Timer tanpa pengawasan tidak dapat memasukkan nilai tersebut, sehingga pembaruan berhenti dan menampilkan error An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Terbitkan ulang sertifikat dengan plugin DNS seperti certbot-dns-cloudflare, atau sediakan skrip --manual-auth-hook dan --manual-cleanup-hook untuk mengubah record melalui API provider Anda.

Berapa lama record TXT _acme-challenge perlu waktu untuk muncul?

Waktunya bergantung pada provider DNS Anda, mulai dari beberapa detik hingga beberapa menit. Validasi membaca authoritative server zona DNS Anda. Karena itu, periksa dengan dig +short TXT _acme-challenge.example.com @1.1.1.1 dan tunggu hingga nilai yang diharapkan muncul sebelum melanjutkan proses manual. Dengan plugin, tingkatkan waktu tunggu bawaan melalui opsi propagasi plugin, misalnya --dns-cloudflare-propagation-seconds 60, jika validasi melaporkan bahwa record tidak ditemukan.

Apakah sertifikat wildcard kurang aman dibandingkan sertifikat biasa?

Kriptografinya sama. Perbedaannya bersifat operasional. Satu private key mencakup setiap subdomain, sehingga dampak kompromi lebih luas. Selain itu, kredensial API DNS yang diperlukan otomatisasi merupakan secret sensitif yang disimpan di server. Jika Anda hanya menjalankan beberapa subdomain yang sudah diketahui, sertifikat SAN menghindari kedua risiko tersebut. Karena itu, panduan ini merekomendasikan untuk tidak menggunakan wildcard dalam kondisi tersebut.