acme-letsencrypt

Aperçu

Il s'agit d'un rôle purement Ansible pour accomplir les tâches suivantes :

• Créer des clés privées ECC ou RSA
• Générer des demandes de signature de certificat (pour plusieurs domaines)
• Envoyer la demande à Let's Encrypt ou à un autre fournisseur ACME de votre choix
• Installer tous les fichiers à un emplacement déterminé

J'ai écrit ce rôle pour obtenir des certificats Let's Encrypt sans avoir besoin de dépendre d'outils tiers (comme certbot, acme-tiny, acme.sh, etc.) et avoir plus de contrôle sur ce qui se passe.

Actuellement, seuls les challenges HTTP sont pris en charge.

Étant donné qu'il ne s'agit que d'un rôle Ansible, il ne gère pas le renouvellement automatique des certificats. Pour cela, vous pouvez soit exécuter ce rôle périodiquement depuis votre pipeline CI/CD, soit le faire fonctionner en mode Ansible Pull avec un crontab.

Version d'Ansible

Ce rôle, à partir de la version 2.0.0, est garanti compatible uniquement avec Ansible >=2.10.

Si vous avez besoin de compatibilité avec <2.10 (appelé "pré-collections"), utilisez toute version avec un tag 1.x.x.

Exigences

Sur l'hôte cible :

• openssl

Exemples de playbooks

Utiliser une clé ECC secp384r1 pour un certificat SAN (plusieurs domaines).

- name: "Obtenir des certificats pour webserver01"
  hosts: webserver01
  become: true
  roles:
    - dhach.acme_letsencrypt
  vars:
    le_base_directory: /etc/letsencrypt
    le_certificates:
      - name: ecc.example.com
        domains:
          - secp.example.com
          - ecc.example.com
        key:
          curve: secp384r1

Maintenant, utilisez une clé secp256r1, forcez sa recréation, puis émettez la demande contre le serveur de validation de production de Let's Encrypt :

- name: "Obtenir des certificats pour webserver02"
  hosts: webserver02
  become: true
  roles:
    - dhach.acme_letsencrypt
  vars:
    le_acme_directory: https://acme-v02.api.letsencrypt.org/directory
    le_certificates:
      - name: another-domain.example.com
        domains:
          - another-domain-abc.example.com
          - another-domain-def.example.com
          - another-domain-ghi.example.com
          - another-domain-jkl.example.com
          - another-domain-mno.example.com
        ssl:
          type: ECC
          curve: secp256r1
          renew: true

Ou utilisez des clés RSA pour obtenir un certificat pour chaque domaine :

- name: "Obtenir des certificats pour webserver03"
  hosts: webserver03
  become: true
  roles:
    - dhach.acme_letsencrypt
  vars:
    le_certificates:
      - name: example.com
        domains:
          - foo.example.com
        key:
          type: RSA
          size: 4096
      - name: more.example.com
        domains:
          - bar.example.com
        key:
           type: RSA
           size: 4096

Où trouver les fichiers

Toutes les clés générées, les demandes de certificat et les certificats subséquents peuvent être trouvés sous la valeur de {{ le_base_directory }}/{{ le_certificates['name'] }}.

Par exemple, si vous spécifiez un name de 'example.com', et que le_base_directory est défini sur '/etc/letsencrypt/', le résultat serait :

/etc/letsencrypt/example.com/
├── domain.csr
├── domain.key
├── domain.pem
├── fullchain.pem
└── intermediate.pem

Comment configurer votre serveur web

Les serveurs ACME nécessitent que vous répondiez à un challenge en plaçant un fichier avec un nom et un contenu spécifiques dans un chemin prédéfini que votre serveur web sert via HTTP.

Votre serveur web doit servir l'emplacement /.well-known/acme-challenge avec le contenu du répertoire suivant : {{ le_base_directory }}/.well-known/acme-challenge/.

Exemples si vous utilisez la valeur par défaut pour le_base_directory :

Nginx :

location /.well-known/acme-challenge {
    alias /etc/letsencrypt/.well-known/acme-challenge/;
}

Apache :

Alias /.well-known/acme-challenge/ "/etc/letsencrypt/.well-known/acme-challenge/"
<Directory "/etc/letsencrypt/.well-known/acme-challenge/">
    AllowOverride None
    Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
    Require method GET POST OPTIONS
</Directory>

Variables et valeurs par défaut du rôle

Toutes les variables définies sont listées ci-dessous, avec leurs valeurs par défaut respectives.

Demandes de certificat

Vous pouvez contrôler pour quels domaines le certificat doit être demandé. Vous avez également la possibilité de spécifier des détails concernant la génération de clés. Les options peuvent légèrement différer entre les clés RSA et ECC.

Toutes les demandes de certificat sont construites en tant que demandes SAN (SubjectAltName).

ECC :

le_certificates:
  - name: example.com  # essentiellement un identifiant interne et où sauvegarder le fichier
    domains:  # une liste de domaines pour lesquels vous souhaitez que le certificat soit émis
      - foo.example.com
      - bar.example.com
    key:  # détails pour la clé privée, si une doit être générée
      type: ECC  # (obligatoire) Types pris en charge : ECC, RSA
      curve: secp384r1  # (optionnel | par défaut : secp384r1) Courbe pour la clé ECC (aucun effet sur les clés RSA).
      renew: false  # (optionnel | par défaut : false) Si vous souhaitez recréer la clé. Un backup sera toujours gardé

RSA :

le_certificates:
  - name: example.com  # essentiellement un identifiant interne et où sauvegarder le fichier
    domains:  # une liste de domaines pour lesquels vous souhaitez que le certificat soit émis
      - foo.example.com
      - bar.example.com
    key:  # détails pour la clé privée, si une doit être générée
      type: RSA  # (obligatoire) Types pris en charge : ECC, RSA
      size: 4096  # (optionnel | par défaut : 4096) Longueur de la clé RSA (aucun effet sur les clés ECC)
      renew: false  # (optionnel | par défaut : false) Si vous souhaitez recréer la clé. Un backup sera toujours gardé

Répertoires et permissions

le_base_directory: Le répertoire de base où placer tous les fichiers générés (par défaut : /etc/letsencrypt)

le_files_owner: Qui devrait posséder les fichiers et dossiers générés (par défaut : root)

le_files_group: À quel groupe les fichiers et dossiers générés devraient appartenir (par défaut : root)

Clé de compte Let's Encrypt

le_account_key_path: Où mettre (ou trouver) la clé de compte Let's Encrypt (par défaut : "{{ le_base_directory }}/account.key")

le_account_key_type: Quel type de clé (RSA, ECC) utiliser pour la clé de compte (par défaut : RSA)

le_account_key_size: La taille de la clé. Seulement pour les clés RSA. (par défaut : 4096)

le_account_key_curve: Quelle courbe utiliser. Seulement pour les clés ECC, n'a pas d'effet pour les clés RSA. (par défaut : secp384r1)

le_account_key_regenerate: Si on doit régénérer une clé existante ou non. Un backup sera gardé. (par défaut : false)

Malheureusement, Let's Encrypt ne prend pas facilement en charge les clés de compte ECC. Il vaut mieux laisser cela en RSA 4096.

Version et répertoire Let's Encrypt / ACME

le_acme_version: Version ACME à utiliser. Peut être nécessaire si vous choisissez d'utiliser un autre émetteur qu'Let's Encrypt (par défaut : 2)

le_acme_directory: L'URL du répertoire ACME pour demander des certificats. Pour des raisons de sécurité, la valeur par défaut est définie sur Let's Encrypt Staging (par défaut : https://acme-staging-v02.api.letsencrypt.org/directory)

Le répertoire de production de Let's Encrypt est : https://acme-v02.api.letsencrypt.org/directory

le_renew_if_invalid_after: Essayer de renouveler les certificats s'ils sont valides depuis moins de ce nombre de jours (par défaut : 30)

le_force_renew: essayer de renouveler les certificats de force (par défaut : false)

le_csr_only: Si vous souhaitez simplement générer des clés privées et des CSR, mettez cela sur true. Cela peut être utile pour le débogage. (par défaut : false)

Contribuer et signaler des problèmes

Toutes les contributions sont les bienvenues. N'hésitez pas à ouvrir des problèmes ou à créer des demandes de tirage.

Je vais me pencher sur tout problème soulevé et toujours essayer d'améliorer le rôle.

Tests

Tous les tests sont effectués avec Molecule.

Un pipeline CI est réalisé avec GitHub Actions et utilise une stratégie de matrice, qui teste sur Ubuntu, Debian et CentOS.

Pour commencer les tests locaux, créez un environnement Python local, installez toutes les dépendances et exécutez les tests. Cela nécessite Docker installé sur votre machine (ou l'utilisation de Docker-Machine) :

python3 -m venv venv
source venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r test-requirements.txt

molecule test

Étant donné que ce rôle nécessite essentiellement d'émettre des demandes contre un serveur ACME et a donc besoin de contrôle sur un domaine pour lequel il doit définir dynamiquement un enregistrement DNS, le test est limité à la vérification de la syntaxe, à la vérification de la création des clés et des CSR et à s'assurer qu'ils contiennent le contenu attendu.

Le test de l'ensemble du rôle avec toutes ses fonctionnalités se fait contre le serveur de staging de Let's Encrypt sur une machine connectée à Internet, mais manuellement.

Licence

Licence publique générale GNU v3.0