Services de certificats (Manuel de référence de GNU Guix)

11.10.21 Services de certificats

Le module (gnu services certbot) fournit un service qui récupère automatiquement un certificat TLS valide de l’autorité de certification Let’s Encrypt. Ces certificats peuvent ensuite être utilisés pour servir du contenu de manière sécurisée sur HTTPS et d’autres protocoles basés sur TLS, en sachant que le client sera capable de vérifier l’authenticité du serveur.

Let’s Encrypt fournit l’outil certbot pour automatiser le processus de certification. Cet outil génère d’abord un clef sur le serveur de manière sécurisée. Ensuite il demande à l’autorité de certification Let’s Encrypt de signer la clef. La CA vérifie que la requête provient de l’hôte en question en utilisant un protocole de défi-réponse, ce qui requiert que le serveur fournisse sa réponse par HTTP. Si ce protocole se passe sans encombre, la CA signe la clef et on obtient un certificat. Ce certificat est valide pour une durée limitée et donc, pour continuer à fournir des services en TLS, le serveur doit régulièrement demander à la CA de renouveler sa signature.

Le service certbot automatise ce processus : la génération initiale de la clef, la demande de certification initiale au service Let’s Encrypt, l’intégration du protocole de défi/réponse dans le serveur web, l’écriture du certificat sur le disque, les renouvellements périodiques et les tâches de déploiement avec le renouvellement (p. ex. recharger les services, copier les clefs avec d’autres permissions).

Certbot est lancé deux fois par jour, à une minute aléatoire dans l’heure. Il ne fera rien sauf si vos certificats doivent être renouvelés ou sont révoqués, mais le lancer régulièrement permettra à vos services de rester en ligne si Let’s Encrypt décide de révoquer votre certificat.

En utilisant ce service, vous acceptez le document « ACME Subscriber Agreement », qu’on peut trouver ici : https://acme-v01.api.letsencrypt.org/directory.

Variable :certbot-service-type

Un type de service pour le client Let’s Encrypt certbot. Sa valeur doit être un enregistrement certbot-configuration comme dans cet exemple :

(service certbot-service-type
         (certbot-configuration
          (email "foo@example.net")
          (certificates
           (list
            (certificate-configuration
             (domains '("example.net" "www.example.net")))
            (certificate-configuration
             (domains '("bar.example.net")))))))

Voir plus bas pour des détails sur certbot-configuration.

Type de données :certbot-configuration

Type données représentant la configuration du service certbot. Ce type a les paramètres suivants :

package (par défaut : certbot)

Le paquet certbot à utiliser.

webroot (par défaut : /var/www)

Le répertoire depuis lequel servir les fichiers du défi/réponse de Let’s Encrypt.

certificates (par défaut : '())

Une liste de certificates-configuration pour lesquels générer des certificats et demander des signatures. Chaque certificat a un name et plusieurs domains.

email (par défaut : #f)

Adresse de courriel facultative pour la création de compte et le contact de récupération de compte. Il est recommandé de l’indiquer car cela vous permet de recevoir des notifications importantes à propos de votre compte et des certificats créés.

server (par défaut : #f)

URL facultative d’un serveur ACME. Indiquer ce paramètre remplace la valeur de certbot par défaut, qui est le serveur de Let’s Encrypt.

rsa-key-size (par défaut : 2048)

Taille de la clef RSA.

default-location (par défaut : voir plus bas)

Le nginx-location-configuration par défaut. Comme certbot doit pouvoir servir les défis et les réponses, il doit être capable de lancer un serveur web. Cela se fait en étendant le service web nginx avec un nginx-server-configuration qui écoute sur les domains sur le port 80 et qui a un nginx-location-configuration pour le chemin /.well-known/ utilisé par Let’s Encrypt. Voir Services web pour plus d’information sur les types de données de la configuration de nginx.

Les requêtes vers d’autres URL correspondra à default-location, qui, s’il est présent, sera ajout é à tous les nginx-server-configuration.

Par défaut, le default-location sera une redirection de http://domain/… vers https://domain/…, en vous laissant définir ce que vous voulez servir sur votre site en https.

Passez #f pour ne pas utiliser de location par défaut.

Type de données :certificate-configuration

Type de données représentant la configuration d’un certificat. Ce type a les paramètres suivants :

name (par défaut : voir plus bas)

Ce nom est utilisé par Certbot pour ses tâches quotidiennes et dans les chemins de fichiers ; il n’affecte pas le contenu des certificats eux-mêmes. Pour voir les noms des certificats, lancez certbot certificates.

Sa valeur par défaut est le premier domaine spécifié.

domains (par défaut : '())

Le premier domaine spécifié sera le CN du sujet du certificat, et tous les domaines seront les noms alternatifs du sujet dans le certificat.

challenge (par défaut : #f)

Le type de défi à utiliser avec certbot. Si #f est spécifié, le défi HTTP par défaut sera utilisé. Si une valeur est spécifiée, le greffon manuel sera utilisé par défaut (voir authentication-hook, cleanup-hook et la documentation sur https://certbot.eff.org/docs/using.html#hooks), et donne à Let’s Encrypt la permission d’enregistrer l’adresse IP publique de la machine qui a fait la demande.

csr (par défaut : #f)

Nom de fichier d’une Demande de Signature de Certificat (CSR) au format DER ou PEM. Si #f est spécifié, cet argument ne sera pas passé à certbot. Si une valeur est spécifiée, certbot l’utilisera pour obtenir un certificat, au lieu d’utiliser une CSR auto-signée. Le(s) nom(s) de domaine mentionné(s) dans domains doivent être en cohérence avec ceux mentionné(s) dans le fichier CSR.

authentication-hook (par défaut : #t)

Commande à lancer dans un shell une fois par défi de certificat auquel répondre. Pour cette commande, la variable shell $CERTBOT_DOMAIN contiendra le domaine à authentifier, $CERTBOT_VALIDATION contiendra la chaîne de validation et $CERTBOT_TOKEN contiendra le nom de fichier de la ressource demandée pour le défi HTTP-01.

cleanup-hook (par défaut : #f)

Commande à lancer dans un shell une fois par défi de certificat auquel auth-hook a répondu. Pour cette commande, les variables shell disponibles dans le script auth-hook sont toujours disponibles, et en plus $CERTBOT_AUTH_OUTPUT contiendra la sortie standard du script auth-hook.

deploy-hook (par défaut : #f)

Commande à lancer dans un shell une fois par certificat récupéré avec succès. Pour cette commande, la variable $RENEWED_LINEAGE pointera sur le sous-répertoire live (par exemple, ‘"/etc/letsencrypt/live/example.com"’) contenant le nouveau certificat et la clef ; la variable $RENEWED_DOMAINS contiendra les noms de domaines séparés par des espaces (par exemple ‘"example.com www.example.com"’).

start-self-signed? (default: #t)

Whether to generate an initial self-signed certificate during system activation. This option is particularly useful to allow nginx to start before certbot has run, because certbot relies on nginx running to perform HTTP challenges.

Pour chaque certificate-configuration, le certificat est sauvegardé dans /etc/certs/name/fullchain.pem et la clef est sauvegardée dans /etc/certs/name/privkey.pem.