Truedoc

h1. Usare Let's Encrypt

{{>toc}}

h2. Panoramica

L'uso dei certificati SSL, necessario per l'accesso in HTTPs ai siti web, è ormai divenuto uno dei passi fondamentali nella gestione della sicurezza della rete, in quanto consente sia di cifrare le comunicazioni, evitando una possibile intercettazione dei dati, che di identificare l'autenticità del corrispondente, garantendone opportunamente l'identità. A lungo però il loro impiego era strettamente legato all'acquisto degli stessi presso una Certification Authority, a titolo talvolta anche molto oneroso, ed alla necessità di reinstallazione periodica degli stessi. 

Il progetto di "Let's Encrypt":https://letsencrypt.org/ che ha portato alla una nuova Certification Authority libera e gratuita promossa da "EFF":https://www.eff.org, "Mozilla":https://www.mozilla.org, Google, Meta e molti altri nacque per poter mettere a disposizione a costo zero e rendere più semplice e fruibile una tecnologia che è fondamentale per la sicurezza di Internet. In particolare il progetto, oltre a fornire la possibilità a chiunque di ottenere gratuitamente un certificato valido, definisce un protocollo di riconoscimento (ACME, Automatic Certificate Management Environment) per il rilascio dei certificati, e consente di gestire il rinnovo in maniera automatica, potendo così usare con un ciclo di vita molto più breve (e quindi anche più sicuro) degli stessi.

In sostanza il procedimento prevede diverse una modailità con cui dimostrare di essere titolari del nome a dominio per cui si richiede il rilascio di un certificato, riassumbili in sostanza nel redere disponibile ad una opportuna interrogazione sul dominio stesso un segreto, fornito da "Let's Encrypt":https://letsencrypt.org/ durante la richiesta. Di queste vedremo come usare la più comune, che passa attraverso la pubblicazione (eseguita dal programma di gestione dei certificati) del suddetto segreto via web ad uno specifico indirizzo all'interno del dominio di cui si chede la validazione.

h2. Installazione di certbot

Dato che il procedimento di rilascio dei certificati avviene attraverso uno protocollo standardizzato (nell'"RFC 8555":https://datatracker.ietf.org/doc/html/rfc8555), esistono diversi programmi che consentono di gestire certificati "Let's Encrypt":https://letsencrypt.org/ ed ad oggi anche diverse Certification Authority che possono fornire il servizio, ci limiteremo comunque a trattare l'uso del programma @certbot@ fornito dal progetto originale, che è ormai disponibile come pacchetto per la gran parte delle distribuzioni Linux e che su Debian e derivate può essere installato immediatamente con:

<pre>

apt-get install certbot

</pre>

questo renderà disponibile il comando @certbot@ che è quello che ci consentirà di gestire le richieste, gli aggiornamenti ed i rinnovi dei certificati forniti da  "Let's Encrypt":https://letsencrypt.org/.

h2. Gestione dei certificati

h3. La richiesta iniziale

Benché in alcuni casi @certbot@ consenta anche di gestire, oltre le richieste ed i rinnovi dei certificati, anche le configurazione automatica del server web per poterli usare, in generale questo non è possibile (vengono fatte alcune assunzioni relative alla configurazione, che non tutte le distribuzioni supportano, e che comunque sono abbastanza restrittive). Per questo normalmente si deve ricorrere all'uso del sottocomando @certonly@, come indicato anche dal programma stesso se questi rileva che l'automatismo è impossibile:

<pre>

root@bookworm:~# certbot

Saving debug log to /var/log/letsencrypt/letsencrypt.log

Certbot doesn't know how to automatically configure the web server on this system. However, it can still get a certificate for you. Please run "certbot certonly" to do so. You'll need to manually configure your web server to use the resulting certificate.

</pre>

L'uso del sottocomando @certonly@ consente soltanto di ottenere un primo rilascio dei certificati, la configurazione dei servizi dovrà essere eseguita manualmente. Come accennato per emettere un certificato Let's Encrypt deve effettuare la validazione del dominio per cui questo viene richiesto, cosa che viene effettuata con una richiesta via web al dominio stesso, e l'uso di un meccanismo di _challenge and response_ basato sulla possibilità di scaricare un file dal quel dominio.

Questa procedura può essere realizzata direttamente dal programma se si usa dopo il comando @certonly@ l'opzione @--standalone@, che si incarica di far partire un servizio web sulla porta 80 o 443, ma in tal caso occorre fermare Apache o qualunque altro webserver che sia già attivo sul dominio. 

Si può evitare tutto questo utilizzando invece l'opzione @--webroot@ (o @-w@) se è disponibile l'accesso via web (viene richiesto l'accesso standard in HTTP, non HTTPs) alla _document root_ del sito per cui si vuole ottenere il certificato, in tal caso infatti il programma crea i file necessari alla validazione sotto la directory @.well-known/acme-challenge/@, che però deve poter essere servita a chi la richiede da fuori; occorre pertanto verificare che la configurazione del server web mantenga accessibile questa directory, ed è in genere necessaria una configurazione ad hoc.

In questo caso deve essere indicata nella richiesta come argomento dell'opzione @-w@ la directory della _document root_, mentre il dominio o i domini, che se sono più di uno,  saranno aggiunti allo stesso certificato come nomi alternativi, devono essere richiesti con l'opzione @-d@. 

Se si hanno diversi siti con diverse _document root_ in teoria si può eseguire l'operazione in un solo passo usando prima l'opzione @-w@ per indicare la prima _document root_ e poi l'opzione @-d@ per indicare relativo dominio, e così via per i successivi. Il comando infatti assume per ciascun dominio indicato con @-d@ si stia usando la directory indicata con l'ultima occorrenza precedente di @-w@. In questo caso tutte le _document root_ dovranno essere egualmente accessibili. Alternativamente si potrà ripetere l'operazione separatamente per ciascun dominio. Si tenga presente che in questo caso saranno generati altrettanti certificati separati.

Siccome tutto questo risulta scomodo e non è sempre applicabile, è possibile usare una unica directory per tutti i domini, anche se questa non corrisponde alla loro _document root_, consentendo l'accesso via web alla stessa in maniera generica (vedremo come farlo con le configurazioni descritte in seguito). Questa è anche la modalità consigliata dal progetto, assumeremo pertanto che si stia usando una configurazione adeguata e che la directory utilizzata per ospitare i file della _challenge and response_ di @.well-known/acme-challenge@ sia @/var/www/letsencrypt/@.

Se pertanto si vuole ottenere il certificato per il dominio @mail.truelite.it@ il comando da usare sarà:

<pre>

root@bookworm:~# certbot certonly --webroot -w /var/www/letsencrypt/ -d mail.truelite.it

Saving debug log to /var/log/letsencrypt/letsencrypt.log

Enter email address (used for urgent renewal and security notices)

 (Enter 'c' to cancel): info@truelite.it

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Please read the Terms of Service at

https://letsencrypt.org/documents/LE-SA-v1.4-April-3-2024.pdf. You must agree in

order to register with the ACME server. Do you agree?

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

(Y)es/(N)o: Y

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Would you be willing, once your first certificate is successfully issued, to

share your email address with the Electronic Frontier Foundation, a founding

partner of the Let's Encrypt project and the non-profit organization that

develops Certbot? We'd like to send you email about our work encrypting the web,

EFF news, campaigns, and ways to support digital freedom.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

(Y)es/(N)o: N

Account registered.

...

</pre>

La prima volta che lo si esegue per un nuovo dominio verrà richiesta una email di contatto (per comunicazione e recupero delle chiavi) e la prima volta che lo si esegue su una macchina si dovranno anche accettare le condizioni di Let's Encrypt. Questo comando creerà un certificato per il solo dominio @mail.truelite.it@; se un certificato deve essere valido per più domini, si possono salvare in un file, nell'esempio @valid_hosts.txt@ (un dominio per riga) ed usare il comando:

<pre>

# certbot certonly --webroot -w /var/www/letsencrypt/ -d $(xargs < domainlist.txt | sed 's/ /,/g')

</pre>

oppure lo si può invocare nella forma:

<pre>

# certbot certonly --webroot -w /var/www/letsencrypt/ -d mail.truelite.it -d smtp.truelite.it ...

</pre>

I certificati rilasciati durano tre mesi, e vengono installati sotto @/etc/letsencrypt/live@ in una directory corrispondente al nome a dominio indicato per primo (se sono più di uno); nel caso saranno sotto @/etc/letsencrypt/live/mail.truelite.it/@.

h3. Aggiunta di nuovi certificati distinti

Se si utilizza SNI (oggi utilizzabile con tutti i browser, ma non utilizzabile con servizi diversi dal web), e si vogliono avere certificati distinti per domini distinti, basterà ripetere il comando per ciascuno di essi. Ogni invocazione successiva con nomi a dominio diversi si limiterà a creare i certificati richiesti in maniera distinta, pertanto con qualcosa del tipo:

<pre>

# certbot certonly --webroot -w /var/www/letsencrypt/ -d www.truelite.it 

Checking for new version...

Requesting root privileges to run letsencrypt...

   /root/.local/share/letsencrypt/bin/letsencrypt certonly --webroot -w /var/www/letsencrypt/ -d www.truelite.it

IMPORTANT NOTES:

 - Congratulations! Your certificate and chain have been saved at

   /etc/letsencrypt/live/www.truelite.it/fullchain.pem. Your cert will

   expire on 2016-07-07. To obtain a new version of the certificate in

   the future, simply run Let's Encrypt again.

 - If you like Let's Encrypt, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate

   Donating to EFF:                    https://eff.org/donate-le

</pre>

Si otterrà un altro certificato, posto stavolta sotto @/etc/letsencrypt/live/www.truelite.it@. 

Con lo script @listlecert.sh@ allegato si può stampare un elenco dei certificati creati, e dei domini da essi coperti, ma le versioni correnti di @certbot@ supportano l'uso del comando @certbot certificates@ che stampa un elenco con tutti i dettagli comprese le data di scadenza ed i pathname dei file.

h2. Gestione dei certificati

h3. Aggiunta di un nuovo dominio ad un certificato esistente

Qualora si voglia aggiungere un nuovo dominio ad un certificato esistente basterà ripetere l'invocazione del comando aggiungendo il nuovo dominio con una ulteriore opzione @-d@, ad esempio:

<pre>

# certbot certonly --webroot -w /var/www/letsencrypt/ -d mail.truelite.it -d rainloop.truelite.it

Saving debug log to /var/log/letsencrypt/letsencrypt.log

-------------------------------------------------------------------------------

You have an existing certificate that contains a portion of the domains you

requested (ref: /etc/letsencrypt/renewal/mail.truelite.it.conf)

It contains these names: mail.truelite.it

You requested these names for the new certificate: mail.truelite.it,

rainloop.truelite.it.

Do you want to expand and replace this existing certificate with the new

certificate?

-------------------------------------------------------------------------------

(E)xpand/(C)ancel: E

Renewing an existing certificate

...

</pre>

In questo caso verrà chiesto se espandere il certificato presente, e scegliendo il default (E) questo verrà aggiunto. Si tenga presente che perché l'espansione funzioni occorre indicare nella richiesta tutti i domini già presenti nel certificato corrente, altrimenti verrà creata una versione alternativa (e distinta) con solo quelli elencati.

h3. Rimozione di certificati non più raggiungibili

Nel caso si siano richiesti certificati con più nomi di dominio e alcuni di questi non fossero più verificabili (in quanto non più raggiungibili, o spostati su altra macchina) si riceverà un errore in fase di rinnovo. È possibile ovviare al problema usando l'opzione @--allow-subset-of-names@ per rinnovare un certificato valido solo per il sottoinsieme di domini ancora verificabili (posto che il dominio principale per cui lo si è richiesto resti valido):

<pre>

# certbot renew --allow-subset-of-names

</pre>

tutti i domini non verificati verranno quindi rimossi dal certificato, e i rinnovi successivi andranno a buon fine anche senza tale opzione.

Ovviamente, si deve avere cura di non lanciare questo comando in caso di non raggiungibilità _temporanea_ di alcuni dei domini, ed è quindi opportuno non usare questa opzione in contesti automatizzati.

h3. Cancellazione di un certificato

Qualora si voglia eliminare un certificato, ad esempio perché il nome principale con cui lo si è creato non è più in uso, occorre usare il comando @cerbot delete@ e selezionare dalla lista se sono più di uno, o eventualmente indicare il nome con l'opzione @--cert-name@. Si tenga presente che questo cancellerà il certificato completamente, se questo era stato creato per più domini, anche questi verranno rimossi.

h3. Modifica delle informazioni di registrazione

Qualora si vogliano modificare le informazioni inserite in fase di registrazione, in particolare qualora si voglia cambiare l'email a cui il progetto invia gli avvisi in caso di mancato rinnovo e le eventuali comunicazioni sul servizio, il comando da usare è il seguente:

<pre>

# certbot register --update-registration --email nuovaemail@truelite.it 

Saving debug log to /var/log/letsencrypt/letsencrypt.log

-------------------------------------------------------------------------------

Would you be willing to share your email address with the Electronic Frontier

Foundation, a founding partner of the Let's Encrypt project and the non-profit

organization that develops Certbot? We'd like to send you email about EFF and

our work to encrypt the web, protect its users and defend digital rights.

-------------------------------------------------------------------------------

(Y)es/(N)o: y

IMPORTANT NOTES:

 - Your e-mail address was updated to nuovaemail@truelite.it.

</pre>

h2. Configurazioni per consentire la validazione

Come accennato per effettuare la validazione del dominio con la modalità @--webroot@ è necessario che siano raggiungibili i contenuti corrispondenti alla URL:

<pre>

http://mio.dominio.it/.well-known/acme-challenge/xxx

</pre>

cosa che può dipendere dalla configurazione del proprio webserver.

h3. Nginx

Nel caso di Nginx la modalità suggerita per consentire questa configurazione è creare un frammento di configurazione (nel caso @/etc/nginx/snippets/letsencrypt-acme-challenge.conf@) contenente le direttive necessarie per consentire l'accesso: 

<pre>

location ^~ /.well-known/acme-challenge/ {

    default_type "text/plain";

    root         /var/www/letsencrypt;

}

location = /.well-known/acme-challenge/ {

    return 404;

}

</pre>

queste istruzioni consentono di eseguire la validazione indicando come @webroot@ la directory @/var/www/letsencrypt@, posto che il frammento di cui sopra sia stato incluso come prima direttiva nelle configurazioni dei virtual host coinvolti (basta anche inserirlo solo nelle direttive in chiaro), ad esempio con qualcosa del tipo:

<pre>

server {

        listen 80;

        root /var/www/html;

        server_name bd.truelite.it;

        include /etc/nginx/snippets/letsencrypt-acme-challenge.conf;

        location / {

            rewrite ^/(.*)$ https://bd.truelite.it/$1 permanent;

        }       

}

</pre>

h3. Apache

Una analoga configurazione per Apache si può effettuare utilizzando il seguente frammento di configurazione:

<pre>

Alias /.well-known/acme-challenge/ /var/www/letsencrypt/.well-known/acme-challenge/

<Directory "/var/www/letsencrypt/.well-known/acme-challenge/">

    Options None

    AllowOverride None

    ForceType text/plain

    # avoid access to anything not resembling a challenge

    RedirectMatch 404 "^(?!/\.well-known/acme-challenge/[\w-]{43}$)"

</Directory>

</pre>

Con Debian da Jessie in poi lo si può inserire in  @/etc/apache2/conf-available/@ ed abilitare con @a2enconf@, con le versioni precedenti occorreva usare @/etc/apache2/conf.d@, per altre distribuzioni si utilizzi una posizione adeguata e lo si includa nella configurazione generale di Apache.

Si tenga presente però che qualora si usi Apache come reverse proxy occorrerà anche inserire una opportuna eccezione alle regole di proxy per la suddetta URL, in sostanza si dovrà aggiungere alla configurazione del virtual host una riga:

<pre>

ProxyPass /.well-known/acme-challenge !

</pre>

Infine, quando si forza la redirezione su SSL delle connessioni in chiaro, occorre evitare che questo avvenga anche per le richieste di Let's Encrypt, pertanto occorrerà sostituire una eventuale direttiva di redirezione generica come la seguente:

<pre>

<VirtualHost *:80>

    ServerName ci.truelite.it

    Redirect permanent / https://ci.truelite.it/

</VirtualHost>

</pre>

con una più specifica che escluda la redirezione per la URL utilizzata da Let's Encrypt:

<pre>

<VirtualHost *:80>

    ServerName ci.truelite.it

    RedirectMatch 301 ^/((?!.well-known\/acme-challenge).*)$ https://ci.truelite.it/$1

</VirtualHost>

</pre>

Se si vuole ottenere lo stesso risultato con il virtualhost di default di Apache, non è più possibile utilizzare @RedirectMatch@ in quanto in tal caso non è noto a priori l'hostname con cui si viene contattati, si può però inserire una regola generica in @/etc/apache2/sites-available/000-default.conf@ con:

<pre>

<VirtualHost *:80>

        [...]

        RewriteEngine On

        RewriteCond %{HTTPS} off [OR] 

        RewriteRule ^/((?!.well-known\/acme-challenge).*)$ https://%{HTTP_HOST}/$1 [NC,R=301,L]

        [...]

</VirtualHost>

</pre>

h2. Esempi di configurazione dei servizi

Una volta completata la validazione del proprio dominio, nella directory di installazione dei certificati (@/etc/letsencrypt/live/mio.dominio.it@) vengono sempre creati i file:

| *file*    | *contenuto* |

|cert.pem      | cerficato |

|chain.pem     | catena dalla CA |

|fullchain.pem | catena + certificato|

|privkey.pem   | chiave privata |

Dove @chain.pem@ è il certificato intermedio (o la catena di certificati intermedi) che validano @cert.pem@ che è il certificato del proprio dominio, mentre @fullchain.pem@ è l'insieme completo del certificato e della catena. Infine la chiave privata è in @privkey.pem@.

In qualunque configurazione occorre sempre fare riferimento a questi file, che sono link simbolici, in quanto @letsencrypt@ aggiornerà automaticamente gli stessi con la procedura di rinnovo automatico che vedremo più avanti.

h3. Apache

I file @cert.pem@ e @chain.pem@ sono quelli che si usano nella configurazione di Apache, che fino alla versione 2.2 li vuole separati, ad esempio con quelli ottenuti in precedenza la configurazione utilizzata è:

<pre>

SSLCertificateFile /etc/letsencrypt/live/mail.truelite.it/cert.pem

SSLCertificateChainFile /etc/letsencrypt/live/mail.truelite.it/chain.pem

SSLCertificateKeyFile /etc/letsencrypt/live/mail.truelite.it/privkey.pem

</pre>

se invece si usa la versione 2.4 non è più necessario usare @SSLCertificateChainFile@ che è deprecata, e si deve invece passare ad usare il file @fullchain.pem@ che è l'insieme del certificato e di tutta la sua catena di firma con una configurazione del tipo:

<pre>

SSLCertificateFile /etc/letsencrypt/live/mail.truelite.it/fullchain.pem

SSLCertificateKeyFile /etc/letsencrypt/live/mail.truelite.it/privkey.pem

</pre>

h3. Postfix

Il file @fullchain.pem@ è quello che viene richiesto anche da Postfix, Dovecot e Nginx. Per Postfix occorrerà farvi riferimento in @/etc/postfix/main.cf@ con le direttive:

<pre>

smtpd_tls_cert_file=/etc/letsencrypt/live/mail.truelite.it/fullchain.pem

smtpd_tls_key_file=/etc/letsencrypt/live/mail.truelite.it/privkey.pem

</pre>

h3. Dovecot

mentre per Dovecot di dovanno utilizzare in @/etc/dovecot/conf.d/90-user.conf@ le direttive:

<pre>

ssl_cert = </etc/letsencrypt/live/mail.truelite.it/fullchain.pem

ssl_key = </etc/letsencrypt/live/mail.truelite.it/privkey.pem

</pre>

h3. Nginx

ed infine per Nginx si dovrà inserire nella configurazione del proprio virtual host qualcosa del tipo:

<pre>

server {

   listen 443 ssl;

   server_name bd.truelite.it;

   root /var/www/html;

   ssl_certificate /etc/letsencrypt/live/bd.truelite.it/fullchain.pem;

   ssl_certificate_key /etc/letsencrypt/live/bd.truelite.it/privkey.pem;

   ...

</pre>

h3. ejabberd

Infine per configurare ejabberd (server jabber) occorre generare dai file di Let's Encrypt un unico file contenente in testa la chiave privata (il programma non consente di specificarli separatamente), se pertanto @/etc/ejabberd/ejabberd.pem@ è il file usato dal programma, occorrerà rigenerarlo ogni volta che si generano o rinnovano i certificati con:

<pre>

cat /etc/letsencrypt/live/jabber.truelite.it/privkey.pem \

    /etc/letsencrypt/live/jabber.truelite.it/fullchain.pem > ejabberd.pem

</pre>

In tutti i casi deve essere effettuato un riavvio completo dei servizi.

h2. Il rinnovo dei certificati

La scadenza dei certificati emessi da Let's Encrypt è di tre mesi, ma una volta ottenuti questi possono essere facilmente rinnovati utilizzando il sottocomando @renew@, in particolare se si esegue il comando dopo averli ottenuti si otterrà qualcosa del tipo:

<pre>

# certbot renew

Checking for new version...

Requesting root privileges to run letsencrypt...

   /root/.local/share/letsencrypt/bin/letsencrypt renew

-------------------------------------------------------------------------------

Processing /etc/letsencrypt/renewal/mail.truelite.it.conf

-------------------------------------------------------------------------------

The following certs are not due for renewal yet:

  /etc/letsencrypt/live/mail.truelite.it/fullchain.pem (skipped)

No renewals were attempted.

</pre>

la cosa si può automatizzare inserendo banalmente nel cron il comando, ad esempio creando il file @/etc/cron.d/letencrypt@ con il contenuto:

<pre>

00 23 * * 6  root certbot renew

</pre>

oppure usare lo script @le-renew@ allegato, che esegue anche il riavvio dei servizi quando rileva un aggiornamento dei certificati, avendo cura di adattarlo alle proprie esigenze; in tal caso il suggerimento è di inserirlo fra quelli di  @/etc/cron.weekly@.

Nelle versioni più recenti del pacchetto viene installato un cron job @/etc/cron.d/certbot@ (non usato se la distibuzione usa systemd) ed un timer ed un service di @systemd@ che eseguono due volte al giorno il comando @certbot -q renew@. In tal caso non è necessario usare lo script allegato, ma si tenga conto che questo comando, da solo, non esegue altra azione che il rinnovo.

E' comunque possibile inserire degli _hook_ da eseguire in caso di rinnovo. Questo si può fare esplicitamente nel comando, con @--renew-hook@ nelle vecchie versioni o con i vari @--pre-hook@, @--post-hook@ e @--deploy-hook@ (quest'ultimo equivalente di @--renew-hook@) nelle versioni più recenti. Per queste ultime si possono anche inserire gli script da eseguire sotto @/etc/letsencrypt/renewal-hooks@ nelle corrispondenti directory @deploy@, @pre@ e @post@. In tal caso gli script vengono eseguiti una volta per ogni certificato rinnovato, e si hanno le variabili @RENEWED_LINEAGE@ per indicare il certificato rinnovato e @RENEWED_DOMAINS@ per l'elenco dei domini (separto da spazi) in esso contenuti.