community.crypto.x509_crl 模块 – 生成证书吊销列表 (CRL)

注意

此模块是 community.crypto 集合（版本 2.22.3）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install community.crypto。您需要进一步的要求才能使用此模块，请参阅 要求了解详细信息。

要在 playbook 中使用它，请指定： community.crypto.x509_crl。

community.crypto 1.0.0 中的新增功能

概要

• 此模块允许您（重新）生成或更新证书吊销列表 (CRL)。

• 吊销列表中的证书可以通过序列号和（可选的）其颁发者指定，也可以通过 PEM 格式的证书文件路径指定。

要求

以下要求需要在执行此模块的主机上满足。

• 如果 name_encoding 设置为除 ignore 之外的其他值，则需要安装 idna Python 库。

• cryptography >= 1.2

参数

参数	注释
attributes 别名: attr 字符串	生成的 filesystem 对象应具有的属性。 要获取支持的标志，请查看目标系统上 *chattr* 的手册页。 此字符串应包含与 *lsattr* 显示的顺序相同的属性。 默认情况下，假定使用 = 运算符，否则需要在字符串中包含 + 或 - 运算符。
backup 布尔值	创建一个包含时间戳的备份文件，以便您可以在意外地用新文件覆盖原始 CRL 时恢复它。 选择 false ← (默认) true
crl_mode 字符串 在 community.crypto 2.13.0 中添加	定义如何处理现有 CRL 的条目。 如果设置为 generate，则确保 CRL 具有 revoked_certificates 中指定的已吊销证书的确切集合。 如果设置为 update，则确保 CRL 包含 revoked_certificates 中的已吊销证书，但也可能包含其他已吊销证书。如果 CRL 文件已存在，则现有 CRL 中的所有条目也将包含在新 CRL 中。使用 update 时，您可能会对将 ignore_timestamps 设置为 true 感兴趣。 默认值为 generate。 此参数在 community.crypto 2.13.0 之前被称为 mode。它已重命名以避免与用于设置 CRL 文件访问模式的常见 mode 参数冲突。 选择 "generate" "update"
digest 字符串	签署 CRL 时要使用的摘要算法。 默认值: "sha256"
force 布尔值	是否应强制重新生成 CRL。 选择 false ← (默认) true
format 字符串	CRL 文件应采用 PEM 还是 DER 格式。 如果现有 CRL 文件与除 format 之外的所有内容都匹配，则会将其转换为正确的格式，而不是重新生成。 选择 "pem" ← (默认) "der"
group 字符串	应该拥有 filesystem 对象的组的名称，就像输入到 *chown* 一样。 如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留先前的所有权。
ignore_timestamps 布尔值	是否应忽略时间戳 last_update、 next_update 和 revoked_certificates[].revocation_date 以进行幂等性检查。时间戳 revoked_certificates[].invalidity_date 永远不会被忽略。 将此与这些值的相对时间戳结合使用，以实现幂等性。 选择 false ← (默认) true
issuer 字典	将出现在 CRL 的颁发者名称字段中的键/值对。 如果需要使用相同的键指定多个值，请使用列表作为值。 如果组件的顺序很重要，请使用 issuer_ordered。 如果 state 为 present，则需要 issuer 和 issuer_ordered 中的一个。 与 issuer_ordered 互斥。
issuer_ordered 列表 / 元素=字典 在 community.crypto 2.0.0 中添加	字典的列表，其中每个字典必须包含一个键/值对。此键/值对将出现在 CRL 的颁发者名称字段中。 如果想要连续使用相同的键指定多个值，可以使用列表作为值。 如果 state 为 present，则需要 issuer 和 issuer_ordered 中的一个。 与 issuer 互斥。
last_update 字符串	可以信任此 CRL 的起始时间点。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC 时间。 有效格式为 [+-]timespec | ASN.1 TIME，其中 timespec 可以是一个整数 + [w | d | h | m | s] （例如 +32w1d2h）。 请注意，如果使用相对时间，则此模块不是幂等的，除非 ignore_timestamps 设置为 true。 默认值： "+0s"
mode 字符串	此参数已重命名为 crl_mode。旧名称 mode 现在已弃用，将在 community.crypto 3.0.0 中删除。请将此参数的使用替换为 crl_mode。 请注意，从 community.crypto 3.0.0 开始，mode 将用于 CRL 文件的模式。 选择 "generate" "update"
name_encoding 字符串	如何在返回值中编码名称（DNS 名称、URI、电子邮件地址）。 ignore 将使用后端返回的编码。 idna 会将域名所有标签转换为 IDNA 编码。将优先选择 IDNA2008，如果 IDNA2008 编码失败，则将使用 IDNA2003。 unicode 会将域名所有标签转换为 Unicode。将优先选择 IDNA2008，如果 IDNA2008 解码失败，则将使用 IDNA2003。 请注意，idna 和 unicode 需要安装 idna Python 库。 选择 "ignore" ← (默认) "idna" "unicode"
next_update 字符串	此 issuer 预计发布另一个 CRL 的最晚时间点。许多客户端会将 CRL 在 next_update 发生后视为已过期。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC 时间。 有效格式为 [+-]timespec | ASN.1 TIME，其中 timespec 可以是一个整数 + [w | d | h | m | s] （例如 +32w1d2h）。 请注意，如果使用相对时间，则此模块不是幂等的，除非 ignore_timestamps 设置为 true。 如果 state 为 present，则为必需项。
owner 字符串	应该拥有文件系统对象的用户名称，就像被馈送到 chown 一样。 如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下，它可以保留之前的属主。 指定数字用户名将被视为用户 ID 而不是用户名。请避免使用数字用户名，以避免混淆。
path 路径 / 必需	应创建或已存在生成的 CRL 文件的远程绝对路径。
privatekey_content 字符串	CA 私钥的内容，用于签署 CRL。 如果 state 为 present，则必须指定 privatekey_path 或 privatekey_content 中的一个，但不能同时指定两者。
privatekey_passphrase 字符串	privatekey_path 的密码。 如果私钥受密码保护，则这是必需的。
privatekey_path path	用于签署 CRL 的 CA 私钥的路径。 如果 state 为 present，则必须指定 privatekey_path 或 privatekey_content 中的一个，但不能同时指定两者。
return_content 布尔值	如果设置为 true，将以 crl 形式返回（当前或生成的）CRL 的内容。 选择 false ← (默认) true
revoked_certificates 列表 / 元素=字典	要吊销的证书列表。 如果 state 为 present，则为必需项。
content 字符串	PEM 格式的证书内容。 将从证书中提取序列号和颁发者。 与 revoked_certificates[].path 和 revoked_certificates[].serial_number 互斥。必须指定这三个选项之一。
invalidity_date 字符串	已知/怀疑私钥被泄露或证书以其他方式失效的时间点。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC 时间。 有效格式为 [+-]timespec | ASN.1 TIME，其中 timespec 可以是一个整数 + [w | d | h | m | s] （例如 +32w1d2h）。 请注意，如果使用相对时间，则此模块不是幂等的。当 ignore_timestamps 设置为 true 时，这种情况不会改变。
invalidity_date_critical 布尔值	失效日期扩展是否应为关键。 选择 false ← (默认) true
issuer 列表 / 元素=字符串	证书的颁发者。 示例：DNS:ca.example.org
issuer_critical 布尔值	证书颁发者扩展是否应为关键。 选择 false ← (默认) true
path path	PEM 格式的证书路径。 将从证书中提取序列号和颁发者。 与 revoked_certificates[].content 和 revoked_certificates[].serial_number 互斥。这三个选项中必须指定一个。
reason 字符串	吊销原因扩展的值。 选择 "unspecified" "key_compromise" "ca_compromise" "affiliation_changed" "superseded" "cessation_of_operation" "certificate_hold" "privilege_withdrawn" "aa_compromise" "remove_from_crl"
reason_critical 布尔值	吊销原因扩展是否应为关键。 选择 false ← (默认) true
revocation_date 字符串	证书被吊销的时间点。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC 时间。 有效格式为 [+-]timespec | ASN.1 TIME，其中 timespec 可以是一个整数 + [w | d | h | m | s] （例如 +32w1d2h）。 请注意，如果使用相对时间，则此模块不是幂等的，除非 ignore_timestamps 设置为 true。 默认值： "+0s"
serial_number any	证书的序列号。 与 revoked_certificates[].path 和 revoked_certificates[].content 互斥。这三个选项中必须指定一个。 此选项接受整数或十六进制字节字符串，具体取决于 serial_numbers 的值。 如果 serial_numbers=integer，则必须提供诸如 66223 之类的整数。 如果 serial_numbers=hex-octets，则必须提供诸如 01:02:AF 之类的字符串。 您可以使用过滤器 community.crypto.parse_serial 和 community.crypto.to_serial 来转换这两种表示形式。
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为 range。 当设置为 _default 时，如果可用，它将使用策略的 level 部分。
serial_numbers 字符串 在 community.crypto 2.18.0 中添加	此选项确定将接受 revoked_certificates[].serial_number 的哪些值。 如果设置为 integer （默认值），则序列号被假定为整数，例如 66223。（此示例值等效于十六进制字节字符串 01:02:AF。） 如果设置为 hex-octets，则序列号被假定为以冒号分隔的十六进制字节字符串，例如 01:02:AF。（此示例值等效于整数 66223。） 选择 "integer" ← (默认) "hex-octets"
serole 字符串	SELinux 文件系统对象上下文的角色部分。 当设置为 _default 时，如果可用，它将使用策略的 role 部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 当设置为 _default 时，如果可用，它将使用策略的 type 部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用 system 策略（如果适用）。 当设置为 _default 时，如果可用，它将使用策略的 user 部分。
state 字符串	CRL 文件是否应该存在，如果状态与声明的状态不同，则采取操作。 选择 "absent" "present" ← (默认)
unsafe_writes 布尔值	影响何时使用原子操作以防止数据损坏或从目标文件系统对象读取不一致的数据。 默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统配置或损坏的方式会阻止这种情况。一个示例是 docker 挂载的文件系统对象，这些对象无法从容器内部进行原子更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到更新文件系统对象的不安全方法（但是，它不会强制 Ansible 执行不安全的写入）。 重要提示！不安全的写入会受到竞争条件的影响，并可能导致数据损坏。 选择 false ← (默认) true

属性

属性	支持	描述
check_mode	支持: 完全	可以在 check_mode 中运行，并在不修改目标的情况下返回已更改状态预测。
diff_mode	支持: 完全	当处于 diff 模式时，将返回有关已更改的内容（或可能需要在 check_mode 中更改的内容）的详细信息。
safe_file_operations	支持: 完全	使用 Ansible 的严格文件操作函数来确保正确的权限并避免数据损坏。

注释

注意

• 所有 ASN.1 TIME 值都应按照 YYYYMMDDHHMMSSZ 模式指定。

• 指定日期应为 UTC。分钟和秒是强制性的。

另请参阅

另请参阅

community.crypto.parse_serial 过滤器插件

将以冒号分隔的十六进制数字列表形式的序列号转换为整数。

community.crypto.to_serial 过滤器插件

将整数转换为以冒号分隔的十六进制数字列表。

示例

- name: Generate a CRL
  community.crypto.x509_crl:
    path: /etc/ssl/my-ca.crl
    privatekey_path: /etc/ssl/private/my-ca.pem
    issuer:
      CN: My CA
    last_update: "+0s"
    next_update: "+7d"
    revoked_certificates:
      - serial_number: 1234
        revocation_date: 20190331202428Z
        issuer:
          CN: My CA
      - serial_number: 2345
        revocation_date: 20191013152910Z
        reason: affiliation_changed
        invalidity_date: 20191001000000Z
      - path: /etc/ssl/crt/revoked-cert.pem
        revocation_date: 20191010010203Z

返回值

常见的返回值在此处 记录，以下是此模块独有的字段

键	描述
backup_file 字符串	创建的备份文件的名称。 已返回: 已更改，并且如果 backup 为 true 示例: "/path/to/my-ca.crl.2019-03-09@11:22~"
crl 字符串	（当前或生成的）CRL 的内容。 如果 format 为 pem，则将为 CRL 本身，如果 format 为 der，则为 CRL 的 Base64。 已返回: 如果 state 为 present 并且 return_content 为 true
digest 字符串	用于签署 CRL 的签名算法。 已返回: 成功 示例: "sha256WithRSAEncryption"
filename 字符串	生成的 CRL 的路径。 已返回: 已更改或成功 示例: "/path/to/my-ca.crl"
format 字符串	CRL 是 PEM 格式 (pem) 还是 DER 格式 (der)。 已返回: 成功 只能返回 "pem" "der" 示例: "pem"
issuer 字典	CRL 的颁发者。 请注意，对于重复的值，只会返回最后一个值。 有关如何处理 IDN，请参阅 name_encoding。 已返回: 成功 示例: {"commonName": "ca.example.com", "organizationName": "Ansible"}
issuer_ordered list / elements=list	CRL 的颁发者，作为元组的有序列表。 已返回: 成功 示例: [["organizationName", "Ansible"], [{"commonName": "ca.example.com"}]]
last_update 字符串	此 CRL 可以被信任为 ASN.1 TIME 的时间点。 已返回: 成功 示例: "20190413202428Z"
next_update 字符串	将颁发新的 CRL 并且客户端必须检查它的时间点，作为 ASN.1 TIME。 已返回: 成功 示例: "20190413202428Z"
privatekey 字符串	私有 CA 密钥的路径。 已返回: 已更改或成功 示例： "/path/to/my-ca.pem"
revoked_certificates 列表 / 元素=字典	要吊销的证书列表。 已返回: 成功
invalidity_date 字符串	以 ASN.1 TIME 格式表示的，已知/怀疑私钥被泄露或证书失效的时间点。 已返回: 成功 示例: "20190413202428Z"
invalidity_date_critical 布尔值	失效日期扩展是否为关键。 已返回: 成功 示例： false
issuer 列表 / 元素=字符串	证书的颁发者。 有关如何处理 IDN，请参阅 name_encoding。 已返回: 成功 示例： ["DNS:ca.example.org"]
issuer_critical 布尔值	证书颁发者扩展是否为关键。 已返回: 成功 示例： false
reason 字符串	吊销原因扩展的值。 已返回: 成功 只能返回 "unspecified" "key_compromise" "ca_compromise" "affiliation_changed" "superseded" "cessation_of_operation" "certificate_hold" "privilege_withdrawn" "aa_compromise" "remove_from_crl" 示例： "key_compromise"
reason_critical 布尔值	吊销原因扩展是否为关键。 已返回: 成功 示例： false
revocation_date 字符串	以 ASN.1 TIME 格式表示的证书被吊销的时间点。 已返回: 成功 示例: "20190413202428Z"
serial_number 整数	证书的序列号。 此返回值是一个整数。如果您需要以冒号分隔的十六进制字符串形式表示序列号，例如 11:22:33，您需要使用 community.crypto.to_serial 将其转换为该形式。 已返回: 成功 示例： 1234

作者

• Felix Fontein (@felixfontein)

集合链接

• 问题跟踪器
• 仓库（源代码）
• 寻求帮助 (crypto)
• 寻求帮助 (ACME)
• 提交错误报告
• 请求新功能
• 沟通