Vai al contenuto

ACME

Il protocollo ACME, Automated Certificate Management Environment, è uno standard IETF (RFC 8555) per la gestione automatizzata dei certificati X.509.

Il protocollo ACME è stato implementato per la prima volta da Let's Encrypt, la Certification Authority libera e gratuita gestita dal Internet Security Research Group (ISRG). E' bene ricordare che se da una parte Let's Encrypt fornisce un servizio formidabile, dall'altra supporta solo i certificati di tipo DV.

Il client di riferimento per l'uso di Let's Encrypt e del protocollo ACME è certbot.

Riferimenti

Installazione di certbot

Per l'installazione di certbot è caldamente consigliato seguire sempre le istruzioni ufficiali disponibili su https://certbot.eff.org. Qualora nel menù a tendina "system" non sia presente il S.O. in uso consigliamo di eseguire l'installazione via pip. Riportiamo qui le istruzioni per l'installazione di certbot via pip, per maggiori informazioni vi consigliamo di consultare le istruzioni ufficiali e più recenti su https://certbot.eff.org.

  • SSH into the server

Tutti i comandi che seguono devono essere eseguiti da root o con sudo. Accedere con ssh al server in cui gira il server HTTP oppure nel sistema in cui si vuole generare il certificato.

  • Install system dependencies

Le dipendenze di sistema includono generalmente Python 3.6+, il modulo venv e il plug-in Augeas per Apache.

In caso di problemi nell'installazione dei moduli di crittografia potrebbe essere necessario installare dipendenze addizionali. Per maggiori informazioni vedere cryptography project's site.

I comandi per installare le dipendenze sulla macchina sono i seguenti:

Per distribuzioni APT-based(e.g. Debian, Ubuntu ...):

sudo apt update sudo apt install python3 python3-venv libaugeas0

Per distribuzioni RPM-based (e.g. Fedora, CentOS ...):

sudo dnf install python3 augeas-libs

  • Remove certbot-auto and any Certbot OS packages

Se sono presenti pacchetti Certbot installati utilizzando un gestore di pacchetti del sistema operativo come apt, dnf o yum, è necessario rimuoverli prima di installare lo snap Certbot per garantire che quando si esegue il comando certbot venga utilizzato lo snap anziché l'installazione dal pacchetto del sistema operativo manager. Il comando esatto per eseguire questa operazione dipende dal sistema operativo, ma sono esempi comuni sudo apt-get remove certbot, sudo dnf remove certbot, o sudo yum remove certbot.

  • Set up a Python virtual environment

Eseguire le seguenti istruzioni sulla riga di comando sulla macchina per configurare un ambiente virtuale.

sudo python3 -m venv /opt/certbot/ sudo /opt/certbot/bin/pip install --upgrade pip

  • Install Certbot

Eseguire questo comando sulla riga di comando sulla macchina per installare Certbot.

sudo /opt/certbot/bin/pip install certbot certbot-apache

  • Prepare the Certbot command

Eseguire le seguenti istruzioni sulla riga di comando sulla macchina per garantire che il comando certbot possa essere eseguito.

sudo ln -s /opt/certbot/bin/certbot /usr/bin/certbot

  • Set up automatic renewal

Eseguire la riga seguente, che aggiungerà un processo cron al crontab predefinito.

echo "0 0,12 * * * root /opt/certbot/bin/python -c 'import random; import time; time.sleep(random.random() * 3600)' && sudo certbot renew -q" | sudo tee -a /etc/crontab > /dev/null

  • [Monthly] Upgrade certbot

È importante fare l'upgrade periodico di Certbot per mantenerlo aggiornato. Per fare ciò, eseguire il comando seguente sulla riga di comando della macchina.

sudo /opt/certbot/bin/pip install --upgrade certbot certbot-apache

Se questo passaggio genera errori, eseguire sudo rm -rf /opt/certbot e ripetere tutte le istruzioni di installazione dall'inizio.

(HARICA) Creazione account ACME in Cert Manager

HARICA offre due tipologie di account per utilizzare il protocollo ACME: una associata all’organizzazione e una personale.

ACME Enterprise

Attenzione

Per poter utilizzare account ACME Enterprise è necessario aver preliminarmente validato la propria organizzazione seguendo le istruzioni indicate in Validazione Enterprise.

Prima di poter utilizzare ACME con HARICA, è necessario creare uno o più account ACME legati all’organizzazione.

Accedere al Cert Manager con un account Enterprise Admin e dal menù Enterprise > Admin selezionare ACME. Cliccare sul pulsante Create +.

Durante la creazione, sarà richiesto di:

  • Specificare l’organizzazione per la quale si desidera creare l’account.
  • Scegliere il tipo di account ACME da creare:
  • SSL OV: per certificati con validazione dell’organizzazione (OV). Questi certificati avranno la denominazione dell'organizzazione nel Subject, ad esempio C=IT, L=Roma, O=GARR, CN=www.garr.it.

  • SSL DV: per certificati con sola validazione del dominio (DV). Questi certificati riporteranno il solo dominio nel Subject del certificato, ad esempio CN=www.garr.it.

  • Inserire un "Friendly Name", ovvero un nome descrittivo per identificare facilmente l’account.

  • Accettare i termini di utilizzo del servizio.

Una volta completati i campi e cliccato su Create, si verrà reindirizzati alla schermata con l’elenco degli account ACME disponibili per l’organizzazione.

L'account verrà creato immediatamente e in Details verranno visualizzati a video i dati del nuovo che dovranno essere copiati per la registrazione dell'account su Certbot:

  • Key ID
  • HMAC Key
  • Server URL

Nel menù Domains invece dovranno essere specificati i domini per cui l'account ACME è abilitato; è possibilire abilitare tutti i domini cliccando su Allow All Domains.

Attenzione

Selezionando l'opzione Allow All Domains, verranno inseriti TUTTI i domini associati all'organizzazione e qualora si volesse eliminare alcuni dei domini, o tutti, l'operazione dovrà essere fatta a mano per ciascun dominio.

ACME personale

Si consiglia di valutare molto attentamente l'abilitazione del profilo ACME personale, per i seguenti motivi:

  • Certificati solo DV (Domain Validation):
    I certificati rilasciati tramite ACME personale sono di tipo DV, quindi non riportano alcuna informazione sull’organizzazione.

  • Informazioni errate sui domini abilitati:
    Nell'account ACME personale, HARICA include automaticamente tutti i domini dell'organizzazione di cui l’utente fa parte, ma in realtà la validazione è sempre fatta dal client ACME sul dominio dell'host da cui si fa la richiesta (come let's encrypt).

  • E' possibile richiedere certificati per qualsiasi dominio: Tramite l'account ACME personale, si possono richiedere certificati per qualunque dominio che sia associato all'host da cui si fa la richiesta (validazione ACME HTTP-01 o DNS-01) indipendentemente dai domini caricati e validati su Cert Manager.

Attenzione

GARR raccomanda di utilizzare sempre il profilo ACME Enterprise che garantisce maggiore controllo sull'emissione dei certificati.

Per abilitare gli account ACME-Personal, procedere come segue:

  • selezionare Enterprise -> Admin e selezionare dal TAB Enterprises la Enterprise che si vuole abilitare.
  • nella finestra della Enterprise che viene aperta contestualmente, selezionare nel TAB Enterprises la voce del Legal Name (la propria organizzazione) per cui si vuole procedere.
  • Per abilitare ACME-Personal, premere l'icona in alto a destra che riporta il simbolo di un'etichetta (appare “Tags” al passaggio del mouse).
  • Si aprirà una finestra con un interruttore a levetta per "#ACME-Personal"
  • Selezionare la levetta affiché diventi di colore blu e salvare con Save.

Una volta abilitato il profilo ACME-Personal, per creare un account ACME gli utenti devono accedere alla sezione ACME selezionando la voce ACME in alto a sinistra sotto Dashboard.

Gli utenti possono creare fino ad un massimo di 3 account ACME personali, per ogni account sono elencati i certificati richiesti, che possono essere revocati direttamente da interfaccia.

(HARICA) Registrazione account ACME in certbot, emissione, rinnovo automatico e revoca dei certificati

Registrazione in certbot di un account creato in Cert Manager

Tutti i comandi che seguono devono essere eseguiti da root o con sudo.

Prima di cominciare a gestire i certificati è necessario registrare il nostro account ACME con il comando che segue:

certbot register --email <EMAIL> --server <SERVER URL> --eab-kid <KEY ID> --eab-hmac-key <HMAC KEY>

Sostituire <KEY ID>, <HMAC KEY> e <SERVER URL> con i corrispondenti valori che vi si siete segnati dopo la creazione dell'account ACME sul CM di Harica.

Il processo di registrazione comporta l'accettazione dei Terms of Service; vi verrà inoltre richiesto se volete condividere la mail con la Electronic Frontier Foundation.

Il risultato sarà la creazione dell'account e della relativa chiave nella directory /etc/letsencrypt/accounts.

Importante

Non è possibile registrare due account ACME di Harica sullo stesso client. E' possibile avere più account ACME registrati sullo stesso client a patto che siano di due Certification Autority differenti. Prima di registrare un nuovo account ACME della stessa CA occorre rimuovere il precedente.

Emissione dei certificati

Certbot permette di creare ed installare automaticamente i certificati dei virtual host presenti e correttamente configurati sul nostro server web, o semplicemente di creare i certificati senza installazione automatica.

Con il comando run si creano ed installano chiave e certificato per il virtualhost <FQDN-certificato> (sostituire <SERVER URL> con il corrispondente valore presente nell'account ACME sul CM di Harica):

certbot run --apache --email <EMAIL> --server <SERVER URL> --domain <FQDN-certificato> --key-type rsa --rsa-key-size 3072 --cert-name <FRIENDLY-NAME>

oppure per chiavi ECC

certbot run --apache --email <EMAIL> --server <SERVER URL> --domain <FQDN-certificato> --key-type ecdsa --elliptic-curve secp384r1 --cert-name <FRIENDLY-NAME>

Le modalità di installazione possono variare a seconda delle distribuzioni, ma in generale certbot, una volta creati chiave e certificato, tenterà di individuare la configurazione del virtualhost apache corrispondente e di modificarla per farla puntare al certificato ed alla chiave appena creati.

Per limitarsi alla sola creazione del certificato e della relativa in formato PEM, utilizzare invece il comando certonly con l'opzione --standalone (sostituire <SERVER URL> con il corrispondente valore presente nell'account ACME sul CM di Harica):

certbot certonly --standalone --email <EMAIL> --server <SERVER URL> --domain <FQDN-certificato> --key-type rsa --rsa-key-size 3072 --cert-name <FRIENDLY-NAME>

oppure per chiavi ECC

certbot certonly --standalone --email <EMAIL> --server <SERVER URL> --domain <FQDN-certificato> --key-type ecdsa --elliptic-curve secp384r1 --cert-name <FRIENDLY-NAME>

Per richiedere un certificato con SAN multipli, quindi per più nomi di dominio, ripetere l'opzione --domain DOMINIO o utilizzare una lista di nomi di dominio separata da virgola, ma senza spazi, come da esempio (sostituire <SERVER URL> con il corrispondente valore presente nell'account ACME sul CM di Harica):

certbot certonly --standalone --email <EMAIL> --server <SERVER URL> --domain <FQDN-certificato1>,<FQDN-certificato2>,<FQDN-certificato2> --key-type rsa --rsa-key-size 3072 --cert-name <FRIENDLY-NAME>

oppure per chiavi ECC

certbot certonly --standalone --email <EMAIL> --server <SERVER URL> --domain <FQDN-certificato1>,<FQDN-certificato2>,<FQDN-certificato2> --key-type ecdsa --elliptic-curve secp384r1 --cert-name <FRIENDLY-NAME>

Alcune opzioni utili in fase di creazione dei certificati:

  • --quiet silenzia il comando, utile per automation
  • --non-intereactive utile per automation, ma necessita di ulteriori opzioni
  • --key-type permette di scegliere il tipo di chiave {rsa,ecdsa}
  • --rsa-key-size BITS per specificare la grandezza della chiave RSA in bits, il default è 2048
  • --elliptic-curve N per specificare la lunghezza della chiave ECC in bits, il default è secp256r1

Tutti i certificati creati vengono salvati in /etc/letsencrypt/archive/<DOMAIN> e collegati in /etc/letsencrypt/live/<DOMAIN> se attivi. Inoltre le chiavi private sono salvate come privkey.pem.

Importante

assicurarsi di configurare il rinnovo automatico del certificato. Molti dei pacchetti di installazione di certbot includono già una configurazione di base per il rinnovo dei certificati via cron. In generale conviene sempre fare riferimento alle "Certbot instructions / Set up automatic renewal" presenti nel sito https://certbot.eff.org/instructions relative al software e al sistema prescelto.

Revoca dei certificati

Per revocare i certificati emessi utilizzare il comando revoke(sostituire <SERVER URL> con il corrispondente valore presente nell'account ACME sul CM di Harica):

certbot revoke --email <EMAIL> --server <SERVER URL> --cert-name <FQDN-certificato>

Nel caso di certificati per più nomi di dominio, basterà specificare uno dei nomi validi. Inoltre tramite l'opzione --cert-path è possibile utilizzare il percorso del certificato al posto del nome di dominio:

certbot revoke --email <EMAIL> --server <SERVER URL> --cert-path /etc/letsencrypt/live/<FQDN-certificato>/cert.pem

Rinnovo automatico e forzato dei certificati

La semplicità con cui è possibile rinnovare i certificati è molto probabilmente il maggior punto di forza di ACME e certbot.

Il rinnovo avviene con il comando renew e rinnova automaticamente tutti i certificati presenti in /etc/letsencrypt e che stanno per scadere entro 30 giorni:

certbot renew

Ci sono una serie di opzioni utili per il rinnovo dei certificati che è bene conoscere:

  • --quiet silenzia il comando, utile per richiamare il rinnovo da cron.
  • --force-renewal forza il rinnovo di tutti i certificati indipendentemente dalla loro data di scadenza.
  • --reuse-key rinnova solo il certificato, ma non emette anche una nuova chiave (default false).

Molti dei pacchetti di installazione di certbot includono già una configurazione di base per il rinnovo dei certificati via cron. Ad esempio su Debian 10 il pacchetto certbot installa il seguente cron job in /etc/cron.d/certbot:

# /etc/cron.d/certbot: crontab entries for the certbot package
#
# Upstream recommends attempting renewal twice a day
#
# Eventually, this will be an opportunity to validate certificates
# haven't been revoked, etc. Renewal will only occur if expiration
# is within 30 days.
#
# Important Note! This cronjob will NOT be executed if you are
# running systemd as your init system. If you are running systemd,
# the cronjob.timer function takes precedence over this cronjob. For
# more details, see the systemd.timer manpage, or use systemctl show
# certbot.timer.
SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
0 */12 * * * root test -x /usr/bin/certbot -a \! -d /run/systemd/system && perl -e 'sleep int(rand(43200))' && certbot -q renew

E' anche possibile forzare il rinnovo del certificato di un solo dominio utilizzando il comando certonly e le opportune opzioni. Ad esempio per forzare il rinnovo del nome di dominio <FQDN-certificato1>, riutilizzando la chiave esistente (sostituire <SERVER URL> con il corrispondente valore presente nell'account ACME sul CM di Harica):

certbot certonly --standalone --force-renewal --reuse-key --agree-tos --email <EMAIL> --server <SERVER URL> --domain <FQDN-certificato1>

Utilizzo di un account ACME su più server

Per utilizzare certbot su più server avete le seguenti opzioni:

  1. creare un account ACME sul CM di Harica per ogni server da abilitare e registrarlo seguendo le istruzioni "Registrazione account ACME e uso di certbot".
  2. registrare un account ACME esistente su più server seguendo le istruzioni "Registrazione account ACME e uso di certbot".
  3. copiare le chiavi di uno degli account ACME già registrati in ogni server che si desidera abilitare trasferendo tutto il contenuto della directory /etc/letsencrypt/accounts presente sul primo server su cui è stata effettuata la registrazione.

La seconda opzione dovrebbe essere la più conveniente nella maggior parte delle situazioni perché permette di tener traccia dei client su cui è stata effettuata la registrazione dell'account ACME (vedere l'apposita sezione sul CM di Harica).

(Let's encrypt) emissione, rinnovo automatico e revoca dei certificati

Tutti i comandi devono essere eseguiti da root o con sudo accedendo con ssh al server in cui gira il server HTTP.

Per l'installazione di certbot e la richiesta di certificati con Let's encrypt è caldamente consigliato seguire sempre le istruzioni ufficiali disponibili su https://certbot.eff.org. Qualora nel menù a tendina "system" non sia presente il S.O. in uso consigliamo di eseguire l'installazione via pip. Per maggiori informazioni vi consigliamo di consultare le istruzioni ufficiali e più recenti su https://certbot.eff.org.

Esempio di link per la combinazione "Apache" + "pip": https://certbot.eff.org/instructions?ws=apache&os=pip

IMPORTANTE: seguire esattamente tutti i passi indicati dalla guida di certbot.

Ogni istanza del client certbot permette la registrazione di un solo account per Certification Authority ma anche la registrazione di un secondo account se proveniente da una Certification Authority diversa.

Quali account sono registrati in un'istanza di certbot

Tramite i seguenti comandi si può scoprire se un'instanza di certbot ha già degli account associati:

  • certbot show_account (Let’s encrypt)

Il web server deve essere raggiungibile

Prima di poter richiedere un certificato con Let's encrypt assicurarsi che il fqdn del server sia raggiungibile via web.

In caso negativo non sarà possibile procedere con la richiesta di certificato usando le istruzioni seguenti. Fare riferimento alla documentazione di certbot per tutte le altre casistiche.

Richiedere e installare in automatico un certificato

Lanciare il seguente comando per richiedere un certificato ed installarlo su Apache:

sudo certbot --apache

o su Nginx:

sudo certbot --nginx

Richiedere un certificato senza installazione automatica

Per richiedere un certificato in maniera più conservativa senza installazione su Apache:

sudo certbot certonly --apache

o per Nginx

sudo certbot certonly --nginx

Installare manualmente il certificato tramite i file di configurazione del server web.

Consultare la lista dei certificati gestiti dal client certbot

Lanciare il comando:

certbot certificates

oppure consultare il contenuto delle cartelle /etc/letsencrypt/{live,archive}

Revocare un certificato

Con certbot esistono due modalità per revocare un certificato: tramite opzione cert-name e indicando direttamente il percorso del file.

certbot revoke --cert-name example.com

certbot revoke --cert-path /etc/letsencrypt/live/example.com/cert.pem

Completata la revoca certbot chiederà se si desidera cancellare i certificati appena revocati. Se i certificati revocati non sono stati cancellati certbot proverà a rinnovarli durante il prossimo rinnovo automatico.

Consultazione certificati

Per consultare la situazione dei certificati emessi accedere al sito:

https://crt.sh/

seguendo le istruzioni di ricerca fornite dal sito stesso.