Cara buat sertifikat wildcard Certbot DNS-01

Mengapa sertifikat wildcard memerlukan DNS-01

Sertifikat wildcard mencakup setiap subdomain tingkat pertama dari sebuah domain: *.example.com cocok dengan app.example.com, blog.example.com, dan nama lain apa pun dengan satu label. Let's Encrypt hanya menerbitkan sertifikat wildcard melalui tantangan DNS-01, sehingga Certbot harus membuktikan kendali atas DNS domain dengan memublikasikan rekaman TXT di _acme-challenge.example.com. Tantangan HTTP-01 tidak dapat memenuhi syarat, karena menyajikan file token hanya membuktikan kendali atas satu hostname, yaitu hostname tempat server validasi mengambil file tersebut. Wildcard adalah klaim untuk setiap nama yang memungkinkan di bawah domain tersebut, dan satu-satunya rekaman publik yang mewakili seluruh namespace adalah DNS itu sendiri.

Satu persyaratan tersebut menentukan hal lainnya di halaman ini. Untuk melewati DNS-01, Anda harus dapat membuat rekaman TXT di zona domain, baik secara manual maupun melalui API (application programming interface) penyedia DNS Anda. Metode manual hanya berhasil satu kali lalu gagal saat pembaruan, karena alasan spesifik yang dijelaskan di bawah. Metode API, melalui plugin DNS Certbot, melakukan pembaruan secara otomatis, dan ini adalah konfigurasi yang harus Anda gunakan.

Ini adalah bab wildcard dari panduan Certbot kami. Sertifikat hostname tunggal biasa, 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 rekaman TXT _acme-challenge

Saat Certbot meminta *.example.com, Let's Encrypt memberikan token acak. Certbot menggabungkan token tersebut dengan kunci akun ACME (automatic certificate management environment) Anda, melakukan hashing pada hasilnya dengan SHA-256, dan menghasilkan nilai teks pendek. Nilai tersebut harus muncul sebagai rekaman TXT di _acme-challenge.example.com. Let's Encrypt kemudian melakukan kueri ke name server otoritatif domain Anda dari infrastruktur mereka sendiri. Jika rekaman yang dibaca sesuai dengan nilai yang diharapkan, Anda telah membuktikan bahwa Anda mengontrol zone tersebut, dan kontrol atas zone diterima sebagai kontrol atas setiap nama di bawahnya.

Dua detail menyebabkan sebagian besar kegagalan:

• Meminta example.com dan *.example.com pada sertifikat yang sama berarti dua tantangan terpisah, dan kedua rekaman TXT berada pada nama yang sama, _acme-challenge.example.com. Keduanya harus ada pada waktu yang bersamaan. Menambahkan rekaman kedua adalah langkah yang benar; mengganti rekaman pertama dengan rekaman kedua akan menyebabkan tantangan pertama gagal.
• Validasi membaca server otoritatif Anda, tetapi panel kontrol penyedia layanan dapat membutuhkan waktu satu menit atau lebih untuk menyebarkan rekaman 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 dan jalankan kembali.

Lihat cara kerjanya sekali: mode manual

Mode manual mengharuskan Anda melakukan pengeditan DNS secara mandiri. Ini adalah cara terbaik untuk memahami mekanisme tersebut sebelum Anda melakukan otomatisasi:

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 akan berhenti dan menampilkan instruksi:

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

Buatlah rekaman TXT tersebut di panel penyedia DNS Anda, konfirmasi bahwa rekaman tersebut sudah terlihat menggunakan perintah dig di atas, lalu tekan Enter. Karena proses ini meminta domain dasar dan wildcard, Certbot akan memberikan perintah dua kali; biarkan kedua rekaman tetap ada hingga penerbitan selesai. Keberhasilan ditandai dengan baris berikut:

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

Mengapa mode manual tidak dapat memperbarui dirinya sendiri

Setiap pembaruan adalah tantangan baru dengan token baru, sehingga nilai TXT berubah setiap saat. Rekaman yang Anda tempel hari ini tidak akan berguna dalam 60 hari. Timer pembaruan menjalankan Certbot secara otomatis dua kali sehari, dan tidak ada orang di depan keyboard untuk menempelkan nilai baru, sehingga sertifikat yang diterbitkan secara manual gagal diperbarui dengan error 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, tetapi pada titik tersebut Anda sedang membangun ulang plugin DNS secara manual. Gunakan mode manual untuk mempelajari alur kerja, atau untuk kebutuhan satu kali pada domain yang DNS-nya belum dapat Anda otomatisasi, dan pasang pengingat jauh sebelum hari ke-90, karena Let's Encrypt tidak lagi mengirimkan email kedaluwarsa. Untuk keperluan lainnya, gunakan plugin.

Jalur plugin: certbot-dns-cloudflare pada Ubuntu 24.04

Plugin DNS menyimpan kredensial API untuk penyedia DNS Anda dan melakukan seluruh proses rekaman TXT secara otomatis, saat penerbitan dan pada setiap pembaruan. Cloudflare digunakan sebagai contoh di sini karena merupakan plugin penyedia yang paling banyak dibutuhkan, dan sudah tersedia dalam paket Ubuntu.

Panduan Certbot kami merekomendasikan paket apt pada Ubuntu 24.04, dan ketentuan ini berlaku untuk Cloudflare:

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

Catatan mengenai versi. Repositori 24.04 menyertakan plugin ini pada versi 2.0.0 bersama dengan Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare menunjukkan versi Anda. Ketidaksesuaian ini tidak berbahaya, dan token API terbatas dapat berfungsi, karena library python3-cloudflare yang mendasarinya pada 24.04 adalah 2.11.1, lebih tinggi dari versi 2.3.1 yang dibutuhkan plugin untuk dukungan token. Pada rilis Ubuntu yang lebih lama, library tersebut terlalu lama untuk mendukung token, yang menjadi penyebab munculnya peringatan di internet mengenai plugin apt yang memaksa penggunaan Global API Key. Pada 24.04, peringatan tersebut tidak lagi berlaku.

Di dashboard Cloudflare, buatlah token API terbatas, bukan Global API Key: My Profile, lalu API Tokens, lalu Create Token, dengan izin tunggal Zone / DNS / Edit, yang dibatasi hanya pada satu zone tempat Anda menerbitkan sertifikat. Simpan 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 dan akan memberikan peringatan tentang Unsafe permissions on credentials configuration file jika file dapat dibaca oleh pengguna lain. Sekarang jalankan:

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

Plugin membuat rekaman TXT melalui API, menunggu jeda propagasi singkat, menjalankan validasi, lalu menghapus kembali rekaman tersebut. Jika name server zone Anda lambat dalam mendeteksi perubahan, tingkatkan waktu tunggu dengan --dns-cloudflare-propagation-seconds 60. Sertifikat akan disimpan di /etc/letsencrypt/live/example.com/, dan Anda dapat mengarahkan nginx atau Apache ke fullchain.pem dan privkey.pem tepat seperti yang ditunjukkan pada panduan dasar, termasuk deploy hook.

Jika plugin penyedia Anda tidak ada di apt

Arsip 24.04 hanya menyediakan paket plugin untuk beberapa penyedia saja, termasuk Cloudflare, Route 53, DigitalOcean, dan antarmuka generik RFC 2136. Jalankan apt search certbot-dns untuk melihat daftar tersebut. Jika penyedia Anda tidak ada, ini adalah satu kondisi di mana saran prioritas apt kami berubah: instal Certbot dan plugin melalui snap, lalu hapus Certbot dari apt terlebih dahulu agar dua timer pembaruan tidak bentrok pada /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 snap; plugin tersebut tidak dapat memperluas plugin apt, itulah sebabnya 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 memiliki API, atau menjalankan name server sendiri dan mengarahkan plugin rfc2136 ke server tersebut.

Pembaruan: buktikan sekarang, bukan dalam 60 hari

Certbot mencatat bagaimana setiap sertifikat diterbitkan di /etc/letsencrypt/renewal/example.com.conf, termasuk authenticator = dns-cloudflare dan jalur kredensial, sehingga timer standar dua kali sehari dapat memperbaruinya tanpa bantuan Anda. Lakukan simulasi seluruh proses menggunakan lingkungan staging:

sudo certbot renew --dry-run

Hasil sukses berarti kredensial berfungsi dan validasi selesai sepenuhnya; pembaruan asli dalam 60 hari akan mengikuti jalur yang sama. Ada dua langkah lanjutan yang perlu dilakukan hari ini. Pertama, sertifikat yang telah diperbarui di disk tidak akan mengubah apa pun sampai web server memuat ulangnya, jadi pasang deploy hook seperti yang dijelaskan dalam panduan nginx dan Apache. Kedua, jaga keamanan file kredensial: siapa pun yang dapat membacanya dapat mengedit zona DNS Anda, yang cukup untuk mengalihkan email atau melewati tantangan DNS-01 milik mereka sendiri. Simpan file tersebut dengan mode 600 di bawah /root, batasi token hanya untuk satu zona, dan lakukan rotasi jika Anda mencurigai adanya kebocoran.

Ketika Anda tidak memerlukan wildcard

Wildcard adalah alat yang tepat untuk banyak subdomain, atau untuk subdomain yang tidak dapat Anda prediksi. Wildcard bukan pilihan default yang tepat untuk hal 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, dan tidak ada kredensial DNS API yang tersimpan di server.
• Wildcard hanya cocok dengan satu label secara tepat. *.example.com tidak mencakup example.com, itulah sebabnya perintah di atas meminta keduanya, dan tidak mencakup a.b.example.com; hal tersebut memerlukan *.b.example.com.
• Satu kunci privat digunakan oleh setiap subdomain. Jika mesin yang menyimpannya disusupi, semua nama yang dicakup oleh wildcard akan terdampak secara bersamaan.
• Jika Traefik melakukan terminasi TLS (transport layer security) untuk kontainer Anda, Anda tidak memerlukan Certbot sama sekali: Traefik meminta sertifikat wildcard sendiri melalui DNS-01, menggunakan jenis token penyedia yang sama.

Kapan wildcard benar-benar berguna: subdomain per-pelanggan atau per-aplikasi yang dibuat lebih cepat daripada waktu penerbitan ulang sertifikat, dan host internal tanpa port 80 publik, seperti layanan yang hanya dapat dijangkau melalui VPN WireGuard. DNS-01 tidak pernah terhubung ke host yang disertifikasi, sehingga mesin yang sepenuhnya privat pun dapat memiliki sertifikat yang dipercaya secara publik.

FAQ

Bisakah Certbot menerbitkan sertifikat wildcard dengan HTTP-01?

Tidak. HTTP-01 membuktikan kontrol atas satu hostname, karena server validasi mengambil file token dari nama tersebut secara spesifik. Wildcard mencakup setiap nama di bawah domain tersebut, sehingga Let's Encrypt memerlukan tantangan DNS-01 untuknya, sedangkan autentikator --nginx, --apache, --webroot dan --standalone semuanya berbasis HTTP. Satu-satunya cara adalah melalui rekaman TXT di _acme-challenge.example.com, yang ditempatkan secara manual atau melalui plugin DNS.

Apakah sertifikat wildcard mencakup domain root?

Tidak. Wildcard hanya cocok dengan satu label secara tepat, sehingga *.example.com mencakup www.example.com tetapi tidak mencakup example.com polos, dan tidak mencakup a.b.example.com. Mintalah kedua nama tersebut dalam satu sertifikat menggunakan -d example.com -d '*.example.com'. Hal ini akan membuat dua tantangan, dan kedua rekaman TXT berada pada nama _acme-challenge.example.com yang sama, jadi tambahkan rekaman kedua tanpa menghapus rekaman pertama.

Mengapa sertifikat wildcard saya tidak diperbarui secara otomatis?

Karena sertifikat tersebut diterbitkan dengan --manual. Setiap pembaruan memerlukan nilai TXT baru, dan timer otomatis tidak dapat memasukkan nilai tersebut, sehingga pembaruan berhenti dengan error An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Terbitkan ulang sertifikat menggunakan plugin DNS seperti certbot-dns-cloudflare, atau sediakan skrip --manual-auth-hook dan --manual-cleanup-hook yang mengedit rekaman melalui API penyedia layanan Anda.

Berapa lama rekaman TXT _acme-challenge muncul?

Hal ini bergantung pada penyedia DNS Anda: mulai dari beberapa detik hingga beberapa menit. Validasi membaca server otoritatif zona Anda, jadi 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 rekaman tidak ditemukan.

Apakah sertifikat wildcard kurang aman daripada sertifikat biasa?

Kriptografinya identik. Perbedaannya bersifat operasional: satu kunci privat mencakup setiap subdomain, sehingga jika terjadi kompromi, dampaknya akan meluas, dan kredensial API DNS yang diperlukan oleh otomatisasi adalah rahasia sensitif yang disimpan di server. Jika Anda hanya menjalankan beberapa subdomain yang sudah diketahui, sertifikat SAN menghindari kedua masalah tersebut, yang merupakan alasan mengapa panduan ini menyarankan untuk melewatkan penggunaan wildcard.