linux-system-roles.certificate

Rola Systemu Certyfikatów

Rola do zarządzania wydawaniem i odnawianiem certyfikatów TLS/SSL.

Podstawowe użycie:

---
- hosts: webserver

  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign

  roles:
    - linux-system-roles.certificate

Na systemie opartym na RPM certyfikat zostanie umieszczony w /etc/pki/tls/certs/mycert.crt, a klucz w /etc/pki/tls/private/mycert.key.

Wymagania

Zobacz poniżej.

Wymagania zbioru

Rola wymaga zewnętrznych zbiorów tylko do zarządzania węzłami rpm-ostree. Proszę uruchomić następujące polecenie, aby je zainstalować, jeśli potrzebujesz zarządzać węzłami rpm-ostree:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Zmienne

Parametr	Opis	Typ	Wymagany	Domyślny
certificate_wait	Czy zadanie powinno czekać na wydanie certyfikatu.	bool	nie	tak
certificate_requests	Lista słowników reprezentujących każdy certyfikat do wydania. Zobacz certificate_requests.	lista	nie	-

certificate_requests

Uwaga: Pola takie jak common_name, country, state, locality, organization, organizational_unit, email, key_usage i extended_key_usage, które mogą być zawarte w żądaniu certyfikatu, są zdefiniowane przez RFC 5280.

Uwaga: Należy pamiętać, że CA może nie uwzględnić wszystkich żądanych pól. Na przykład, nawet jeśli w żądaniu znajduje się country: US, CA może wystawić certyfikat bez country w jego temacie.

Uwaga: Pola dns, email i ip są używane do definiowania alternatywnych nazw tematu (SAN).

Parametr	Opis	Typ	Wymagany	Domyślny
name	Nazwa certyfikatu. Pełna ścieżka może być użyta do wyboru katalogu, w którym zostaną zapisane pliki.	str	tak	-
ca	CA, która wyda certyfikat. Zobacz CAs and Providers.	str	tak	-
dns	Domeny (lub lista domen), które mają być zawarte w certyfikacie. Może również zapewnić domyślną wartość dla common_name.	str lub lista	nie	-
email	Email (lub lista emaili) do umieszczenia w certyfikacie.	str lub lista	nie	-
ip	IP lub lista IP, które mają być umieszczone w certyfikacie. IP mogą być w wersji IPv4, IPv6 lub obu. Może również zapewnić domyślną wartość dla common_name.	str lub lista	nie	-
auto_renew	Określa, czy certyfikat ma być automatycznie odnawiany przed jego wygaśnięciem.	bool	nie	tak
owner	Nazwa użytkownika (lub identyfikator użytkownika) dla plików certyfikatu i klucza.	str	nie	Użytkownik uruchamiający Ansible
group	Nazwa grupy (lub identyfikator grupy) dla plików certyfikatu i klucza.	str	nie	Grupa uruchamiająca Ansible
mode	Uprawnienia systemu plików dla plików certyfikatu i klucza.	raw	nie	-
key_size	Generowanie kluczy o określonym rozmiarze w bitach.	int	nie	2048 - Zobacz key_size
common_name	Żądana nazwa wspólna dla certyfikatu.	str	nie	Zobacz common_name
country	Kod kraju żądany dla certyfikatu.	str	nie	-
state	Stan żądany dla certyfikatu.	str	nie	-
locality	Miejscowość żądana dla certyfikatu (zazwyczaj miasto).	str	nie	-
organization	Organizacja żądana dla certyfikatu.	str	nie	-
organizational_unit	Jednostka organizacyjna żądana dla certyfikatu.	str	nie	-
contact_email	Kontaktowy email żądany dla certyfikatu.	str	nie	-
key_usage	Dozwolone użycie klucza dla certyfikatu. Aby zobaczyć ważne wartości, zobacz: key_usage.	lista	nie	Zobacz key_usage
extended_key_usage	Atrybuty zaawansowanego użycia klucza, które mają być obecne w żądaniu certyfikatu.	lista	nie	Zobacz extended_key_usage
run_before	Komenda, która powinna być wykonana przed zapisaniem certyfikatu. Zobacz run hooks.	str	nie	-
run_after	Komenda, która powinna być wykonana po zapisaniu certyfikatu. Zobacz run hooks.	str	nie	-
principal	Principal Kerberos.	str	nie	-
provider	Metoda wykorzystywana do żądania i zarządzania certyfikatem.	str	nie	Różni się w zależności od CA

common_name

Jeśli common_name nie jest ustawione, rola spróbuje użyć pierwszej wartości dns lub ip jako domyślnej. Jeśli dns i ip są również nie ustawione, common_name nie zostanie uwzględnione w certyfikacie.

key_size

Zalecane minimalne wartości dla rozmiaru klucza certyfikatu różnią się w zależności od organizacji i zmieniają się z czasem. W celu zapewnienia bezpiecznych ustawień domyślna minimalna wartość dla key_size będzie w przyszłości zwiększana.

Jeśli chcesz, aby twoje certyfikaty miały zawsze ten sam rozmiar key_size przy odnawianiu, ustaw tę zmienną na pożądaną wartość.

key_usage

Ważne wartości dla key_usage to:

digitalSignature
nonRepudiation
keyEncipherment
dataEncipherment
keyAgreement
keyCertSign
cRLSign
encipherOnly
decipherOnly

Domyślne wartości dla key_usage to:

digitalSignature
keyEncipherment

extended_key_usage

Każdy ważny oid może być użyty do ustawienia jednego lub więcej extended_key_usage. Oprócz tego istnieje również lista znanych aliasów, które będą rozpoznawane przez rolę:

id-kp-serverAuth
id-kp-clientAuth
id-kp-codeSigning
id-kp-emailProtection
id-kp-timeStamping
id-kp-OCSPSigning
id-kp-ipsecEndSystem
id-kp-ipsecTunnel
id-kp-ipsecUser

Jeśli extended_key_usage nie jest ustawione, rola domyślnie ustawi:

id-kp-serverAuth
id-kp-clientAuth

run hooks

Czasami trzeba wykonać polecenie tuż przed odnowieniem certyfikatu i inne polecenie tuż po. Aby to zrobić, użyj run_before i run_after.

Wartości przekazane do run_before i run_after będą opakowane i przechowywane w plikach skryptów powłoki, które później będą wykonane przez dostawcę.

CAs i Dostawcy

CA	Dostawcy	Opis CA	Wymagania
self-sign	certmonger*	Wydawaj certyfikaty samopodpisane z lokalnej CA.
ipa	certmonger*	Wydawaj certyfikaty przy użyciu CA FreeIPA.	Host musi być zarejestrowany w serwerze FreeIPA.

* Domyślny dostawca.

CA reprezentuje certyfikaty CA, które będą używane do wydawania i podpisywania żądanego certyfikatu. Dostawca reprezentuje metodę wykorzystywaną do wysłania żądania certyfikatu do CA i następnie uzyskania podpisanego certyfikatu.

Jeśli użytkownik wybierze CA self-sign przy pomocy certmonger, a następnie zdecyduje się zmienić dostawcę na openssl, certyfikaty CA używane w obu przypadkach muszą być takie same. Należy zauważyć, że openssl nie jest jeszcze wspieranym dostawcą i jest wymieniane tutaj jedynie jako przykład.

Certmonger i SELinux

Jeśli SELinux jest włączony, usługa certmonger może tylko pisać lub edytować pliki w katalogach, gdzie obecny jest kontekst cert_t.

Dodatkowo, jeśli skrypty wykonywane przez parametry run_before i run_after muszą pisać lub edytować pliki, te skrypty również muszą mieć kontekst cert_t przed wykonaniem roli.

Możesz używać Roli Systemu selinux, aby zarządzać kontekstami SELinux.

Dla uzyskania więcej informacji o wymaganiach certmonger i SELinux, zobacz certmonger_selinux(8) man pages.

Przykłady

Wydanie certyfikatu samopodpisanego

Wydaj certyfikat dla *.example.com i umieść go w standardowym katalogu dla dystrybucji.

---
- hosts: webserver

  vars:
    certificate_requests:
      - name: mycert
        dns: *.example.com
        ca: self-sign

  roles:
    - linux-system-roles.certificate

Możesz znaleźć katalogi dla każdej dystrybucji w następujących lokalizacjach:

Debian/Ubuntu:
- Certyfikaty: /etc/ssl/localcerts/certs/
- Klucze: /etc/ssl/localcerts/private/
RHEL/CentOS/Fedora:
- Certyfikaty: /etc/pki/tls/certs/
- Klucze: /etc/pki/tls/private/

Wybór miejsca, w którym umieścić certyfikaty

Wydaj certyfikat i klucz oraz umieść je w określonej lokalizacji. Poniższy przykład tworzy plik certyfikatu w /another/path/mycert.crt i plik klucza w /another/path/mycert.key.

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: /another/path/mycert
        dns: *.example.com
        ca: self-sign

  roles:
    - linux-system-roles.certificate

Wydanie certyfikatów z wieloma DNS, IP i emailami

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns:
          - www.example.com
          - sub1.example.com
          - sub2.example.com
          - sub3.example.com
        ip:
          - 192.0.2.12
          - 198.51.100.65
          - 2001:db8::2:1
        email:
          - [email protected]
          - [email protected]
        ca: self-sign

  roles:
    - linux-system-roles.certificate

Ustawianie wspólnych opcji subiektu

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        common_name: www.example.com
        ca: self-sign
        country: US
        state: NY
        locality: Nowy Jork
        organization: Red Hat
        organizational_unit: platforma
        email: [email protected]
  roles:
    - linux-system-roles.certificate

Ustawianie rozmiaru klucza certyfikatu

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
        key_size: 4096
  roles:
    - linux-system-roles.certificate

Ustawianie "Użycia klucza" i "Rozszerzonego użycia klucza" (EKU)

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
        key_usage:
          - digitalSignature
          - nonRepudiation
          - keyEncipherment
        extended_key_usage:
          - id-kp-clientAuth
          - id-kp-serverAuth
  roles:
    - linux-system-roles.certificate

Nie czekaj na wydanie certyfikatu

Wydanie certyfikatu może potrwać kilka minut w zależności od CA. Dlatego możliwe jest również zażądanie certyfikatu, ale nie czekanie na niego.

Ta konfiguracja dotyczy wszystkich certyfikatów: jeśli certificate_wait jest ustawione na nie, rola nie czeka na żaden certyfikat.

---
- hosts: webserver
  vars:
    certificate_wait: false
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
  roles:
    - linux-system-roles.certificate

Ustawianie principal

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
        principal: HTTP/[email protected]

  roles:
    - linux-system-roles.certificate

Wybór, by nie odnawiać certyfikatu automatycznie

Domyślnie certyfikaty generowane przez rolę są ustawione na automatyczne odnawianie. Aby wyłączyć to zachowanie, ustaw auto_renew: nie.

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
        auto_renew: nie

  roles:
    - linux-system-roles.certificate

Użycie FreeIPA do wydania certyfikatu

Jeśli twój host jest zarejestrowany w serwerze FreeIPA, masz również możliwość użycia jego CA do wydania certyfikatu. Aby to zrobić, ustaw ca: ipa.

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        principal: HTTP/[email protected]
        ca: ipa

  roles:
    - linux-system-roles.certificate

Uruchamianie polecenia przed lub po wydaniu certyfikatu

Czasami trzeba wykonać polecenie tuż przed odnowieniem certyfikatu i inne polecenie tuż po. Aby to zrobić, użyj run_before i run_after.

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
        run_before: systemctl stop webserver.service
        run_after: systemctl start webserver.service

  roles:
    - linux-system-roles.certificate

Ustawianie właściciela i grupy certyfikatu

Jeśli używasz certyfikatu dla usługi, na przykład httpd, musisz ustawić właściciela i grupę certyfikatu, który będzie miał certyfikat. W następującym przykładzie właściciel i grupa są ustawione na httpd.

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
        owner: httpd
        group: httpd

  roles:
    - linux-system-roles.certificate