linux-system-roles.certificate

Роль системы сертификатов

Роль для управления выдачей и обновлением TLS/SSL сертификатов

Это роль для выдачи и обновления SSL сертификатов на системах Linux.

Основное использование:

---
- hosts: webserver

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

  roles:
    - linux-system-roles.certificate

На системе на основе RPM это поместит сертификат в /etc/pki/tls/certs/mycert.crt и ключ в /etc/pki/tls/private/mycert.key.

Требования

Смотрите ниже

Требования к коллекции

Роль требует внешних коллекций только для управления узлами rpm-ostree. Пожалуйста, выполните следующую команду для их установки, если необходимо управлять узлами rpm-ostree:

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

Переменные

Параметр	Описание	Тип	Обязательно	По умолчанию
certificate_wait	Должен ли процесс ждать завершения выдачи сертификата.	bool	нет	да
certificate_requests	Список словарей, представляющих каждый сертификат для выдачи. См. certificate_requests.	список	нет	-

certificate_requests

Примечание: Поля такие как common_name, country, state, locality, organization, organizational_unit, email, key_usage и extended_key_usage, которые могут быть включены в запрос сертификата, определены RFC 5280.

Примечание: Имейте в виду, что Удостоверяющий Центр (CA) может не учитывать все запрашиваемые поля. Например, даже если в запросе указано country: US, CA может выдать сертификат без указания country в его предмете.

Примечание: Поля dns, email и ip используются для определения Альтернативных Имен Субъекта (SAN).

Параметр	Описание	Тип	Обязательно	По умолчанию
name	Имя сертификата. Можно использовать полный путь для выбора директории, где будут храниться файлы.	str	да	-
ca	Удостоверяющий Центр (CA), который выдает сертификат. См. CAs and Providers.	str	да	-
dns	Домен (или список доменов), который будет включен в сертификат. Также может предоставить значение по умолчанию для common_name.	str или список	нет	-
email	Электронная почта (или список электронных адресов), который будет включен в сертификат.	str или список	нет	-
ip	IP-адрес или список IP-адресов, который будет включен в сертификат. IP могут быть IPv4, IPv6 или оба. Также может предоставить значение по умолчанию для common_name.	str или список	нет	-
auto_renew	Указывает, должен ли сертификат автоматически обновляться до истечения срока действия.	bool	нет	да
owner	Имя пользователя (или идентификатор пользователя) для файлов сертификата и ключа.	str	нет	Пользователь, запускающий Ansible
group	Имя группы (или идентификатор группы) для файлов сертификата и ключа.	str	нет	Группа, запускающая Ansible
mode	Разрешения файловой системы для файлов сертификата и ключа.	raw	нет	-
key_size	Генерация ключей с определенным размером в битах.	int	нет	2048 - См. key_size
common_name	Общее имя, запрашиваемое для субъекта сертификата.	str	нет	См. common_name
country	Код страны, запрашиваемый для субъекта сертификата.	str	нет	-
state	Штат, запрашиваемый для субъекта сертификата.	str	нет	-
locality	Населенный пункт, запрашиваемый для субъекта сертификата (обычно город).	str	нет	-
organization	Организация, запрашиваемая для субъекта сертификата.	str	нет	-
organizational_unit	Организационная единица, запрашиваемая для субъекта сертификата.	str	нет	-
contact_email	Контактный электронный адрес, запрашиваемый для субъекта сертификата.	str	нет	-
key_usage	Разрешенные ключевые функции для сертификата. Для допустимых значений см. key_usage.	список	нет	См. key_usage
extended_key_usage	Атрибуты расширенного использования ключа, которые должны присутствовать в запросе на сертификат.	список	нет	См. extended_key_usage
run_before	Команда, которая должна выполниться перед сохранением сертификата. См. run hooks.	str	нет	-
run_after	Команда, которая должна выполниться после сохранения сертификата. См. run hooks.	str	нет	-
principal	Кераberos-принципал.	str	нет	-
provider	Основной метод, используемый для запроса и управления сертификатом.	str	нет	Различается для CA

common_name

Если common_name не установлен, роль попытается использовать первое значение dns или ip соответственно в качестве значения по умолчанию. Если dns и ip также не установлены, common_name не будет включен в сертификат.

key_size

Рекомендуемые минимальные значения для размера ключа сертификата от разных организаций со временем варьируются. В попытке предоставить безопасные настройки значение по умолчанию для key_size будет постепенно увеличиваться.

Если вы хотите, чтобы ваши сертификаты всегда имели одинаковый key_size при обновлении, установите эту переменную на нужное значение.

key_usage

Допустимые значения для key_usage:

digitalSignature
nonRepudiation
keyEncipherment
dataEncipherment
keyAgreement
keyCertSign
cRLSign
encipherOnly
decipherOnly

По умолчанию для key_usage установлены следующие значения:

digitalSignature
keyEncipherment

extended_key_usage

Любой допустимый oid может использоваться для установки одного или нескольких extended_key_usage. Кроме того, существует также список известных алиасов, которые будут распознаны ролью:

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

Если extended_key_usage не установлен, роль по умолчанию будет использовать:

id-kp-serverAuth
id-kp-clientAuth

run hooks

Иногда вам нужно выполнить команду прямо перед обновлением сертификата и другую команду сразу после. Для этого используйте run_before и run_after.

Значение, указанное для run_before и run_after, будет оформлено и сохранено в файлы shell-скриптов, которые позже будут выполнены поставщиком.

CAs и Поставщики

CA	Поставщики	Описание CA	Требования
self-sign	certmonger*	Выдача самоподписанных сертификатов от локального CA.
ipa	certmonger*	Выдача сертификатов с использованием FreeIPA CA.	Хост должен быть зарегистрирован на сервере FreeIPA.

* Поставщик по умолчанию.

CA представляет собой сертификаты CA, которые будут использоваться для выдачи и подписи запрашиваемого сертификата. Поставщик представляет собой метод, используемый для отправки запроса на сертификат в CA, а затем получения подписанного сертификата.

Если пользователь выбирает CA self-sign с certmonger в качестве поставщика и позже решает изменить поставщика на openssl, сертификаты CA, используемые в обоих случаях, должны быть одинаковыми. Обратите внимание, что openssl еще не поддерживается как поставщик и приведен здесь только в качестве примера.

Certmonger и SELinux

Если SELinux включен, служба certmonger может только записывать или редактировать файлы в директориях, где присутствует контекст cert_t.

Дополнительно, если скрипты, выполняемые параметрами run_before и run_after, нуждаются в записи или редактировании файлов, эти скрипты также требуют наличия контекста cert_t перед выполнением роли.

Вы можете использовать системную роль selinux для управления контекстами SELinux.

Для получения дополнительной информации о требованиях к certmonger и SELinux, смотрите certmonger_selinux(8) man pages.

Примеры

Выдача самоподписанного сертификата

Выдача сертификата для *.example.com и размещение его в стандартной директории для дистрибутива.

---
- hosts: webserver

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

  roles:
    - linux-system-roles.certificate

Вы можете найти директории для каждого дистрибутива в следующих местах:

Debian/Ubuntu:
- Сертификаты: /etc/ssl/localcerts/certs/
- Ключи: /etc/ssl/localcerts/private/
RHEL/CentOS/Fedora:
- Сертификаты: /etc/pki/tls/certs/
- Ключи: /etc/pki/tls/private/

Выбор места для размещения сертификатов

Выдача сертификата и ключа, и размещение их в указанном месте. Пример ниже создает файл сертификата в /another/path/mycert.crt и файл ключа в /another/path/mycert.key.

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

  roles:
    - linux-system-roles.certificate

Выдача сертификатов с несколькими DNS, IP и Email

---
- 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

Установка общих параметров субъекта

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

Установка размера ключа сертификата

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

Установка "Использование ключа" и "Расширенное использование ключа" (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

Не ждать выдачи сертификата

Выдача сертификата может занять несколько минут в зависимости от CA. По этой причине также возможно запросить сертификат, но не ждать его.

Эта конфигурация влияет на все сертификаты: если certificate_wait установлен в no, роль не ожидает выдачи любого сертификата.

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

Установка принципала

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

  roles:
    - linux-system-roles.certificate

Установка сертификата без автоматического обновления

По умолчанию сертификаты, сгенерированные ролью, установлены для автоматического обновления. Чтобы отключить это поведение, установите auto_renew: no.

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

  roles:
    - linux-system-roles.certificate

Использование FreeIPA для выдачи сертификата

Если ваш хост зарегистрирован на сервере FreeIPA, вы также можете использовать его CA для выдачи вашего сертификата. Для этого установите ca: ipa.

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

  roles:
    - linux-system-roles.certificate

Выполнение команды до или после выдачи сертификата

Иногда вам нужно выполнить команду прямо перед выдачей сертификата и другую команду сразу после. Для этого используйте run_before и 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

Установка владельца и группы сертификата

Если вы используете сертификат для службы, например httpd, вам нужно установить владельца и группу, которые будут владеть сертификатом. В следующем примере владелец и группа установлены на httpd.

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

  roles:
    - linux-system-roles.certificate