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 覆盖它后找回原始 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 字符串	应该拥有文件系统对象的组的名称，如同提供给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的绝对最新时间点。一旦发生next_update，许多客户端将CRL视为已过期。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为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 字符串	用于签署CRL的CA私钥的内容。 如果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 字符串	吊销原因扩展的值。 选项 "未指定" "密钥泄露" "CA 泄露" "关联更改" "已取代" "停止运营" "证书暂停" "权限撤销" "AA 泄露" "从 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 任意	证书的序列号。 与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 文件是否应该存在，如果状态与声明的状态不同，则采取行动。 选项 "不存在" "存在" ← (默认)
unsafe_writes 布尔值	影响何时使用原子操作来防止目标文件系统对象的数据损坏或不一致读取。 默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致读取，但有时系统配置或损坏的方式会阻止这种情况。一个例子是 docker 挂载的文件系统对象，无法从容器内部以原子方式更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全的写入）。 重要！不安全的写入容易出现竞争条件，并可能导致数据损坏。 选项 false ← (默认) true

属性

属性	支持	描述
check_mode	支持：完全支持	可以在check_mode下运行，并在不修改目标的情况下返回更改状态预测。
diff_mode	支持：完全支持	在差异模式下，将返回有关已更改内容（或可能需要在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 列表 / 元素=列表	CRL 的发行者，作为有序元组列表。 返回值：成功 示例：[["organizationName", "Ansible"], [{"commonName": "ca.example.com"}]]
last_update 字符串	从此 CRL 可以被信任的时间点（作为 ASN.1 TIME）。 返回值：成功 示例："20190413202428Z"
next_update 字符串	新 CRL 将发出的时间点，以及客户端必须检查它的时间点，以 ASN.1 TIME 格式表示。 返回值：成功 示例："20190413202428Z"
私钥 字符串	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 字符串	吊销原因扩展的值。 返回值：成功 只能返回 "未指定" "密钥泄露" "CA 泄露" "关联更改" "已取代" "停止运营" "证书暂停" "权限撤销" "AA 泄露" "从 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)

资源链接

• 问题追踪
• 代码仓库
• 寻求帮助 (加密)
• 寻求帮助 (ACME)
• 提交错误报告
• 提出功能请求
• 沟通