acme-letsencrypt

Przegląd

To jest czysta rola Ansible, która zapewnia następujące funkcje:

• Tworzenie kluczy prywatnych ECC lub RSA
• Generowanie żądań podpisania certyfikatu (dla wielu domen)
• Wysyłanie żądania do Let's Encrypt lub innego dostawcy ACME według wyboru
• Instalacja wszystkich plików w określonej lokalizacji

Napisałem tę rolę, aby uzyskać certyfikaty Let's Encrypt bez polegania na zewnętrznych narzędziach (takich jak certbot, acme-tiny, acme.sh itp.) i mieć lepszą kontrolę nad tym, co się dzieje.

Obecnie wspierany jest tylko typ wyzwania HTTP.

Ponieważ to jest tylko rola Ansible, nie obsługuje automatycznego odnawiania certyfikatów. Możesz uruchamiać tę rolę okresowo w swoim pipeline CI/CD lub używać jej w trybie Ansible Pull z crontabem.

Wersja Ansible

Ta rola, począwszy od wersji 2.0.0, jest gwarantowana do współpracy tylko z Ansible >=2.10.

Jeśli potrzebujesz zgodności z <2.10 (tzw. "pre-kolekcje"), użyj dowolnej wersji z tagiem 1.x.x.

Wymagania

Na docelowym hoście:

• openssl

Przykłady playbooków

Używając klucza ECC secp384r1 dla certyfikatu SAN (wiele domen).

- name: "Pobierz certyfikaty dla 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

Teraz użyj klucza secp256r1, wymuś jego ponowne utworzenie, a następnie wydaj żądanie do serwera weryfikacji produkcji Let's Encrypt:

- name: "Pobierz certyfikaty dla 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

Lub użyj kluczy RSA, aby uzyskać jeden certyfikat dla każdej domeny:

- name: "Pobierz certyfikaty dla 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

Gdzie znaleźć pliki

Wszystkie wygenerowane klucze, żądania certyfikatów i kolejne certyfikaty można znaleźć pod wartością {{ le_base_directory }}/{{ le_certificates['name'] }}.

Na przykład, jeśli określisz nazwę 'example.com', a le_base_directory jest ustawione na '/etc/letsencrypt/', rezultat będzie wyglądał następująco:

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

Jak skonfigurować swój serwer WWW

Serwery ACME wymagają odpowiedzi na wyzwanie, umieszczając plik o określonej nazwie i treści w wyznaczonej ścieżce, którą serwer WWW udostępnia przez HTTP.

Twój serwer WWW musi serwować lokalizację /.well-known/acme-challenge z zawartością następującego katalogu: {{ le_base_directory }}/.well-known/acme-challenge/.

Przykłady przy użyciu domyślnej wartości dla 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>

Zmienne i domyślne ustawienia roli

Wszystkie zdefiniowane zmienne są wymienione poniżej, z odpowiednimi domyślnymi wartościami.

Żądania certyfikatów

Możesz kontrolować, dla jakich domen żądany jest certyfikat. Masz także możliwość określenia szczegółów dotyczących generacji kluczy. Opcje nieco różnią się między kluczami RSA i ECC.

Wszystkie żądania certyfikatów są konstrukcjami SAN (SubjectAltName).

ECC:

le_certificates:
  - name: example.com  # wewnętrzny identyfikator i miejsce zapisu pliku
    domains:  # lista domen, dla których chcesz uzyskać certyfikat
      - foo.example.com
      - bar.example.com
    key:  # szczegóły dla klucza prywatnego, jeśli ma być wygenerowany
      type: ECC  # (obowiązkowe) Wspierane typy: ECC, RSA
      curve: secp384r1  # (opcjonalne | domyślne: secp384r1) Krzywa dla klucza ECC (nie ma wpływu na klucze RSA).
      renew: false  # (opcjonalne | domyślne: false) Czy wymusić ponowne utworzenie klucza. Zawsze będzie zachowana kopia zapasowa

RSA:

le_certificates:
  - name: example.com  # wewnętrzny identyfikator i miejsce zapisu pliku
    domains:  # lista domen, dla których chcesz uzyskać certyfikat
      - foo.example.com
      - bar.example.com
    key:  # szczegóły dla klucza prywatnego, jeśli ma być wygenerowany
      type: RSA  # (obowiązkowe) Wspierane typy: ECC, RSA
      size: 4096  # (opcjonalne | domyślne: 4096) Długość klucza RSA (nie ma wpływu na klucze ECC)
      renew: false  # (opcjonalne | domyślne: false) Czy wymusić ponowne utworzenie klucza. Zawsze będzie zachowana kopia zapasowa

Katalogi i uprawnienia

le_base_directory: Katalog główny, w którym umieszczane będą wszystkie wygenerowane pliki (domyślnie: /etc/letsencrypt)

le_files_owner: Kto powinien być właścicielem wygenerowanych plików i folderów (domyślnie: root)

le_files_group: Do jakiej grupy powinny należyć wygenerowane pliki i foldery (domyślnie: root)

Klucz konta Let's Encrypt

le_account_key_path: Gdzie umieścić (lub znaleźć) klucz konta Let's Encrypt (domyślnie: "{{ le_base_directory }}/account.key")

le_account_key_type: Jaki typ klucza (RSA, ECC) używać dla klucza konta (domyślnie: RSA)

le_account_key_size: Rozmiar klucza. Tylko dla kluczy RSA. (domyślnie: 4096)

le_account_key_curve: Jaką krzywą używać. Tylko dla kluczy ECC, nie ma wpływu na klucze RSA. (domyślnie: secp384r1)

le_account_key_regenerate: Czy regenerować istniejący klucz. Będzie zachowana kopia zapasowa. (domyślnie: false)

Niestety, Let's Encrypt nie obsługuje łatwo kluczy konta ECC. Najlepiej pozostawić go na RSA 4096.

Wersja ACME Let's Encrypt oraz katalog

le_acme_version: Wersja ACME do użycia. Może być konieczna, jeśli zdecydujesz się używać innego dostawcy niż Let's Encrypt (domyślnie: 2)

le_acme_directory: URL katalogu ACME, aby żądać certyfikatów. Z powodów bezpieczeństwa domyślnie ustawiono na środowisko testowe Let's Encrypt (domyślnie: https://acme-staging-v02.api.letsencrypt.org/directory)

Katalog produkcyjny Let's Encrypt to: https://acme-v02.api.letsencrypt.org/directory.

le_renew_if_invalid_after: Spróbuj odnowić certyfikaty, jeśli ważne są mniej niż określona ilość dni (domyślnie: 30)

le_force_renew: spróbuj wymusić odnowienie certyfikatów (domyślnie: false)

le_csr_only: Jeśli chcesz tylko, aby wygenerowano klucze prywatne i CSR, ustaw to na true. Może być przydatne do debugowania. (domyślnie: false)

Współpraca i zgłaszanie problemów

Wszystkie wkłady są mile widziane. Nie wahaj się zgłaszać problemów lub tworzyć pull requestów.

Z przyjemnością zajmę się każdym zgłoszonym problemem i zawsze staram się poprawić rolę.

Testowanie

Wszystkie testy są przeprowadzane za pomocą Molecule.

Pipeline CI zrealizowano za pomocą GitHub Actions i korzysta ze strategii macierzy, która testuje na Ubuntu, Debian oraz CentOS.

Aby rozpocząć lokalne testy, skonfiguruj lokalne środowisko Python, zainstaluj wszystkie zależności i uruchom testy. Wymagana jest instalacja Dockera na Twoim komputerze (lub użycie 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

Ponieważ ta rola zasadniczo wymaga składania żądań do serwera ACME i w związku z tym potrzebowałaby kontroli nad domeną, dla której dynamicznie ustawia rekord DNS, testowanie jest ograniczone do linterowania, sprawdzania, czy klucze i CSR zostały utworzone i są obecne, oraz czy zawierają oczekiwaną zawartość.

Testowanie pełnej roli ze wszystkimi funkcjonalnościami jest przeprowadzane na serwerze testowym Let's Encrypt na prawdziwej, podłączonej do Internetu maszynie, ale ręcznie.

Licencja

GNU General Public License w wersji 3.0