Certificats wildcard Certbot avec DNS-01

Pourquoi un certificat wildcard exige DNS-01

Un certificat wildcard couvre tous les sous-domaines de premier niveau d'un domaine : *.example.com correspond à app.example.com, blog.example.com et tout autre nom situé à une étiquette de profondeur. Let's Encrypt n'émet des certificats wildcard qu'à travers le défi DNS-01. Certbot doit donc prouver qu'il contrôle le DNS du domaine en publiant un enregistrement TXT à _acme-challenge.example.com. Le défi HTTP-01 ne convient pas, car servir un fichier jeton prouve le contrôle d'un seul nom d'hôte, celui à partir duquel le serveur de validation a récupéré le fichier. Un wildcard est une revendication sur tous les noms possibles sous le domaine, et le seul enregistrement public qui parle pour l'espace de noms entier, c'est le DNS lui-même.

Cette seule exigence détermine tout le reste de cette page. Pour réussir le défi DNS-01, vous devez pouvoir créer des enregistrements TXT dans la zone du domaine, soit à la main, soit via l'API (interface de programmation applicative) de votre fournisseur DNS. La méthode manuelle fonctionne une fois, puis échoue au renouvellement, pour une raison concrète montrée plus bas. La méthode par API, à travers un plugin DNS de Certbot, se renouvelle sans intervention, et c'est la configuration à laquelle vous devez aboutir.

C'est le chapitre wildcard de nos guides Certbot. Les certificats ordinaires à nom d'hôte unique, la configuration du serveur web et les règles du port 80 sont traités dans Certbot avec nginx sur Ubuntu 24.04 et Certbot avec Apache sur Ubuntu 24.04.

Comment fonctionne l'enregistrement TXT _acme-challenge

Quand Certbot demande *.example.com, Let's Encrypt répond avec un jeton aléatoire. Certbot combine ce jeton avec la clé de votre compte ACME (automatic certificate management environment), hache le résultat avec SHA-256 et produit une courte valeur texte. Cette valeur doit apparaître comme un enregistrement TXT à _acme-challenge.example.com. Let's Encrypt interroge ensuite les serveurs de noms faisant autorité de votre domaine depuis sa propre infrastructure. Si l'enregistrement qu'il lit correspond à la valeur attendue, vous avez prouvé que vous contrôlez la zone, et le contrôle de la zone est accepté comme le contrôle de tous les noms qui en dépendent.

Deux détails causent la plupart des échecs :

• Demander example.com et *.example.com sur le même certificat signifie deux défis distincts, et les deux enregistrements TXT vivent au même nom, _acme-challenge.example.com. Les deux doivent exister en même temps. Ajouter le second enregistrement est correct ; remplacer le premier par le second fait échouer le premier défi.
• La validation lit vos serveurs faisant autorité, mais les panneaux de contrôle des fournisseurs peuvent prendre une minute ou plus pour y propager un nouvel enregistrement. Vérifiez depuis l'extérieur avant de laisser la validation s'exécuter :

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

Quand cette commande affiche la valeur demandée par Certbot, la validation peut réussir. Quand elle n'affiche rien, attendez et relancez-la.

Voyez-le fonctionner une fois : le mode manuel

Le mode manuel vous fait faire l'édition DNS vous-même, ce qui est la meilleure façon de comprendre le mécanisme avant de l'automatiser :

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

Les guillemets autour du wildcard empêchent votre shell de traiter * comme un motif de nom de fichier. Certbot s'interrompt avec des instructions :

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

Créez cet enregistrement TXT dans le panneau de votre fournisseur DNS, confirmez qu'il est visible avec la commande dig ci-dessus, et alors seulement appuyez sur Entrée. Comme cette exécution demande le domaine nu et le wildcard, Certbot vous invite deux fois ; gardez les deux enregistrements en place jusqu'à la fin de l'émission. Le succès se termine par les lignes familières :

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

Pourquoi le mode manuel ne peut pas se renouveler

Chaque renouvellement est un nouveau défi avec un nouveau jeton, donc la valeur TXT change à chaque fois. L'enregistrement que vous avez collé aujourd'hui est inutile dans 60 jours. Le timer de renouvellement lance Certbot sans surveillance deux fois par jour, et personne n'est au clavier pour coller la nouvelle valeur, donc un certificat émis manuellement échoue à son renouvellement avec cette erreur exacte :

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

Vous pouvez satisfaire cette exigence en écrivant des scripts --manual-auth-hook qui appellent l'API de votre fournisseur DNS, mais à ce stade vous reconstruisez un plugin DNS à la main. Utilisez le mode manuel pour apprendre le déroulement, ou pour un cas vraiment ponctuel sur un domaine dont vous ne pouvez pas encore automatiser le DNS, et programmez un rappel bien avant le 90e jour, car Let's Encrypt n'envoie plus d'e-mails d'expiration. Pour tout le reste, utilisez un plugin.

La méthode par plugin : certbot-dns-cloudflare sur Ubuntu 24.04

Un plugin DNS détient un identifiant d'API pour votre fournisseur DNS et effectue lui-même toute la chorégraphie de l'enregistrement TXT, à l'émission puis à chaque renouvellement. Cloudflare est l'exemple traité ici parce que c'est le plugin fournisseur dont la plupart des gens ont besoin, et qu'il est packagé dans Ubuntu.

Nos guides Certbot recommandent les paquets apt sur Ubuntu 24.04, et cette position vaut aussi pour Cloudflare :

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

Une note honnête sur les versions. L'archive 24.04 fournit ce plugin en version 2.0.0 à côté de Certbot 2.9.0 ; apt policy python3-certbot-dns-cloudflare affiche la vôtre. L'écart est sans danger, et les jetons d'API à portée limitée fonctionnent, car la bibliothèque python3-cloudflare sous-jacente dans 24.04 est en 2.11.1, au-dessus du 2.3.1 dont le plugin a besoin pour la prise en charge des jetons. Sur les versions plus anciennes d'Ubuntu, cette bibliothèque était trop ancienne pour les jetons, d'où viennent les avertissements que vous pouvez trouver en ligne au sujet du plugin apt qui force la Global API Key. Sur 24.04, ils ne s'appliquent plus.

Dans le tableau de bord Cloudflare, créez un jeton d'API à portée limitée, pas la Global API Key : My Profile, puis API Tokens, puis Create Token, avec la seule permission Zone / DNS / Edit, limitée à la seule zone pour laquelle vous émettez. Placez-le dans un fichier que seul root peut lire :

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 vérifie les permissions et avertit avec Unsafe permissions on credentials configuration file si le fichier est lisible par d'autres. Émettez maintenant :

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

Le plugin crée les enregistrements TXT via l'API, attend un court délai de propagation, laisse la validation s'exécuter, puis supprime à nouveau les enregistrements. Si les serveurs de noms de votre zone sont lents à prendre en compte les changements, augmentez l'attente avec --dns-cloudflare-propagation-seconds 60. Le certificat arrive dans /etc/letsencrypt/live/example.com/, et vous pointez nginx ou Apache vers fullchain.pem et privkey.pem exactement comme le montrent les guides de base, hook de déploiement compris.

Si le plugin de votre fournisseur n'est pas dans apt

L'archive 24.04 ne package des plugins que pour une poignée de fournisseurs, dont Cloudflare, Route 53, DigitalOcean et l'interface générique RFC 2136. Lancez apt search certbot-dns pour voir la liste. Si votre fournisseur manque, c'est le seul endroit où notre conseil « apt d'abord » plie : installez plutôt Certbot et le plugin depuis snap, et retirez d'abord le Certbot apt pour que deux timers de renouvellement ne se disputent jamais /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

Un plugin snap ne se connecte qu'au Certbot snap ; il ne peut pas étendre celui d'apt, c'est pourquoi les deux installations ne doivent pas coexister. Et si votre hébergeur DNS n'offre aucune API, vos options réalistes sont de déplacer le DNS du domaine vers un fournisseur qui en a une, ou de faire tourner votre propre serveur de noms et d'y pointer le plugin rfc2136.

Renouvellement : prouvez-le maintenant, pas dans 60 jours

Certbot enregistre comment chaque certificat a été émis dans /etc/letsencrypt/renewal/example.com.conf, y compris authenticator = dns-cloudflare et le chemin des identifiants, si bien que le timer standard, deux fois par jour, le renouvelle sans aucune aide de votre part. Répétez l'ensemble contre l'environnement de test :

sudo certbot renew --dry-run

Une réussite signifie que l'identifiant fonctionne et que la validation se déroule de bout en bout ; le vrai renouvellement dans 60 jours suit le même chemin. Deux suites valent la peine d'être faites aujourd'hui. D'abord, un certificat renouvelé sur le disque ne change rien tant que le serveur web ne le recharge pas, donc branchez le hook de déploiement décrit dans les guides nginx et Apache. Ensuite, traitez le fichier d'identifiants avec respect : quiconque peut le lire peut modifier votre zone DNS, ce qui suffit à rediriger votre courrier ou à passer ses propres défis DNS-01. Gardez-le en mode 600 sous /root, limitez la portée du jeton à une seule zone, et faites-le tourner si vous soupçonnez une fuite.

Quand vous n'avez pas besoin d'un wildcard

Un wildcard est le bon outil pour de nombreux sous-domaines, ou pour des sous-domaines que vous ne pouvez pas prévoir. C'est un mauvais choix par défaut pour tout le reste.

• Un seul sous-domaine, ou une poignée de sous-domaines connus : un certificat SAN (subject alternative name) normal est plus simple. certbot --nginx -d example.com -d www.example.com -d app.example.com couvre jusqu'à 100 noms via un simple HTTP-01, et aucun identifiant d'API DNS ne se trouve jamais sur le serveur.
• Un wildcard correspond à exactement une étiquette. *.example.com ne couvre pas le example.com nu, c'est pourquoi les commandes ci-dessus demandent les deux, et il ne couvre pas non plus a.b.example.com ; cela nécessiterait *.b.example.com.
• Une seule clé privée se tient derrière chaque sous-domaine. Si la machine qui la détient est compromise, tous les noms que le wildcard couvre sont touchés d'un coup.
• Si Traefik termine le TLS (transport layer security) pour vos conteneurs, vous n'avez pas du tout besoin de Certbot dans le tableau : Traefik demande lui-même les certificats wildcard via DNS-01, en utilisant le même genre de jeton fournisseur.

Là où le wildcard justifie vraiment sa place : les sous-domaines par client ou par application créés plus vite que vous ne voulez réémettre des certificats, et les hôtes internes sans port 80 public, comme les services accessibles uniquement à travers un VPN WireGuard. DNS-01 ne se connecte jamais à l'hôte certifié, si bien que même une machine entièrement privée peut détenir un certificat publiquement approuvé.

FAQ

Certbot peut-il émettre un certificat wildcard avec HTTP-01 ?

Non. HTTP-01 prouve le contrôle d'un seul nom d'hôte, car le serveur de validation récupère un fichier jeton depuis ce nom exact. Un wildcard couvre tous les noms sous le domaine, donc Let's Encrypt exige le défi DNS-01 pour lui, et les authentificateurs --nginx, --apache, --webroot et --standalone sont tous basés sur HTTP. La seule voie est un enregistrement TXT à _acme-challenge.example.com, placé manuellement ou par un plugin DNS.

Un certificat wildcard couvre-t-il le domaine racine ?

Non. Le wildcard correspond à exactement une étiquette, donc *.example.com couvre www.example.com mais pas le example.com nu, et pas a.b.example.com. Demandez les deux noms sur un même certificat avec -d example.com -d '*.example.com'. Cela crée deux défis, et les deux enregistrements TXT se trouvent au même nom _acme-challenge.example.com, donc ajoutez le second enregistrement sans supprimer le premier.

Pourquoi mon certificat wildcard ne se renouvelle-t-il pas automatiquement ?

Parce qu'il a été émis avec --manual. Chaque renouvellement a besoin d'une valeur TXT toute neuve, et le timer sans surveillance n'a aucun moyen de la coller, donc le renouvellement s'arrête avec l'erreur An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Réémettez le certificat avec un plugin DNS comme certbot-dns-cloudflare, ou fournissez des scripts --manual-auth-hook et --manual-cleanup-hook qui modifient l'enregistrement via l'API de votre fournisseur.

Combien de temps l'enregistrement TXT _acme-challenge met-il à apparaître ?

Cela dépend de votre fournisseur DNS : de quelques secondes à plusieurs minutes. La validation lit les serveurs faisant autorité de votre zone, donc vérifiez avec dig +short TXT _acme-challenge.example.com @1.1.1.1 et attendez que la valeur attendue apparaisse avant de poursuivre une exécution manuelle. Avec un plugin, augmentez l'attente intégrée via l'option de propagation du plugin, par exemple --dns-cloudflare-propagation-seconds 60, si la validation signale que l'enregistrement est introuvable.

Un certificat wildcard est-il moins sûr qu'un certificat normal ?

La cryptographie est identique. Les différences sont opérationnelles : une seule clé privée couvre chaque sous-domaine, donc une compromission porte plus loin, et l'identifiant d'API DNS que l'automatisation exige est lui-même un secret sensible stocké sur le serveur. Si vous n'exploitez que quelques sous-domaines connus, un certificat SAN évite les deux soucis, ce qui est exactement le moment où ce guide recommande de renoncer au wildcard.