Certbot wildcard con challenge DNS-01

Perché un certificato wildcard richiede DNS-01

Un certificato wildcard copre ogni sottodominio di primo livello di un dominio: *.example.com corrisponde a app.example.com, blog.example.com e qualsiasi altro nome con un singolo livello di etichetta. Let's Encrypt rilascia certificati wildcard solo tramite la challenge DNS-01. Pertanto, Certbot deve dimostrare il controllo del DNS del dominio pubblicando un record TXT in _acme-challenge.example.com. La challenge HTTP-01 non è idonea perché la pubblicazione di un file token dimostra il controllo di un singolo hostname, ovvero quello da cui il server di validazione recupera il file. Un wildcard è un'affermazione valida per ogni possibile nome sotto il dominio; l'unico record pubblico che riguarda l'intero namespace è il DNS stesso.

Questo requisito determina tutte le altre procedure descritte in questa pagina. Per superare la challenge DNS-01 è necessario poter creare record TXT nella zona del dominio, manualmente o tramite l'API (application programming interface) del provider DNS. Il metodo manuale funziona una volta sola e fallisce durante il rinnovo per la causa specifica indicata di seguito. Il metodo tramite API, utilizzando un plugin DNS di Certbot, permette il rinnovo automatico; questo è il setup consigliato.

Questo è il capitolo dedicato ai wildcard delle nostre guide Certbot. I certificati standard per singolo hostname, la configurazione del web server e le regole sulla porta 80 sono trattati in Certbot con nginx su Ubuntu 24.04 e Certbot con Apache su Ubuntu 24.04.

Come funziona il record TXT _acme-challenge

Quando Certbot richiede *.example.com, Let's Encrypt risponde con un token casuale. Certbot combina il token con la chiave dell'account ACME (automatic certificate management environment), applica l'hash SHA-256 al risultato e genera un breve valore testuale. Tale valore deve essere presente come record TXT in _acme-challenge.example.com. Let's Encrypt interroga quindi i name server autorevoli del dominio dalla propria infrastruttura. Se il record letto corrisponde al valore atteso, la prova del controllo della zona è confermata; il controllo della zona implica il controllo di tutti i nomi contenuti in essa.

Due dettagli causano la maggior parte dei fallimenti:

• Richiedere example.com e *.example.com sullo stesso certificato implica due challenge separate; entrambi i record TXT si trovano sullo stesso nome, _acme-challenge.example.com. Entrambi devono esistere contemporaneamente. Aggiungere il secondo record è la procedura corretta; sostituire il primo con il secondo causa il fallimento della prima challenge.
• La validazione interroga i server autorevoli, ma i pannelli di controllo dei provider possono impiegare un minuto o più per propagare un nuovo record. Verifica la presenza del record dall'esterno prima di avviare la validazione:

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

Quando il comando restituisce il valore richiesto da Certbot, la validazione può avere successo. Se non restituisce alcun valore, attendi e riprova.

Provalo una volta: modalità manuale

La modalità manuale richiede l'inserimento manuale dell'edit DNS. Questo è il metodo migliore per comprendere il meccanismo prima di automatizzarlo:

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

Le virgolette attorno al wildcard impediscono alla shell di interpretare * come un pattern di file. Certbot si mette in pausa mostrando le istruzioni:

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

Crea il record TXT nel pannello del tuo provider DNS, verifica la visibilità con il comando dig indicato sopra e solo allora premi Enter. Poiché questa esecuzione richiede sia il dominio base che il wildcard, Certbot invierà due prompt; mantieni entrambi i record attivi fino al completamento dell'emissione. Il successo è confermato dalle solite righe:

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

Perché la modalità manuale non può rinnovarsi autonomamente

Ogni rinnovo richiede un nuovo token, quindi il valore TXT cambia ogni volta. Il record inserito oggi non sarà valido dopo 60 giorni. Il timer di rinnovo di Certbot si avvia automaticamente due volte al giorno; se l'utente non è presente per inserire il nuovo valore, il certificato emesso manualmente fallisce il rinnovo con questo errore:

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

È possibile soddisfare questo requisito scrivendo script --manual-auth-hook che interrogano l'API del provider DNS, ma in quel caso si sta ricostruendo manualmente un plugin DNS. Utilizza la modalità manuale per apprendere il flusso o per operazioni singole su domini il cui DNS non è ancora automatizzabile. Imposta un promemoria prima del giorno 90, poiché Let's Encrypt non invia più email di scadenza. Per ogni altro caso, utilizza un plugin.

La soluzione tramite plugin: certbot-dns-cloudflare su Ubuntu 24.04

Un plugin DNS utilizza le credenziali API del provider DNS e gestisce autonomamente la creazione dei record TXT durante l'emissione e ogni rinnovo. Cloudflare è l'esempio utilizzato poiché è il plugin più richiesto ed è incluso nei pacchetti di Ubuntu.

Le nostre guide su Certbot consigliano l'uso dei pacchetti apt su Ubuntu 24.04; questa indicazione è valida anche per Cloudflare:

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

Nota sulle versioni. L'archivio 24.04 include questo plugin alla versione 2.0.0 insieme a Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare indica la vostra versione. La discrepanza non è critica e i token API limitati funzionano, poiché la libreria python3-cloudflare sottostante in 24.04 è la 2.11.1, superiore alla 2.3.1 richiesta dal plugin per il supporto ai token. Nelle versioni precedenti di Ubuntu quella libreria era troppo obsoleta per i token; questo è il motivo dei messaggi online che suggeriscono l'uso della Global API Key con il plugin apt. Su 24.04 tali avvertenze non sono più applicabili.

Nella dashboard di Cloudflare create un token API limitato, non la Global API Key: My Profile, poi API Tokens, poi Create Token, con l'unica permessione Zone / DNS / Edit, limitata alla singola zona per cui si richiede il certificato. Salvate il token in un file leggibile solo dall'utente 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 i permessi e segnala Unsafe permissions on credentials configuration file se il file è leggibile da altri utenti. Procedete con l'emissione:

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

Il plugin crea i record TXT tramite API, attende un breve tempo di propagazione, esegue la validazione e infine elimina i record. Se i name server della zona impiegano molto tempo a rilevare le modifiche, aumentate il tempo di attesa con --dns-cloudflare-propagation-seconds 60. Il certificato viene salvato in /etc/letsencrypt/live/example.com/; configurate nginx o Apache puntando a fullchain.pem e privkey.pem seguendo esattamente le guide base, incluso l'hook di deploy.

Se il plugin del provider non è presente in apt

L'archivio 24.04 include i plugin solo per alcuni provider, tra cui Cloudflare, Route 53, DigitalOcean e l'interfaccia generica RFC 2136. Esegui apt search certbot-dns per visualizzare l'elenco. Se il provider non è presente, la nostra raccomandazione di usare prioritariamente apt cambia: installa Certbot e il plugin tramite snap, quindi rimuovi la versione apt di Certbot per evitare conflitti tra i due timer di rinnovo su /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 si collega esclusivamente alla versione snap di Certbot; non può estendere la versione apt. Per questo motivo le due installazioni non devono coesistere. Se il provider DNS non offre alcuna API, le opzioni realistiche sono spostare il DNS del dominio verso un provider che ne possieda una, oppure gestire un proprio name server e puntare il plugin rfc2136 ad esso.

Rinnovo: verifica subito, non tra 60 giorni

Certbot registra come ogni certificato è stato emesso in /etc/letsencrypt/renewal/example.com.conf, inclusi authenticator = dns-cloudflare e il percorso delle credenziali. Il timer standard, che si avvia due volte al giorno, effettua il rinnovo automaticamente. Esegui una prova completa utilizzando l'ambiente di staging:

sudo certbot renew --dry-run

Se il test ha successo, le credenziali sono corrette e la validazione è completata; il rinnovo reale tra 60 giorni seguirà lo stesso procedimento. È necessario eseguire due passaggi aggiuntivi oggi. Primo, un certificato rinnovato su disco non ha effetto finché il web server non lo ricarica; configura quindi il deploy hook descritto nelle guide per nginx e Apache. Secondo, proteggi il file delle credenziali: chiunque possa leggerlo può modificare la tua zona DNS, il che è sufficiente per reindirizzare la posta elettronica o superare le challenge DNS-01. Mantieni il file con permessi mode 600 sotto /root, limita il token a una singola zona e sostituiscilo se sospetti una compromissione.

Quando non è necessario un wildcard

Un wildcard è lo strumento ideale per gestire molti sottodomini o sottodomini non prevedibili. Non deve essere la scelta predefinita per tutto il resto.

• Un singolo sottodominio, o pochi sottodomini noti: un normale certificato SAN (subject alternative name) è più semplice. certbot --nginx -d example.com -d www.example.com -d app.example.com copre fino a 100 nomi tramite HTTP-01, e non è necessario memorizzare credenziali DNS API sul server.
• Un wildcard corrisponde esattamente a un singolo label. *.example.com non copre il bare example.com, motivo per cui i comandi sopra richiedono entrambi, e non copre nemmeno a.b.example.com; per quello è necessario *.b.example.com.
• Ogni sottodominio utilizza una chiave privata dedicata. Se la macchina che la ospita viene compromessa, tutti i nomi coperti dal wildcard risultano compromessi contemporaneamente.
• Se Traefik gestisce il TLS (transport layer security) per i container, non è necessario utilizzare Certbot: Traefik richiede autonomamente i certificati wildcard tramite DNS-01, utilizzando lo stesso tipo di token del provider.

Il wildcard è utile nei seguenti casi: sottodomini per singolo cliente o per singola app creati più velocemente di quanto si possa riemettere un certificato, e host interni senza porta 80 pubblica, come i servizi raggiungibili solo tramite una VPN WireGuard. Il protocollo DNS-01 non si connette mai all'host oggetto della certificazione, quindi anche una macchina completamente privata può ospitare un certificato di fiducia pubblica.

FAQ

Certbot può emettere un certificato wildcard con HTTP-01?

No. HTTP-01 prova il controllo di un singolo hostname, poiché il server di validazione recupera un file di token da quel nome specifico. Un wildcard copre ogni nome sotto il dominio, quindi Let's Encrypt richiede la challenge DNS-01, mentre gli authenticator --nginx, --apache, --webroot e --standalone sono tutti basati su HTTP. L'unica opzione è un record TXT su _acme-challenge.example.com, inserito manualmente o tramite un plugin DNS.

Un certificato wildcard copre il dominio root?

No. Il wildcard corrisponde esattamente a un singolo label, quindi *.example.com copre www.example.com ma non il dominio bare example.com, né a.b.example.com. Richiedi entrambi i nomi su un unico certificato usando -d example.com -d '*.example.com'. Questo crea due challenge; poiché entrambi i record TXT si trovano sullo stesso nome _acme-challenge.example.com, aggiungi il secondo record senza eliminare il primo.

Perché il mio certificato wildcard non si rinnova automaticamente?

Perché è stato emesso con --manual. Ogni rinnovo richiede un nuovo valore TXT e il timer automatico non può inserirlo, quindi il rinnovo si interrompe con l'errore An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Riemetti il certificato utilizzando un plugin DNS come certbot-dns-cloudflare, oppure fornisci script --manual-auth-hook e --manual-cleanup-hook per modificare il record tramite l'API del provider.

Quanto tempo impiega a comparire il record TXT _acme-challenge?

Dipende dal provider DNS: da pochi secondi a diversi minuti. La validazione legge i server autorevoli della zona; verifica con dig +short TXT _acme-challenge.example.com @1.1.1.1 e attendi che appaia il valore previsto prima di continuare l'esecuzione manuale. Con un plugin, aumenta il tempo di attesa predefinito tramite l'opzione di propagazione del plugin, ad esempio --dns-cloudflare-propagation-seconds 60, se la validazione segnala che il record non è stato trovato.

Un certificato wildcard è meno sicuro di un certificato normale?

La crittografia è identica. Le differenze sono operative: una chiave privata copre tutti i sottodomini, quindi un compromesso ha un raggio d'azione maggiore, e le credenziali API DNS richieste dall'automazione sono esse stesse segreti sensibili memorizzati sul server. Se gestisci solo pochi sottodomini noti, un certificato SAN evita entrambi i problemi; è proprio in questo caso che questa guida consiglia di non usare il wildcard.