Certbot wildcard con desafio DNS-01

Por qué un certificado wildcard requiere DNS-01

Un certificado wildcard 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 un solo nivel de etiqueta. Let's Encrypt emite certificados wildcard ú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 es apto, porque servir un archivo de token solo demuestra el control de un hostname específico, el mismo desde el cual el servidor de validación obtuvo el archivo. Un wildcard es una declaración sobre todos los nombres posibles bajo el dominio, y el único registro público que representa a todo el namespace es el propio DNS.

Ese único requisito determina todo lo demás en esta página. Para completar el desafío DNS-01, debe ser capaz de crear registros TXT en la zona del dominio, ya sea manualmente o mediante la API (interfaz de programación de aplicaciones) de su proveedor de DNS. El método manual funciona una vez, pero falla durante la renovación por la razón específica que se muestra abajo. El método mediante API, usando un plugin de DNS de Certbot, permite la renovación automática; este es el método recomendado.

Este es el capítulo de wildcard de nuestras guías de Certbot. Los certificados estándar para un único hostname, la configuración del servidor web y las reglas del puerto 80 se tratan en Certbot con nginx en Ubuntu 24.04 y Certbot con Apache en Ubuntu 24.04.

Cómo funciona el registro TXT _acme-challenge

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

Dos detalles causan la mayoría de los fallos:

• Solicitar example.com y *.example.com en el mismo certificado implica dos desafíos distintos, y ambos registros TXT residen en el mismo nombre, _acme-challenge.example.com. Ambos deben existir simultáneamente. Agregar el segundo registro es lo correcto; reemplazar el primero con el segundo hará que el primer desafío falle.
• La validación consulta sus servidores autoritativos, pero los paneles de control de los proveedores pueden tardar un minuto o más en propagar un nuevo registro hacia ellos. Verifique desde el exterior antes de ejecutar la validación:

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

Cuando el comando devuelva el valor solicitado por Certbot, la validación puede ser exitosa. Si no devuelve nada, espere y ejecute el comando nuevamente.

Ver el funcionamiento una vez: modo manual

El modo manual requiere que realice la edición de DNS manualmente. Esta 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 wildcard evitan que el shell interprete * como un patrón de nombre de archivo. Certbot se detiene y muestra las instrucciones:

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

Cree el registro TXT en el panel de su proveedor de DNS, confirme que sea visible con el comando dig anterior y, solo entonces, presione Enter. Debido a que esta ejecución solicita el dominio raíz y el wildcard, CertCertbot solicitará los datos dos veces; mantenga ambos registros activos hasta que finalice la emisión. El éxito se indica con 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 requiere un nuevo token, por lo que el valor TXT cambia en cada ocasión. El registro que pegó hoy dejará de ser útil en 60 días. El temporizador de renovación ejecuta Certbot sin intervención dos veces al día, y no hay nadie para pegar el nuevo valor. Por ello, un certificado emitido manualmente fallará al renovarse con este error:

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

Puede cumplir con ese requisito mediante scripts de --manual-auth-hook que utilicen la API de su proveedor de DNS, pero en ese caso estará reconstruyendo un plugin de DNS manualmente. Use el modo manual para aprender el flujo de trabajo o para casos únicos en dominios cuyo DNS aún no pueda automatizar. Configure un recordatorio mucho antes del día 90, ya que Let's Encrypt ya no envía correos de expiración. Para cualquier otro caso, use un plugin.

La opción del plugin: certbot-dns-cloudflare en Ubuntu 24.04

Un plugin de DNS utiliza una credencial de API de su proveedor de DNS y gestiona automáticamente la creación de registros TXT durante la emisión y cada renovación. Cloudflare se utiliza como ejemplo porque es el plugin más solicitado y está incluido en los repositorios de Ubuntu.

Nuestras guías de Certbot recomiendan usar paquetes apt en Ubuntu 24.04, lo cual aplica también para Cloudflare:

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

Nota sobre las versiones. El repositorio de la versión 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 su versión actual. Esta diferencia no causa problemas y los tokens de API limitados funcionan, ya que la librería python3-cloudflare de Ubuntu 24.04 es la 2.11.1, superior a la 2.3.1 que requiere el plugin para soportar tokens. En versiones antiguas de Ubuntu, esa librería era demasiado vieja para tokens; de ahí provienen las advertencias en internet sobre el plugin de apt que obliga a usar la Global API Key. En la 24.04, esas advertencias ya no aplican.

En el panel de Cloudflare cree un token de API limitado, no use la Global API Key: My Profile, luego API Tokens, luego Create Token, con el único permiso Zone / DNS / Edit, limitado a la zona específica para la que emitirá el certificado. Guarde el token en un archivo con permisos de lectura solo para 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 verifica el modo de permisos y lanza una advertencia sobre Unsafe permissions on credentials configuration file si el archivo es legible por otros usuarios. Ejecute la emisión:

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 tiempo de propagación, ejecuta la validación y luego elimina los registros. Si los servidores de nombres de su zona tardan en detectar los cambios, aumente el tiempo de espera con --dns-cloudflare-propagation-seconds 60. El certificado se guarda en /etc/letsencrypt/live/example.com/; configure nginx o Apache apuntando a fullchain.pem y privkey.pem siguiendo exactamente las guías base, incluyendo el deploy hook.

Si el plugin de su proveedor no está en apt

El repositorio de la versión 24.04 solo incluye plugins para unos pocos proveedores, como 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, nuestra recomendación de priorizar apt cambia: instale Certbot y el plugin mediante snap, y elimine primero el Certbot de apt para evitar conflictos entre los dos timers de renovación 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 extender la versión de apt, por lo que ambas instalaciones no deben coexistir. Si su host de DNS no ofrece una API, sus opciones reales son mover el DNS del dominio a un proveedor que sí la tenga, o ejecutar su propio servidor de nombres y apuntar el plugin rfc2136 hacia él.

Renovación: pruébela ahora, no en 60 días

Certbot registra cómo se emitió cada certificado en /etc/letsencrypt/renewal/example.com.conf, incluyendo authenticator = dns-cloudflare y la ruta de las credenciales, de modo que el timer estándar de dos veces al día lo renueva sin su intervención. Pruebe todo el proceso usando el entorno de staging:

sudo certbot renew --dry-run

Un resultado exitoso significa que las credenciales funcionan y la validación se completa de extremo a extremo; la renovación real en 60 días seguirá el mismo proceso. Es recomendable realizar dos acciones adicionales hoy mismo. Primero, un certificado renovado en disco no produce cambios hasta que el servidor web lo recargue; configure el deploy hook descrito en las guías de nginx y Apache. Segundo, proteja el archivo de credenciales: cualquier usuario con permisos de lectura puede editar su zona DNS, lo cual es suficiente para redirigir su correo o superar sus propios desafíos DNS-01. Mantenga el archivo con modo 600 bajo /root, limite el token a una sola zona y rotelo si sospecha de una filtración.

Cuando no es necesario usar un wildcard

Un wildcard es la herramienta adecuada para múltiples subdominios o para subdominios impredecibles. No debe usarse por defecto para todo lo demás.

• Un solo subdominio, o un grupo pequeño de 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, y no requiere guardar credenciales de la API de DNS en el servidor.
• Un wildcard coincide con exactamente una etiqueta. *.example.com no cubre el dominio raíz example.com, por lo que los comandos anteriores solicitan ambos; tampoco cubre a.b.example.com, lo cual requeriría *.b.example.com.
• Cada subdominio utiliza una clave privada distinta. Si el equipo que la contiene se ve comprometido, todos los nombres cubiertos por el wildcard se ven afectados simultáneamente.
• Si Traefik gestiona el TLS (transport layer security) de sus contenedores, no necesita usar Certbot: Traefik solicita certificados wildcard mediante DNS-01, utilizando el mismo tipo de token de proveedor.

Casos donde el wildcard es realmente útil: subdominios por cliente o por aplicación que se crean más rápido de lo que permite la reemisión de certificados, y hosts internos sin puerto 80 público, como servicios accesibles únicamente a través de una VPN WireGuard. DNS-01 nunca se conecta al host que se está certificando, por lo que incluso una máquina totalmente privada puede tener un certificado de confianza pública.

FAQ

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

No. HTTP-01 demuestra el control de un hostname, ya que el servidor de validación descarga un archivo de token desde ese nombre exacto. Un wildcard cubre todos los nombres bajo el dominio, por lo que Let's Encrypt requiere el desafío DNS-01 para ello; los autenticadores --nginx, --apache, --webroot y --standalone son todos basados en HTTP. La única vía es un registro TXT en _acme-challenge.example.com, colocado manualmente o mediante un plugin de DNS.

¿Cubre un certificado wildcard al dominio raíz?

No. El wildcard coincide con exactamente una etiqueta, por lo que *.example.com cubre www.example.com pero no el dominio bare example.com, ni a.b.example.com. Solicite ambos nombres en un mismo certificado usando -d example.com -d '*.example.com'. Esto crea dos desafíos, y ambos registros TXT se encuentran en el mismo nombre _acme-challenge.example.com, por lo que debe añadir el segundo registro sin borrar el primero.

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

Porque se emitió con --manual. Cada renovación requiere un valor TXT nuevo, y el temporizador automático no puede insertarlo, por lo que la renovación falla con el error An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Reemita el certificado con un plugin de DNS como certbot-dns-cloudflare, o proporcione scripts --manual-auth-hook y --manual-cleanup-hook que editen el registro mediante la API de su proveedor.

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

Depende de su proveedor de DNS: desde pocos segundos hasta varios minutos. La validación lee los servidores autoritativos de su zona, así que verifique con dig +short TXT _acme-challenge.example.com @1.1.1.1 y espere a que aparezca el valor esperado antes de continuar con una ejecución manual. Con un plugin, aumente 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.

¿Es un certificado wildcard menos seguro que un certificado normal?

La criptografía es idéntica. Las diferencias son operativas: una única clave privada cubre todos los subdominios, por lo que un compromiso afecta a un área mayor, y las credenciales de la API de DNS que requiere la automatización son en sí mismas secretos sensibles almacenados en el servidor. Si solo utiliza unos pocos subdominios conocidos, un certificado SAN evita ambos problemas; esta es precisamente la razón por la que esta guía recomienda no usar wildcard.