Certbot: certificados comodín con el desafío DNS-01

Por qué un certificado comodín necesita DNS-01

Un certificado comodín cubre todos los subdominios de primer nivel de un dominio: *.example.com coincide con app.example.com, blog.example.com y cualquier otro nombre con una sola etiqueta de profundidad. Let's Encrypt emite certificados comodín únicamente mediante el desafío DNS-01, por lo que Certbot debe demostrar el control del DNS del dominio publicando un registro TXT en _acme-challenge.example.com. El desafío HTTP-01 no puede cumplir este objetivo, porque servir un archivo con un token demuestra el control de un solo nombre de host: aquel desde el que el servidor de validación obtuvo el archivo. Un comodín es una afirmación sobre todos los nombres posibles bajo el dominio, y el único registro público que representa todo el espacio de nombres es el DNS.

Este requisito determina todo lo demás en esta página. Para superar DNS-01, debe poder crear registros TXT en la zona del dominio, manualmente o mediante la API (interfaz de programación de aplicaciones) de su proveedor de DNS. El método manual funciona una vez y después falla durante la renovación, por un motivo concreto que se muestra a continuación. El método mediante la API, a través de un complemento de DNS para Certbot, renueva el certificado sin intervención, y es la configuración que debe utilizar finalmente.

Este es el capítulo sobre certificados comodín de nuestras guías de Certbot. Los certificados normales para un solo nombre de host, la configuración del servidor web y las reglas del puerto 80 se explican en Certbot con nginx en Ubuntu 24.04 y Certbot con Apache en Ubuntu 24.04.

Cómo funciona el registro TXT de _acme-challenge

Cuando Certbot solicita *.example.com, Let's Encrypt responde con un token aleatorio. Certbot combina ese token con la clave de cuenta de ACME (automatic certificate management environment), aplica SHA-256 al resultado y genera un valor de texto corto. Ese valor debe aparecer como registro TXT en _acme-challenge.example.com. Luego, Let's Encrypt consulta los servidores de nombres autoritativos de su dominio desde su propia infraestructura. Si el registro que lee coincide con el valor esperado, ha demostrado que controla la zona. El control de la zona se acepta como control de todos los nombres que contiene.

Dos detalles causan la mayoría de los errores:

• Solicitar example.com y *.example.com en el mismo certificado significa que hay 2 desafíos independientes, y ambos registros TXT se encuentran en el mismo nombre, _acme-challenge.example.com. Ambos deben existir al mismo tiempo. Añadir el segundo registro es correcto; reemplazar el primero por el segundo hace que falle el primer desafío.
• La validación consulta sus servidores autoritativos, pero los paneles de control del proveedor pueden tardar 1 minuto o más en publicar un registro nuevo en esos servidores. Compruébelo desde el exterior antes de ejecutar la validación:

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

Cuando muestre el valor que solicitó Certbot, la validación podrá completarse correctamente. Si no muestra nada, espere y ejecútelo de nuevo.

Ver una vez cómo funciona: modo manual

El modo manual requiere que edites el DNS tú mismo. Es la mejor forma de entender el mecanismo antes de automatizarlo:

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

Las comillas alrededor del comodín impiden que el shell interprete * como un patrón de nombres de archivo. Certbot se detiene y muestra instrucciones:

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

Crea ese registro TXT en el panel de tu proveedor de DNS. Confirma que sea visible con el comando dig anterior y solo entonces pulsa Enter. Como esta ejecución solicita el dominio base y el comodín, Certbot muestra el aviso dos veces. Mantén ambos registros hasta que finalice la emisión. Si todo termina correctamente, aparecen las líneas habituales:

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

Por qué el modo manual no puede renovarse automáticamente

Cada renovación es un desafío nuevo con un token nuevo, por lo que el valor TXT cambia cada vez. El registro que pegaste hoy no sirve dentro de 60 días. El temporizador de renovación ejecuta Certbot de forma desatendida dos veces al día y no hay nadie frente al teclado para pegar el valor nuevo. Por eso, la renovación de un certificado emitido manualmente falla con este error exacto:

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

Puedes cumplir este requisito escribiendo scripts --manual-auth-hook que llamen a la API de tu proveedor de DNS, pero en ese punto estarías recreando manualmente un complemento de DNS. Usa el modo manual para aprender el proceso o para un caso realmente puntual en un dominio cuyo DNS todavía no puedas automatizar. Configura un recordatorio bastante antes del día 90, porque Let's Encrypt ya no envía correos electrónicos de expiración. Para todo lo demás, usa un complemento.

La ruta del plugin: certbot-dns-cloudflare en Ubuntu 24.04

Un plugin de DNS almacena una credencial de API de su proveedor de DNS y gestiona todo el proceso del registro TXT, tanto durante la emisión como en cada renovación. Cloudflare es el ejemplo utilizado aquí porque es el plugin de proveedor que más usuarios necesitan y está incluido en Ubuntu.

Nuestras guías de Certbot recomiendan los paquetes de apt en Ubuntu 24.04, y esta recomendación también se aplica a Cloudflare:

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

Una nota sobre las versiones. El archivo de Ubuntu 24.04 incluye este plugin en la versión 2.0.0 junto con Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare muestra la versión instalada. La diferencia no causa problemas y los tokens de API con permisos limitados funcionan porque la biblioteca python3-cloudflare subyacente en 24.04 es la versión 2.11.1, superior a la 2.3.1 que el plugin necesita para admitir tokens. En versiones anteriores de Ubuntu, esa biblioteca era demasiado antigua para admitir tokens. De ahí proceden las advertencias que puede encontrar en Internet sobre que el plugin de apt obliga a usar la Global API Key. En 24.04 ya no se aplican.

En el panel de Cloudflare, cree un token de API con permisos limitados, no la Global API Key: My Profile, después API Tokens y luego Create Token, con el único permiso Zone / DNS / Edit, limitado a la única zona para la que emitirá el certificado. Guárdelo en un archivo que solo root pueda leer:

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 comprueba los permisos y muestra una advertencia sobre Unsafe permissions on credentials configuration file si otros usuarios pueden leer el archivo. Ahora emita el certificado:

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

El plugin crea los registros TXT mediante la API, espera un breve periodo de propagación, permite que se ejecute la validación y después elimina los registros. Si los servidores de nombres de su zona tardan en aplicar los cambios, aumente la espera con --dns-cloudflare-propagation-seconds 60. El certificado se guarda en /etc/letsencrypt/live/example.com/. Configure nginx o Apache para usar fullchain.pem y privkey.pem exactamente como se muestra en las guías básicas, incluido el deploy hook.

Si el plugin de su proveedor no está en apt

El archivo de 24.04 solo incluye plugins para algunos proveedores, entre ellos Cloudflare, Route 53, DigitalOcean y la interfaz genérica RFC 2136. Ejecute apt search certbot-dns para ver la lista. Si su proveedor no aparece, este es el único caso en el que hacemos una excepción a la recomendación de usar apt primero: instale Certbot y el plugin desde snap y elimine primero el Certbot de apt para evitar que dos temporizadores de renovación compitan por /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 de snap solo se conecta al Certbot de snap. No puede ampliar el Certbot de apt. Por eso las dos instalaciones no deben coexistir. Si su proveedor de DNS no ofrece ninguna API, las opciones realistas son trasladar el DNS del dominio a un proveedor que sí tenga una o ejecutar su propio servidor de nombres y dirigir el plugin rfc2136 a él.

Renovación: pruébala ahora, no dentro de 60 días

Certbot registra cómo se emitió cada certificado en /etc/letsencrypt/renewal/example.com.conf, incluidos authenticator = dns-cloudflare y la ruta de las credenciales, por lo que el temporizador estándar, que se ejecuta dos veces al día, lo renueva sin intervención. Ensaya todo el proceso contra el entorno de pruebas:

sudo certbot renew --dry-run

Si la prueba se completa correctamente, las credenciales funcionan y la validación termina de principio a fin; la renovación real dentro de 60 días seguirá el mismo proceso. Hoy conviene hacer dos tareas adicionales. Primero, un certificado renovado en el disco no produce ningún cambio hasta que el servidor web lo vuelva a cargar, así que configura el deploy hook descrito en las guías de nginx y Apache. Segundo, protege el archivo de credenciales: cualquiera que pueda leerlo puede modificar tu zona DNS, lo que basta para redirigir tu correo o superar desafíos DNS-01 propios. Déjalo con el modo 600 en /root, limita el token a una sola zona y rótalo si alguna vez sospechas que se ha filtrado.

Cuándo no necesitas un comodín

Un certificado comodín es la herramienta adecuada para muchos subdominios o para subdominios que no puedes predecir. No es la opción predeterminada correcta para todo lo demás.

• Un subdominio o unos pocos subdominios conocidos: un certificado SAN (subject alternative name) normal es más sencillo. certbot --nginx -d example.com -d www.example.com -d app.example.com cubre hasta 100 nombres mediante HTTP-01 sin formato, y ninguna credencial de la API de DNS permanece en el servidor.
• Un comodín coincide exactamente con una etiqueta. *.example.com no cubre el dominio base example.com, por eso los comandos anteriores solicitan ambos; tampoco cubre a.b.example.com, que requiere *.b.example.com.
• Una sola clave privada protege todos los subdominios. Si el equipo que la contiene sufre una intrusión, todos los nombres que cubre el comodín quedan afectados al mismo tiempo.
• Si Traefik termina TLS (transport layer security) para tus contenedores, no necesitas Certbot: Traefik solicita los certificados comodín por sí mismo mediante DNS-01, usando el mismo tipo de token del proveedor.

El comodín resulta realmente útil para subdominios por cliente o por aplicación que se crean más rápido de lo que quieres volver a emitir certificados, y para hosts internos sin el puerto público 80, como los servicios accesibles solo mediante una VPN WireGuard. DNS-01 nunca se conecta al host cuyo certificado se valida, por lo que incluso un equipo completamente privado puede contener un certificado confiable públicamente.

FAQ

¿Puede Certbot emitir un certificado wildcard con HTTP-01?

No. HTTP-01 demuestra el control de un nombre de host porque el servidor de validación obtiene un archivo de token de ese nombre exacto. Un wildcard cubre todos los nombres del dominio, por lo que Let's Encrypt requiere el desafío DNS-01. Los autenticadores --nginx, --apache, --webroot y --standalone usan HTTP. La única opción es un registro TXT en _acme-challenge.example.com, creado manualmente o mediante un plugin de DNS.

¿Un certificado wildcard cubre el dominio raíz?

No. El wildcard coincide exactamente con una etiqueta. Por tanto, *.example.com cubre www.example.com, pero no example.com sin subdominio ni a.b.example.com. Solicita ambos nombres en un mismo certificado con -d example.com -d '*.example.com'. Esto crea dos desafíos. Ambos registros TXT usan el mismo nombre _acme-challenge.example.com, así que añade el segundo registro sin eliminar el primero.

¿Por qué mi certificado wildcard no se renueva automáticamente?

Porque se emitió con --manual. Cada renovación requiere un valor TXT completamente nuevo. El temporizador desatendido no puede introducirlo, por lo que la renovación se detiene con el error An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Vuelve a emitir el certificado con un plugin de DNS como certbot-dns-cloudflare, o proporciona scripts --manual-auth-hook y --manual-cleanup-hook que modifiquen el registro mediante la API de tu proveedor.

¿Cuánto tarda en aparecer el registro TXT _acme-challenge?

Depende de tu proveedor de DNS: desde unos segundos hasta varios minutos. La validación consulta los servidores autoritativos de tu zona. Comprueba el registro con dig +short TXT _acme-challenge.example.com @1.1.1.1 y espera hasta que aparezca el valor esperado antes de continuar con una ejecución manual. Con un plugin, aumenta el tiempo de espera integrado mediante la opción de propagación del plugin, por ejemplo --dns-cloudflare-propagation-seconds 60, si la validación indica que no se encontró el registro.

¿Un certificado wildcard es menos seguro que un certificado normal?

La criptografía es idéntica. Las diferencias son operativas: una sola clave privada cubre todos los subdominios, por lo que una vulneración afecta a un alcance mayor. Además, la credencial de la API de DNS que necesita la automatización es un secreto sensible almacenado en el servidor. Si solo ejecutas unos pocos subdominios conocidos, un certificado SAN evita ambos problemas. Por eso esta guía recomienda omitir el wildcard en ese caso.