Certbot : certificat wildcard avec le challenge DNS-01

Pourquoi un certificat wildcard nécessite 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é à un seul niveau. Let’s Encrypt délivre les certificats wildcard uniquement avec le challenge DNS-01. Certbot doit donc prouver le contrôle du DNS du domaine en publiant un enregistrement TXT à l’emplacement _acme-challenge.example.com. Le challenge HTTP-01 ne convient pas, car servir un fichier contenant un token prouve uniquement le contrôle d’un hostname, celui depuis lequel le serveur de validation a récupéré le fichier. Un wildcard concerne tous les noms possibles sous le domaine. Le seul enregistrement public qui représente tout cet espace de noms est le DNS.

Cette exigence détermine tout le reste de cette page. Pour réussir DNS-01, vous devez pouvoir créer des enregistrements TXT dans la zone du domaine, manuellement ou via l’API (application programming interface) de votre fournisseur DNS. La méthode manuelle fonctionne une fois, puis échoue lors du renouvellement, pour une raison précise expliquée ci-dessous. La méthode via l’API, avec un plugin DNS pour Certbot, renouvelle le certificat sans intervention. C’est la configuration à utiliser au terme de la procédure.

Il s’agit du chapitre consacré aux wildcard dans notre guide Certbot. Les certificats ordinaires pour un hostname unique, la configuration du serveur web et les règles du port 80 sont présentés dans Certbot avec nginx sur Ubuntu 24.04 et Certbot avec Apache sur Ubuntu 24.04.

Fonctionnement de l’enregistrement TXT _acme-challenge

Lorsque Certbot demande *.example.com, Let’s Encrypt répond avec un jeton aléatoire. Certbot combine ce jeton avec la clé de compte ACME (automatic certificate management environment), hache le résultat avec SHA-256, puis produit une courte valeur textuelle. Cette valeur doit apparaître dans un enregistrement TXT à l’adresse _acme-challenge.example.com. Let’s Encrypt interroge ensuite les serveurs de noms faisant autorité pour votre domaine depuis sa propre infrastructure. Si l’enregistrement lu correspond à la valeur attendue, vous prouvez que vous contrôlez la zone. Le contrôle de la zone est alors accepté comme preuve du contrôle de tous les noms qu’elle contient.

Deux points causent la plupart des échecs :

• Demander example.com et *.example.com dans le même certificat crée deux challenges distincts, et les deux enregistrements TXT se trouvent au même nom, _acme-challenge.example.com. Ils doivent tous deux exister simultanément. Ajouter le second enregistrement est correct ; remplacer le premier par le second fait échouer le premier challenge.
• La validation interroge vos serveurs faisant autorité, mais les panneaux de contrôle des fournisseurs peuvent mettre une minute ou plus à diffuser un nouvel enregistrement vers ces serveurs. Vérifiez depuis l’extérieur avant de lancer la validation :

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

Lorsque cette commande affiche la valeur demandée par Certbot, la validation peut réussir. Lorsqu’elle n’affiche rien, attendez, puis exécutez-la de nouveau.

Voir le mécanisme une fois : mode manuel

Le mode manuel vous oblige à modifier vous-même le DNS. C’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 se met en pause et affiche 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 l’interface de votre fournisseur DNS. Vérifiez ensuite qu’il est visible avec la commande dig ci-dessus, puis appuyez sur Entrée. Comme cette exécution demande le domaine nu et le wildcard, Certbot vous invite à effectuer l’opération deux fois. Laissez les deux enregistrements en place jusqu’à la fin de l’émission. En cas de succès, les lignes habituelles s’affichent :

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

Pourquoi le mode manuel ne peut pas se renouveler seul

Chaque renouvellement correspond à un nouveau challenge avec un nouveau token. La valeur TXT change donc à chaque fois. L’enregistrement que vous avez ajouté aujourd’hui sera inutile dans 60 jours. Le timer de renouvellement exécute Certbot sans intervention deux fois par jour. Personne n’est alors devant le clavier pour ajouter la nouvelle valeur. Le certificat obtenu en mode manuel échoue donc lors de 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 répondre à cette exigence en écrivant des scripts --manual-auth-hook qui appellent l’API de votre fournisseur DNS. Mais vous recréez alors manuellement un plugin DNS. Utilisez le mode manuel pour comprendre le fonctionnement ou pour un cas réellement ponctuel sur un domaine dont le DNS ne peut pas encore être automatisé. Définissez un rappel bien avant le 90e jour, car Let’s Encrypt n’envoie plus d’e-mails d’expiration. Dans tous les autres cas, utilisez un plugin.

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

Un plugin DNS conserve un identifiant d’API pour votre fournisseur DNS et gère lui-même toute la procédure liée à l’enregistrement TXT, lors de l’émission puis à chaque renouvellement. Cloudflare sert ici d’exemple, car c’est le plugin de fournisseur dont la plupart des utilisateurs ont besoin et il est fourni dans Ubuntu.

Nos guides Certbot recommandent les paquets apt sur Ubuntu 24.04. Cette recommandation s’applique également à Cloudflare :

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

Une précision concernant les versions. L’archive 24.04 fournit ce plugin en version 2.0.0 avec Certbot 2.9.0 ; apt policy python3-certbot-dns-cloudflare affiche votre version. Cette différence ne pose pas de problème. Les API tokens à portée limitée fonctionnent, car la bibliothèque python3-cloudflare sous-jacente dans 24.04 est en version 2.11.1, supérieure à la version 2.3.1 dont le plugin a besoin pour prendre en charge les tokens. Sur les anciennes versions d’Ubuntu, cette bibliothèque était trop ancienne pour les tokens. C’est l’origine des avertissements que vous pouvez trouver en ligne concernant le plugin apt, qui imposerait la Global API Key. Ils ne s’appliquent plus sur 24.04.

Dans le tableau de bord Cloudflare, créez un API token à portée limitée, et non la Global API Key : My Profile, puis API Tokens, puis Create Token. Sélectionnez l’unique permission Zone / DNS / Edit et limitez-la à la zone pour laquelle vous émettez le certificat. 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 le mode du fichier et émet un avertissement concernant Unsafe permissions on credentials configuration file si d’autres utilisateurs peuvent le lire. Lancez ensuite l’émission :

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 les enregistrements. Si les serveurs de noms de votre zone mettent du temps à prendre en compte les changements, augmentez l’attente avec --dns-cloudflare-propagation-seconds 60. Le certificat est placé dans /etc/letsencrypt/live/example.com/. Configurez nginx ou Apache pour utiliser fullchain.pem et privkey.pem, exactement comme dans les guides de base, y compris le deploy hook.

Si le plugin de votre fournisseur n’est pas disponible dans apt

L’archive 24.04 ne fournit des plugins que pour quelques fournisseurs, notamment Cloudflare, Route 53, DigitalOcean et l’interface générique RFC 2136. Exécutez apt search certbot-dns pour afficher la liste. Si votre fournisseur n’y figure pas, c’est le seul cas où nous dérogeons à la recommandation d’utiliser apt en priorité : installez plutôt Certbot et le plugin depuis snap, et désinstallez d’abord Certbot installé avec apt afin 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’à Certbot installé avec snap ; il ne peut pas étendre celui installé avec apt. Les deux installations ne doivent donc pas coexister. Si votre hébergeur DNS ne propose aucune API, vos options réalistes sont de déplacer le DNS du domaine vers un fournisseur qui en propose une, ou d’exécuter votre propre serveur de noms et de pointer le plugin rfc2136 vers celui-ci.

Renouvellement : validez-le maintenant, pas dans 60 jours

Certbot enregistre la manière dont chaque certificat a été émis dans /etc/letsencrypt/renewal/example.com.conf, notamment authenticator = dns-cloudflare et le chemin du fichier d’identifiants. Le timer standard, exécuté deux fois par jour, peut ainsi renouveler le certificat sans intervention de votre part. Répétez toute la procédure avec l’environnement de staging :

sudo certbot renew --dry-run

Une exécution réussie signifie que les identifiants fonctionnent et que la validation s’effectue de bout en bout. Le renouvellement réel dans 60 jours suivra le même parcours. Deux actions complémentaires sont utiles dès aujourd’hui. Premièrement, le renouvellement d’un certificat sur le disque ne change rien tant que le serveur web ne recharge pas ce certificat. Configurez donc le deploy hook décrit dans les guides nginx et Apache. Deuxièmement, protégez le fichier d’identifiants : toute personne pouvant le lire peut modifier votre zone DNS, ce qui suffit pour rediriger votre messagerie ou réussir ses propres challenges DNS-01. Définissez ses permissions sur 600 sous /root, limitez le token à une seule zone et faites-le tourner si vous suspectez la moindre fuite.

Quand vous n’avez pas besoin d’un wildcard

Un wildcard convient lorsque vous gérez de nombreux sous-domaines ou des sous-domaines impossibles à prévoir. Ce n’est pas le choix par défaut dans les autres cas.

• Un seul sous-domaine, ou quelques sous-domaines connus : un certificat SAN (subject alternative name) classique est plus simple. certbot --nginx -d example.com -d www.example.com -d app.example.com couvre jusqu’à 100 noms avec HTTP-01 classique, et aucun identifiant d’API DNS ne se trouve sur le serveur.
• Un wildcard correspond à un seul label. *.example.com ne couvre pas le domaine nu example.com, d’où les commandes ci-dessus qui demandent les deux certificats. Il ne couvre pas non plus a.b.example.com ; cela nécessiterait *.b.example.com.
• Une même clé privée est utilisée pour tous les sous-domaines. Si la machine qui la contient est compromise, tous les noms couverts par le wildcard sont affectés en même temps.
• Si Traefik assure la terminaison TLS (transport layer security) pour vos conteneurs, vous n’avez pas besoin de Certbot : Traefik demande lui-même les certificats wildcard via DNS-01, avec le même type de token de fournisseur.

Le wildcard est réellement utile pour les sous-domaines par client ou par application créés plus rapidement que vous ne souhaitez réémettre les certificats, ainsi que pour les hôtes internes sans port 80 public, par exemple les services accessibles uniquement via un VPN WireGuard. DNS-01 ne se connecte jamais à l’hôte dont le certificat est émis. Même une machine entièrement privée peut donc utiliser un certificat approuvé publiquement.

FAQ

Certbot peut-il délivrer 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 de token à cette adresse exacte. Un wildcard couvre tous les noms du domaine. Let’s Encrypt exige donc le challenge DNS-01, tandis que les authenticators --nginx, --apache, --webroot et --standalone utilisent tous HTTP. La seule possibilité consiste à créer un enregistrement TXT à _acme-challenge.example.com, manuellement ou avec un plugin DNS.

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

Non. Le wildcard correspond à un seul label. *.example.com couvre donc www.example.com, mais pas le domaine nu example.com ni a.b.example.com. Demandez les deux noms dans un même certificat avec -d example.com -d '*.example.com'. Cela crée deux challenges. Les deux enregistrements TXT utilisent alors le même nom _acme-challenge.example.com. Ajoutez le second enregistrement sans supprimer le premier.

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

Parce qu’il a été délivré avec --manual. Chaque renouvellement nécessite une nouvelle valeur TXT. Le timer unattended ne peut pas l’ajouter, 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 les scripts --manual-auth-hook et --manual-cleanup-hook pour modifier l’enregistrement via l’API de votre fournisseur.

Combien de temps faut-il pour que l’enregistrement TXT _acme-challenge apparaisse ?

Cela dépend de votre fournisseur DNS : de quelques secondes à plusieurs minutes. La validation interroge les serveurs faisant autorité pour votre zone. 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 le délai d’attente intégré via l’option de propagation du plugin, par exemple --dns-cloudflare-propagation-seconds 60, si la validation indique que l’enregistrement est introuvable.

Un certificat wildcard est-il moins sécurisé qu’un certificat normal ?

La cryptographie est identique. Les différences sont opérationnelles : une seule clé privée couvre tous les sous-domaines, donc une compromission peut avoir une portée plus importante. De plus, l’identifiant d’API DNS requis par l’automatisation est lui-même un secret sensible stocké sur le serveur. Si vous n’utilisez que quelques sous-domaines connus, un certificat SAN évite ces deux problèmes. C’est précisément dans ce cas que ce guide recommande de ne pas utiliser de wildcard.