acme-letsencrypt

Überblick

Dies ist eine reine Ansible-Rolle, um Folgendes zu erreichen:

• Erstellen Sie ECC- oder RSA-Privatschlüssel
• Generieren Sie Zertifikatanfragen (für mehrere Domains)
• Senden Sie die Anfrage an Let's Encrypt oder einen anderen ACME-Anbieter Ihrer Wahl
• Installieren Sie alle Dateien an einem vorhersehbaren Ort

Ich habe diese Rolle geschrieben, um Let's Encrypt-Zertifikate zu erhalten, ohne auf Drittanbieter-Tools (wie certbot, acme-tiny, acme.sh usw.) angewiesen zu sein und mehr Kontrolle darüber zu haben, was passiert.

Derzeit wird nur der HTTP-Herausforderungstyp unterstützt.

Da dies nur eine Ansible-Rolle ist, kümmert sie sich nicht um die automatische Zertifikatsverlängerung. Um dies zu erreichen, können Sie diese Rolle entweder regelmäßig aus Ihrer CI/CD-Pipeline ausführen oder im Ansible Pull-Modus mit einem Crontab arbeiten.

Ansible-Version

Diese Rolle ist ab Version 2.0.0 nur mit Ansible >=2.10 kompatibel.

Wenn Sie Kompatibilität mit <2.10 benötigen (auch bekannt als "pre-collections"), verwenden Sie jede Version mit einem 1.x.x-Tag.

Anforderungen

Auf dem Zielhost:

• openssl

Beispiele für Playbooks

Verwendung eines secp384r1 ECC-Schlüssels für ein SAN-Zertifikat (mehrere Domains).

- name: "Zertifikate für webserver01 abrufen"
  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

Nun verwenden Sie einen secp256r1-Schlüssel, lassen ihn gewaltsam neu erstellen und senden dann die Anfrage an den Produktionsvalidierungsserver von Let's Encrypt:

- name: "Zertifikate für webserver02 abrufen"
  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

Oder verwenden Sie RSA-Schlüssel, um jeweils ein Zertifikat für jede Domain zu erhalten:

- name: "Zertifikate für webserver03 abrufen"
  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

Wo Sie die Dateien finden

Alle generierten Schlüssel, Zertifikatsanfragen und nachfolgenden Zertifikate finden Sie unter dem Wert von {{ le_base_directory }}/{{ le_certificates['name'] }}.

Zum Beispiel, wenn Sie einen name von 'example.com' angeben und le_base_directory auf '/etc/letsencrypt/' gesetzt ist, wäre das Ergebnis:

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

So konfigurieren Sie Ihren Webserver

ACME-Server verlangen, dass Sie eine Herausforderung beantworten, indem Sie eine Datei mit einem bestimmten Namen und Inhalt in einem vordefinierten Pfad ablegen, den Ihr Webserver über HTTP bereitstellt.

Ihr Webserver muss den Speicherort /.well-known/acme-challenge mit dem Inhalt des folgenden Verzeichnisses bereitstellen: {{ le_base_directory }}/.well-known/acme-challenge/.

Beispiele bei Verwendung des Standardwerts für 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>

Rollenvariablen und Standardwerte

Alle definierten Variablen sind unten aufgelistet, mit den jeweiligen Standardvariablen.

Zertifikatsanfragen

Sie können steuern, für welche Domains das Zertifikat angefragt werden soll. Sie haben auch die Möglichkeit, Details zur Schlüsselerstellung anzugeben. Die Optionen unterscheiden sich leicht zwischen RSA- und ECC-Schlüsseln.

Alle Zertifikatsanfragen werden als SAN (SubjectAltName) Anfragen konstruiert.

ECC:

le_certificates:
  - name: example.com  # im Wesentlichen ein interner Bezeichner und wo die Datei gespeichert werden soll
    domains:  # eine Liste von Domains, für die das Zertifikat ausgestellt werden soll
      - foo.example.com
      - bar.example.com
    key:  # Details für den privaten Schlüssel, falls einer generiert werden soll
      type: ECC  # (obligatorisch) Unterstützte Typen: ECC, RSA
      curve: secp384r1  # (optional | Standard: secp384r1) Kurve für ECC-Schlüssel (hat keinen Einfluss auf RSA-Schlüssel).
      renew: false  # (optional | Standard: false) Ob der Schlüssel gewaltsam neu erstellt werden soll. Es wird immer ein Backup gehalten.

RSA:

le_certificates:
  - name: example.com  # im Wesentlichen ein interner Bezeichner und wo die Datei gespeichert werden soll
    domains:  # eine Liste von Domains, für die das Zertifikat ausgestellt werden soll
      - foo.example.com
      - bar.example.com
    key:  # Details für den privaten Schlüssel, falls einer generiert werden soll
      type: RSA  # (obligatorisch) Unterstützte Typen: ECC, RSA
      size: 4096  # (optional | Standard: 4096) Länge des RSA-Schlüssels (hat keinen Einfluss auf ECC-Schlüssel)
      renew: false  # (optional | Standard: false) Ob der Schlüssel gewaltsam neu erstellt werden soll. Es wird immer ein Backup gehalten.

Verzeichnisse und Berechtigungen

le_base_directory: Das Basisverzeichnis, in dem alle generierten Dateien abgelegt werden (Standard: /etc/letsencrypt)

le_files_owner: Wer die generierten Dateien und Ordner besitzen soll (Standard: root)

le_files_group: Zu welcher Gruppe die generierten Dateien und Ordner gehören sollen (Standard: root)

Let's Encrypt-Kontoinformationen

le_account_key_path: Wo der Let's Encrypt-Kontoinhaber-Schlüssel abgelegt (oder gefunden) werden soll (Standard: "{{ le_base_directory }}/account.key")

le_account_key_type: Welchen Schlüsseltpy (RSA, ECC) soll für den Kontoinhaber verwendet werden (Standard: RSA)

le_account_key_size: Die Größe des Schlüssels. Nur für RSA-Schlüssel. (Standard: 4096)

le_account_key_curve: Welche Kurve verwendet werden soll. Nur für ECC-Schlüssel, hat keinen Einfluss auf RSA-Schlüssel. (Standard: secp384r1)

le_account_key_regenerate: Ob ein vorhandener Schlüssel neu generiert werden soll oder nicht. Ein Backup wird behalten. (Standard: false)

Leider unterstützt Let's Encrypt ECC-Kontoinhaber-Schlüssel nicht direkt. Am besten bleibt es bei RSA 4096.

Let's Encrypt / ACME-Version und Verzeichnis

le_acme_version: ACME-Version, die verwendet werden soll. Dies kann notwendig sein, wenn Sie einen anderen Anbieter als Let's Encrypt verwenden (Standard: 2)

le_acme_directory: Die ACME-Verzeichnis-URL, um Zertifikate anzufordern. Aus Sicherheitsgründen ist der Standard auf das Let's Encrypt-Staging gesetzt (Standard: https://acme-staging-v02.api.letsencrypt.org/directory)

Das Produktionsverzeichnis von Let's Encrypt ist: https://acme-v02.api.letsencrypt.org/directory.

le_renew_if_invalid_after: Versuchen Sie, die Zertifikate zu verlängern, wenn sie weniger als diese Anzahl an Tagen gültig sind (Standard: 30)

le_force_renew: Versuchen Sie, die Zertifikate gewaltsam zu verlängern (Standard: false)

le_csr_only: Wenn Sie nur private Schlüssel und CSRs generiert haben möchten, setzen Sie dies auf true. Kann nützlich für Debugging sein. (Standard: false)

Mitwirken und Probleme

Alle Beiträge sind willkommen. Zögern Sie nicht, Probleme zu melden oder Pull-Requests zu erstellen.

Ich werde gerne alle gemeldeten Probleme prüfen und immer versuchen, die Rolle zu verbessern.

Testen

Alle Tests werden mit Molecule durchgeführt.

Eine CI-Pipeline wird mit GitHub Actions realisiert und verwendet eine Matrixstrategie, die auf Ubuntu, Debian und CentOS testet.

Um mit lokalen Tests zu beginnen, richten Sie eine lokale Python-Umgebung ein, installieren Sie alle Abhängigkeiten und führen Sie die Tests aus. Hierfür ist Docker auf Ihrem Computer installiert erforderlich (oder die Verwendung von 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

Da diese Rolle im Wesentlichen Anfragen an einen ACME-Server stellt und daher Kontrolle über eine Domain benötigt, um dynamisch einen DNS-Eintrag festzulegen, sind die Tests auf Linting, Überprüfung der Erstellung von Schlüsseln und CSRs und deren Inhalt beschränkt.

Das Testen der gesamten Rolle mit allen Funktionen erfolgt gegen den Staging-Server von Let's Encrypt auf einer tatsächlichen, mit dem Internet verbundenen Maschine, jedoch manuell.

Lizenz

GNU General Public License v3.0