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

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

ワイルドカード証明書は、ドメインのすべての第1階層サブドメインを対象にします。*.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 に合格するには、手動または DNS プロバイダーの API（application programming interface）を使用して、ドメインのゾーンに TXT レコードを作成できなければなりません。手動の方法は一度は機能しますが、以下に示す明確な理由により更新時に失敗します。Certbot DNS plugin を使用する API の方法では、自動で更新できます。最終的にはこの構成にしてください。

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

_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 を優先する方針を変更する必要がある唯一の箇所です。先に apt の Certbot を削除し、Certbot とプラグインを snap からインストールしてください。これにより、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 をまったく提供していない場合、現実的な選択肢は、ドメインの DNS を API を備えたプロバイダーへ移すか、自分でネームサーバーを運用して rfc2136 プラグインの接続先に指定することです。

更新: 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のauthenticatorはすべてHTTPベースです。方法は、_acme-challenge.example.comにTXTレコードを配置することだけです。手動で配置することも、DNS pluginで配置することもできます。

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

いいえ。ワイルドカードは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値が必要です。unattended timerにはその値を入力する方法がないため、An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactivelyエラーで更新が停止します。certbot-dns-cloudflareなどのDNS pluginを使用して証明書を再発行してください。または、providerのAPI経由でレコードを編集する--manual-auth-hookおよび--manual-cleanup-hookスクリプトを指定してください。

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

DNS providerによって異なります。数秒から数分かかる場合があります。検証ではゾーンのauthoritative serverが読み取られるため、dig +short TXT _acme-challenge.example.com @1.1.1.1で確認し、手動実行を続ける前に期待する値が表示されるまで待ってください。pluginを使用する場合、レコードが見つからないと検証で報告されたときは、--dns-cloudflare-propagation-seconds 60などのpluginの伝播オプションで組み込みの待機時間を延長してください。

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

暗号方式は同一です。違いは運用面にあります。1つのprivate keyがすべてのサブドメインを対象にするため、侵害された場合の影響範囲が広がります。また、自動化に必要なDNS API credential自体が、serverに保存される重要なsecretです。既知のサブドメインを少数だけ運用する場合は、SAN certificateによってこの両方の懸念を回避できます。そのため、このガイドではその場合にワイルドカードの使用を推奨していません。