Certbotでワイルドカード証明書をDNS-01で取得する方法

ワイルドカード証明書に DNS-01 が必要な理由

ワイルドカード証明書は、ドメイン直下のすべてのサブドメインをカバーします。*.example.com は app.example.com、blog.example.com、その他の 1 階層下にあるすべての名前に一致します。Let's Encrypt は DNS-01 チャレンジでのみワイルドカード証明書を発行するため、Certbot は _acme-challenge.example.com に TXT レコードを公開して、ドメインの DNS を管理していることを証明する必要があります。HTTP-01 チャレンジでは不十分です。トークンファイルの提供で証明できるのは、検証サーバーがそのファイルを取得した 1 つのホスト名の管理権限だけだからです。ワイルドカードは、ドメイン直下に存在し得るすべての名前についての申告です。この名前空間全体を示せる公開情報は DNS だけです。

この要件によって、このページの他のすべてが決まります。DNS-01 を通過するには、ドメインのゾーン、または _acme-challenge が CNAME で参照する別の検証ゾーン（後述）に、手動または DNS プロバイダーの API（アプリケーションプログラミングインターフェース）を使って TXT レコードを作成できなければなりません。手動で行う方法は 1 回は機能しますが、具体的な理由により更新時に失敗します。その理由は後述します。Certbot DNS プラグインを使う API 方式なら自動更新できるため、最終的にはこの構成にしてください。

これは Certbot ガイドのワイルドカード編です。通常の単一ホスト名証明書、Web サーバーの設定、ポート 80 のルールについては、Ubuntu 24.04 で nginx に Certbot を設定する と Ubuntu 24.04 で Apache に Certbot を設定するで説明しています。

_acme-challenge TXT レコードの仕組み

Certbot が *.example.com を要求すると、Let's Encrypt はランダムなトークンを返します。Certbot はそのトークンを ACME（automatic certificate management environment）アカウントキーと組み合わせ、SHA-256 でハッシュ化して、短いテキスト値を生成します。この値は _acme-challenge.example.com の TXT レコードとして存在する必要があります。Let's Encrypt は、自身のインフラストラクチャからドメインの権威ネームサーバーに問い合わせます。読み取ったレコードが期待する値と一致すると、ゾーンを管理していることが証明されます。ゾーンの管理権限は、そのゾーン配下のすべての名前を管理する権限として認められます。

ほとんどの失敗は、次の2つの点が原因です。

• 同じ証明書で example.com と *.example.com を要求すると、別々の2つのチャレンジになります。両方の TXT レコードは、同じ名前 _acme-challenge.example.com に配置されます。両方を同時に存在させる必要があります。2つ目のレコードを追加するのは正しい方法です。1つ目を2つ目で置き換えると、1つ目のチャレンジに失敗します。
• 検証では権威サーバーを参照しますが、プロバイダーのコントロールパネルが新しいレコードを権威サーバーへ反映するまで、1分以上かかることがあります。検証を実行する前に、外部から確認してください。

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

Certbot が要求した値が表示されれば、検証は成功します。何も表示されない場合は、待ってからもう一度実行してください。

1回だけ動作を確認する: 手動モード

手動モードでは、DNSの編集を自分で行います。自動化する前に仕組みを理解するには、この方法が最適です。

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

ワイルドカードを囲む引用符によって、シェルが*をファイル名パターンとして扱わないようにします。Certbotは指示を表示して一時停止します。

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

DNSプロバイダーの管理画面でそのTXTレコードを作成します。上記のdigコマンドで表示されることを確認してから、Enterを押してください。この実行ではベアドメインとワイルドカードを要求するため、Certbotは2回プロンプトを表示します。発行が完了するまで、両方のレコードを残しておいてください。成功すると、次の見慣れた行で終了します。

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

手動モードでは自動更新できない理由

更新のたびに、新しいトークンを使った新しいチャレンジが実行されます。そのため、TXT 値は毎回変わります。今日貼り付けたレコードは、60日後には使えません。更新タイマーは Certbot を1日2回、無人で実行します。新しい値を貼り付ける人がいないため、手動で発行した証明書の更新は次のエラーで失敗します。

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 プロバイダーの API を呼び出す --manual-auth-hook スクリプトを作成すれば、この要件を満たせます。ただし、その時点で DNS plugin を手作業で再構築することになります。手動モードは、処理の流れを学ぶ場合や、DNS をまだ自動化できないドメインで本当に1回だけ実行する場合に使用してください。また、Let's Encrypt は有効期限のメール通知を送信しなくなったため、90日目より十分前にリマインダーを設定してください。それ以外の場合は、plugin を使用してください。

プラグイン方式: Ubuntu 24.04 での certbot-dns-cloudflare

DNSプラグインは、DNSプロバイダーのAPI認証情報を保持し、証明書の発行時と更新時に、TXTレコードの処理全体を自動で実行します。ここではCloudflareを例にします。Cloudflareは、多くのユーザーが必要とするプロバイダープラグインであり、Ubuntuのパッケージとして提供されているためです。

Certbotガイドでは、Ubuntu 24.04でaptパッケージを使用することを推奨しています。Cloudflareでもこの方針が適用されます。

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

バージョンについて、正確な情報を説明します。24.04のアーカイブでは、このプラグインはCertbot 2.9.0とともにバージョン2.0.0で提供されています。apt policy python3-certbot-dns-cloudflareで実際のバージョンを確認できます。この不一致による問題はありません。スコープを限定したAPIトークンも使用できます。24.04に含まれる基盤のpython3-cloudflareライブラリは2.11.1で、トークンのサポートに必要な2.3.1を上回っているためです。古いUbuntuリリースでは、このライブラリがトークンを使用するには古すぎました。そのため、aptプラグインがGlobal API Keyの使用を強制するという警告が、オンラインで見つかることがあります。24.04では、この警告は該当しません。

Cloudflareのダッシュボードで、Global API Keyではなくスコープを限定したAPIトークンを作成します。My Profile、API Tokens、Create Tokenの順に選択し、権限はZone / DNS / Editのみ設定します。発行対象の1つのゾーンだけに制限してください。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'

プラグインはAPI経由でTXTレコードを作成し、短い伝播待ち時間の後に検証を実行し、完了するとレコードを削除します。ゾーンのネームサーバーが変更を反映するまで時間がかかる場合は、--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 からインストールし、その前に apt 版 Certbot を削除してください。そうしないと、2 つの更新タイマーが /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 版 Certbot を拡張することはできません。そのため、2 つのインストールを共存させてはいけません。DNS ホストが API をまったく提供していない場合、現実的な選択肢は 3 つあります。ドメインの DNS を API を持つプロバイダーへ移行できます。自分でネームサーバーを運用し、rfc2136 プラグインからそのサーバーを指定できます。または、現在の DNS ホストを使い続けたまま、_acme-challenge.example.com から API を持つ検証ゾーンへ 1 回限りの CNAME を追加できます。たとえば、ホスティング型の acme-dns サービスや、自分で運用する acme-dns サーバーを使えます。Let's Encrypt は検証時にこの CNAME をたどります。そのため、TXT レコードは委任先のゾーンに置かれ、メインゾーンを再度変更する必要はありません。

更新: 60日後ではなく、今すぐ確認する

Certbotは、各証明書の発行方法を/etc/letsencrypt/renewal/example.com.confに記録します。authenticator = dns-cloudflareと認証情報のパスも記録されるため、標準の1日2回のタイマーが自動的に更新します。ステージング環境に対して、一連の処理を最初から最後まで確認します。

sudo certbot renew --dry-run

成功すれば、認証情報が機能し、検証が最初から最後まで完了したことを意味します。60日後の実際の更新も同じ経路で実行されます。今のうちに、次の2点も実施してください。まず、ディスク上の証明書を更新しても、web serverが再読み込みしなければ変更は反映されません。そのため、nginxおよびApacheのガイドで説明されているdeploy hookを設定します。次に、認証情報ファイルを厳重に扱います。このファイルを読み取れるユーザーは、DNS zoneを編集できます。これだけで、メールの転送先を変更したり、独自のDNS-01 challengeに応答したりできます。/rootの下にmode 600で保存し、tokenの権限を1つのzoneに限定します。漏えいの疑いがある場合は、tokenを更新してください。

ワイルドカードが不要な場合

ワイルドカードは、多数のサブドメインや、予測できないサブドメインに適しています。それ以外では、デフォルトで使用するべきではありません。

• 1つのサブドメイン、または既知の少数のサブドメインの場合は、通常の SAN (subject alternative name) 証明書の方が簡単です。certbot --nginx -d example.com -d www.example.com -d app.example.com は通常の HTTP-01 で最大 100 個の名前をカバーします。また、DNS API の認証情報をサーバー上に置く必要もありません。
• ワイルドカードが一致するのは、1つのラベルだけです。*.example.com は裸の example.com をカバーしません。そのため、上記のコマンドでは両方を要求しています。また、a.b.example.com もカバーしません。これには *.b.example.com が必要です。
• すべてのサブドメインが、1つの秘密鍵を使用します。その鍵を保持するマシンが侵害されると、ワイルドカードがカバーするすべての名前が同時に影響を受けます。
• Traefik がコンテナの TLS (transport layer security) を終端する場合、Certbot を使用する必要はありません。Traefik は DNS-01 を使用してワイルドカード証明書を自ら要求します。プロバイダーのトークンには、同じ種類のものを使用します。

ワイルドカードが有効なのは、証明書を再発行するよりも速いペースで作成する顧客別またはアプリ別のサブドメインです。また、パブリックな port 80 を持たない内部ホストにも適しています。たとえば、WireGuard VPN 経由でのみアクセスできるサービスです。DNS-01 は証明書の対象ホストに接続しません。そのため、完全にプライベートなマシンでも、公開で信頼される証明書を保持できます。

FAQ

Certbot は HTTP-01 でワイルドカード証明書を発行できますか？

いいえ。HTTP-01 で証明できるのは 1 つのホスト名の管理権限です。検証サーバーが、その名前からトークンファイルを取得するためです。ワイルドカードはドメイン直下のすべての名前をカバーします。そのため、Let's Encrypt は DNS-01 チャレンジを要求します。--nginx、--apache、--webroot、--standalone の認証方式はいずれも HTTP ベースです。使用できる方法は、_acme-challenge.example.com に TXT レコードを置くことだけです。CNAME で委任されたゾーンを使用する場合は、そのゾーンに配置します。レコードは手動または DNS プラグインで追加します。

ワイルドカード証明書はルートドメインをカバーしますか？

いいえ。ワイルドカードが一致するのは 1 つのラベルだけです。そのため、*.example.com は www.example.com には一致しますが、裸の example.com には一致せず、a.b.example.com にも一致しません。-d example.com -d '*.example.com' を使って、両方の名前を 1 つの証明書に含めて申請してください。これにより 2 つのチャレンジが作成されます。両方の TXT レコードは同じ _acme-challenge.example.com 名に置かれるため、最初のレコードを削除せずに 2 つ目のレコードを追加してください。

ワイルドカード証明書が自動更新されないのはなぜですか？

--manual を使って発行したためです。更新のたびに新しい TXT 値が必要になります。自動更新タイマーにはその値を入力する方法がないため、更新は An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively エラーで停止します。certbot-dns-cloudflare などの DNS プラグインを使って証明書を再発行するか、--manual-auth-hook と --manual-cleanup-hook のスクリプトを用意して、プロバイダーの API 経由でレコードを編集してください。

_acme-challenge TXT レコードが表示されるまでどのくらいかかりますか？

DNS プロバイダーによって異なります。数秒から数分かかることがあります。検証ではゾーンの権威 DNS サーバーが参照されるため、dig +short TXT _acme-challenge.example.com @1.1.1.1 で確認し、手動実行を続ける前に期待する値が表示されるまで待ってください。プラグインを使う場合、検証でレコードが見つからないと報告されたときは、プラグインの伝播オプションで組み込みの待機時間を延長できます。たとえば --dns-cloudflare-propagation-seconds 60 を指定します。

ワイルドカード証明書は通常の証明書より安全性が低いですか？

暗号方式は同じです。違いは運用面にあります。1 つの秘密鍵がすべてのサブドメインをカバーするため、侵害された場合の影響範囲が広くなります。また、自動化に必要な DNS API の認証情報も、サーバーに保存する機密情報です。既知のサブドメインを少数だけ運用する場合は、SAN 証明書によってこの 2 つの懸念を回避できます。そのため、このガイドではその場合にワイルドカードの使用を避けることを推奨しています。