linux-system-roles.certificate

概述 版本 洞察

证书系统角色

ansible-lint.yml ansible-test.yml codeql.yml markdownlint.yml python-unit-test.yml tft.yml tft_citest_bad.yml woke.yml

管理 TLS/SSL 证书的发行和续期的角色。

Linux 系统角色用于发布和更新 SSL 证书。

基本用法：

---
- 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。 list 否 -

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 和 Providers。 str 是 -
dns 包含在证书中的域（或域列表）。也可以为 common_name提供默认值。 str 或 list 否 -
email 包含在证书中的电子邮件（或电子邮件列表）。 str 或 list 否 -
ip 包含在证书中的 IP（或 IP 列表）。IP 可以是 IPv4、IPv6 或两者。也可以为 common_name 提供默认值。 str 或 list 否 -
auto_renew 指示证书是否应在到期之前自动续期。 bool 否 是
owner 证书和密钥文件的用户名（或用户 ID）。 str 否 运行 Ansible 的用户
group 证书和密钥文件的组名（或组 ID）。 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。 list 否 见 key_usage
extended_key_usage 应在证书请求中出现的扩展密钥用法属性。 list 否 见 extended_key_usage
run_before 保存证书之前应该运行的命令。见 run hooks。 str 否 -
run_after 保存证书之后应该运行的命令。见 run hooks。 str 否 -
principal Kerberos 主体。 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 和 Providers

CA Providers CA 描述 要求
self-sign certmonger* 从本地 CA 发布自签名证书。
ipa certmonger* 使用 FreeIPA CA 发布证书。 主机需要注册到 FreeIPA 服务器。

* 默认提供者。

CA 表示将用于发行和签署请求证书的 CA 证书。提供者表示用于将证书请求发送给 CA 然后检索签名证书的方法。

如果用户选择 self-sign CA，并以 certmonger 作为提供者，随后决定将提供者更改为 openssl，则两种情况下使用的 CA 证书需要相同。请注意，openssl 仍然是 不受支持的 提供者，仅作为示例提到。

Certmonger 和 SELinux

如果启用 SELinux，certmonger 服务只能在存在 cert_t 上下文的目录中写入或编辑文件。

此外，如果 run_before 和 run_after 参数执行的脚本需要写入或编辑文件，这些脚本在角色执行之前也需要存在 cert_t 上下文。

您可以使用 selinux 系统角色来管理 SELinux 上下文。

有关 certmonger 和 SELinux 要求的更多信息，请参见 certmonger_selinux(8) man 页面。

示例

发布自签名证书

为 *.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 和电子邮件的证书

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

注意，您也可以使用 UID 和 GID，而不是用户名和组名。

兼容性

目前支持 CentOS 7+、RHEL 7+、Fedora。已在 Debian 10 中测试。

rpm-ostree

参见 README-ostree.md

许可证

MIT

作者信息

Sergio Oliveira Campos (@seocam)

关于项目

Role for managing TLS/SSL certificate issuance and renewal

role centos certificate certmonger el7 el8 el9 el10 fedora redhat rhel ssl system tls
安装
ansible-galaxy install linux-system-roles.certificate
GitHub 仓库
31 星标
22 分叉
9 未解决问题
许可证
mit
下载
7.6k
拥有者