community.crypto.openssl_csr 模块 – 生成 OpenSSL 证书签名请求 (CSR)

注意

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

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

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

要在 Playbook 中使用它，请指定：community.crypto.openssl_csr。

概要

• 请注意，如果现有的 CSR 与模块的选项不匹配，或者似乎已损坏，则该模块会重新生成它。如果您担心这会覆盖您现有的 CSR，请考虑使用 backup 选项。

• 此模块允许 (重新) 生成 OpenSSL 证书签名请求。

• 此模块支持 subjectAltName、keyUsage、extendedKeyUsage、basicConstraints 和 OCSP Must Staple 扩展。

要求

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

• cryptography >= 1.3

参数

参数	注释
attributes 别名：attr 字符串	生成的 文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上 chattr 的手册页。 此字符串应包含与 lsattr 显示的顺序相同的属性。 = 运算符假定为默认值，否则 + 或 - 运算符需要包含在字符串中。
authority_cert_issuer 列表 / 元素=字符串	将出现在证书签名请求的颁发机构证书颁发者字段中的名称。 值必须以它们的选项为前缀。（即，email、URI、DNS、RID、IP、dirName、otherName 以及特定于您的 CA 的选项） 示例：DNS:ca.example.org 如果指定了，则还必须指定 authority_cert_serial_number。 请注意，商业 CA 会忽略此值，分别使用它们自己选择的值。指定此选项对于自签名证书或用于自己的 CA 很有用。 请注意，仅当使用 cryptography 后端时才支持此选项！ 仅当指定了 authority_key_identifier、authority_cert_issuer 和 authority_cert_serial_number 中的至少一个时，才会添加 AuthorityKeyIdentifier 扩展。
authority_cert_serial_number 整数	颁发机构证书序列号。 如果指定了，则还必须指定 authority_cert_issuer。 请注意，仅当使用 cryptography 后端时才支持此选项！ 请注意，商业 CA 会忽略此值，分别使用它们自己选择的值。指定此选项对于自签名证书或用于自己的 CA 很有用。 仅当指定了 authority_key_identifier、authority_cert_issuer 和 authority_cert_serial_number 中的至少一个时，才会添加 AuthorityKeyIdentifier 扩展。 此选项接受一个 整数。如果要以冒号分隔的十六进制字符串（例如 11:22:33）的形式提供序列号，则需要使用 community.crypto.parse_serial 将它们转换为整数。
authority_key_identifier 字符串	颁发机构密钥标识符，以十六进制字符串表示，其中两个字节用冒号分隔。 示例：00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33 请注意，商业 CA 会忽略此值，分别使用它们自己选择的值。指定此选项对于自签名证书或用于自己的 CA 很有用。 请注意，仅当使用 cryptography 后端时才支持此选项！ 仅当指定了 authority_key_identifier、authority_cert_issuer 和 authority_cert_serial_number 中的至少一个时，才会添加 AuthorityKeyIdentifier 扩展。
backup 布尔值	创建一个包含时间戳的备份文件，这样如果您不小心用新的 CSR 覆盖了原始 CSR，则可以将其恢复。 选项 false ← (默认) true
basic_constraints 别名：basicConstraints 列表 / 元素=字符串	指示基本约束，例如证书是否为 CA。
basic_constraints_critical 别名：basicConstraints_critical 布尔值	basicConstraints 扩展是否应被视为关键。 选项 false ← (默认) true
common_name 别名：CN、commonName 字符串	证书签名请求主题的 commonName 字段。
country_name 别名：C、countryName 字符串	证书签名请求主题的 countryName 字段。
create_subject_key_identifier 布尔值	从公钥创建主题密钥标识符。 请注意，商业 CA 可以忽略该值，分别使用它们自己选择的值来代替。指定此选项对于自签名证书或用于自己的 CA 很有用。 请注意，仅当使用 cryptography 后端时才支持此选项！ 选项 false ← (默认) true
crl_distribution_points 列表 / 元素=字典 在 community.crypto 1.4.0 中添加	允许指定一个或多个 CRL 分发点。 仅受 cryptography 后端支持。
crl_issuer 列表 / 元素=字符串	有关 CRL 颁发者的信息。
full_name 列表 / 元素=字符串	描述如何检索 CRL。 与 crl_distribution_points[].relative_name 互斥。 示例：URI:https://ca.example.com/revocations.crl。
reasons 列表 / 元素=字符串	执行吊销检查时，此分发点可用于的原因列表。 选项 "key_compromise" "ca_compromise" "affiliation_changed" "superseded" "cessation_of_operation" "certificate_hold" "privilege_withdrawn" "aa_compromise"
relative_name 列表 / 元素=字符串	描述如何相对于 CRL 颁发者检索 CRL。 与 crl_distribution_points[].full_name 互斥。 示例：/CN=example.com。 仅当安装了 cryptography >= 1.6 时才能使用。
digest 字符串	使用私钥签署证书签名请求时使用的摘要。 默认值： "sha256"
email_address 别名：E，emailAddress 字符串	证书签名请求主题的 emailAddress 字段。
extended_key_usage 别名：extKeyUsage，extendedKeyUsage 列表 / 元素=字符串	对公钥可用于的允许目的的额外限制（例如客户端身份验证，服务器身份验证）。
extended_key_usage_critical 别名：extKeyUsage_critical，extendedKeyUsage_critical 布尔值	是否应将 extKeyUsage 扩展视为关键。 选项 false ← (默认) true
force 布尔值	是否应由此 ansible 模块强制重新生成证书签名请求。 选项 false ← (默认) true
group 字符串	应该拥有文件系统对象的用户组名称，就像传递给 chown 一样。 如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下它可以保留以前的所有权。
key_usage 别名：keyUsage 列表 / 元素=字符串	这定义了证书中包含的密钥的目的（例如加密，签名，证书签名）。
key_usage_critical 别名：keyUsage_critical 布尔值	是否应将 keyUsage 扩展视为关键。 选项 false ← (默认) true
locality_name 别名：L，localityName 字符串	证书签名请求主题的 localityName 字段。
mode 任何	生成的文件系统对象应具有的权限。 对于那些习惯于 /usr/bin/chmod 的人，请记住模式实际上是八进制数字。您必须给 Ansible 足够的信息来正确解析它们。为了获得一致的结果，请引用八进制数字（例如，'644' 或 '1777'），以便 Ansible 接收到字符串并可以自行将字符串转换为数字。添加前导零（例如，0755）有时有效，但在循环和其他某些情况下可能会失败。 如果未遵循这些规则，则向 Ansible 提供数字最终会得到一个十进制数字，这将导致意外的结果。 从 Ansible 1.8 开始，该模式可以指定为符号模式（例如，u+rwx 或 u=rw,g=r,o=r）。 如果未指定 mode 并且目标文件系统对象不存在，则在为新创建的文件系统对象设置模式时，将使用系统上的默认 umask。 如果未指定 mode 并且目标文件系统对象存在，则将使用现有文件系统对象的模式。 指定 mode 是确保使用正确的权限创建文件系统对象的最佳方法。有关更多详细信息，请参见 CVE-2020-1736。
name_constraints_critical 布尔值 在 community.crypto 1.1.0 中添加	是否应将名称约束扩展视为关键。 选项 false ← (默认) true
name_constraints_excluded 列表 / 元素=字符串 在 community.crypto 1.1.0 中添加	对于 CA 证书，这指定了一个标识符列表，这些标识符描述了此 CA 不允许为其颁发证书的名称子树。 值必须以其选项为前缀。（即，email，URI，DNS，RID，IP，dirName，otherName 以及特定于您的 CA 的那些）。
name_constraints_permitted 列表 / 元素=字符串 在 community.crypto 1.1.0 中添加	对于 CA 证书，这指定了一个标识符列表，这些标识符描述了此 CA 允许为其颁发证书的名称子树。 值必须以其选项为前缀。（即，email，URI，DNS，RID，IP，dirName，otherName 以及特定于您的 CA 的那些）。
ocsp_must_staple 别名：ocspMustStaple 布尔值	指示证书应包含 OCSP Must Staple 扩展 (https://tools.ietf.org/html/rfc7633)。 选项 false ← (默认) true
ocsp_must_staple_critical 别名：ocspMustStaple_critical 布尔值	是否应将 OCSP Must Staple 扩展视为关键。 请注意，根据 RFC，此扩展不应标记为关键，因为不知道 OCSP Must Staple 的旧客户端必须拒绝此类证书（请参阅 https://tools.ietf.org/html/rfc7633#section-4）。 选项 false ← (默认) true
organization_name 别名：O，organizationName 字符串	证书签名请求主题的 organizationName 字段。
organizational_unit_name 别名：OU，organizationalUnitName 字符串	证书签名请求主题的 organizationalUnitName 字段。
owner 字符串	应该拥有文件系统对象的用户名，就像传递给 chown 一样。 如果未指定，它将使用当前用户，除非您是 root 用户，在这种情况下它可以保留以前的所有权。 指定数字用户名将被视为用户 ID，而不是用户名。避免使用数字用户名，以免混淆。
path 路径 / 必需	将写入生成的 OpenSSL 证书签名请求的文件名。
privatekey_content 字符串 在 community.crypto 1.0.0 中添加	用于签署证书签名请求的私钥内容。 如果 state 为 present，则必须指定 privatekey_path 或 privatekey_content，但不能同时指定两者。
privatekey_passphrase 字符串	私钥的密码。 如果私钥受密码保护，则这是必需的。
privatekey_path path	用于签署证书签名请求的私钥路径。 如果 state 为 present，则必须指定 privatekey_path 或 privatekey_content，但不能同时指定两者。
return_content 布尔值 在 community.crypto 1.0.0 中添加	如果设置为 true，将返回（当前或生成的）CSR 的内容作为 csr。 选项 false ← (默认) true
select_crypto_backend 字符串	确定要使用的加密后端。 默认选择是 auto，如果可用，它会尝试使用 cryptography。 如果设置为 cryptography，将尝试使用 cryptography 库。 选项 "auto" ← (默认) "cryptography"
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为 range。 如果设置为 _default，它将使用策略的 level 部分（如果可用）。
serole 字符串	SELinux 文件系统对象上下文的角色部分。 如果设置为 _default，它将使用策略的 role 部分（如果可用）。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 如果设置为 _default，它将使用策略的 type 部分（如果可用）。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用 system 策略（如果适用）。 如果设置为 _default，它将使用策略的 user 部分（如果可用）。
state 字符串	证书签名请求是否存在，如果状态与声明的不符，则采取相应操作。 选项 “不存在” "存在" ← (默认)
州/省名称 别名: ST, stateOrProvinceName 字符串	证书签名请求主题的州/省名称字段。
主题 字典	将出现在证书签名请求主题名称字段中的键/值对。 如果需要使用相同的键指定多个值，请使用列表作为值。 如果组件的顺序很重要，请使用 subject_ordered。 与 subject_ordered 互斥。
主题备用名称 别名: subjectAltName 列表 / 元素=字符串	要附加到证书签名请求的主题备用名称 (SAN) 扩展。 值必须以其选项为前缀。(这些是 email, URI, DNS, RID, IP, dirName, otherName, 以及特定于你的 CA 的选项)。 请注意，如果没有指定 SAN，但指定了公用名称，则该公用名称将添加为 SAN，除非 use_common_name_for_san 设置为 false。 更多信息请访问 https://tools.ietf.org/html/rfc5280#section-4.2.1.6。
主题备用名称是否关键 别名: subjectAltName_critical 布尔值	主题备用名称扩展是否应被视为关键。 选项 false ← (默认) true
主题密钥标识符 字符串	主题密钥标识符，格式为十六进制字符串，其中两个字节用冒号分隔。 示例：00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33 请注意，商业 CA 会忽略此值，分别使用它们自己选择的值。指定此选项对于自签名证书或用于自己的 CA 很有用。 请注意，仅当 create_subject_key_identifier 为 false 时才能使用此选项。 请注意，仅当使用 cryptography 后端时才支持此选项！
主题排序 列表 / 元素=字典 在 community.crypto 2.0.0 中添加	字典列表，每个字典必须包含一个键/值对。此键/值对将出现在证书签名请求的主题名称字段中。 如果希望在一行中指定具有相同键的多个值，可以使用列表作为值。 与 subject 以及任何其他主题字段选项互斥，例如 country_name, state_or_province_name, locality_name, organization_name, organizational_unit_name, common_name 或 email_address。
不安全写入 布尔值	影响何时使用原子操作以防止数据损坏或从目标文件系统对象读取不一致的数据。 默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统的配置方式或只是存在缺陷，会阻止这种情况发生。一个例子是 docker 挂载的文件系统对象，这些对象无法从容器内部原子更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全写入）。 重要提示！不安全写入会受到竞争条件的影响，并可能导致数据损坏。 选项 false ← (默认) true
使用公用名称作为 SAN 别名: useCommonNameForSAN 布尔值	如果设置为 true，如果未指定 SAN，则该模块将用 DNS: 前缀填充 subject_alt_name 的公用名称。 选项 false true ← (默认)
版本 整数	证书签名请求的版本。 根据 RFC 2986，唯一允许的值是 1。 自 community.crypto 2.0.0 起，此选项不再接受不支持的值。 选项 1 ← (默认)

属性

属性	支持	描述
检查模式	支持: 完整	可以在 check_mode 中运行，并返回已更改的状态预测，而无需修改目标。
差异模式	支持: 完整	在差异模式下，将返回有关已更改的内容（或可能需要在 check_mode 中更改的内容）的详细信息。
安全文件操作	支持: 完整	使用 Ansible 的严格文件操作功能，以确保适当的权限并避免数据损坏。

注释

注意

• 如果证书签名请求已存在，则会检查 subjectAltName、keyUsage、extendedKeyUsage 和 basicConstraints 是否仅包含请求的值，OCSP 必须钉住是否按要求设置，以及该请求是否由给定的私钥签名。

另请参阅

另请参阅

community.crypto.openssl_csr_pipe

生成 OpenSSL 证书签名请求 (CSR)。

community.crypto.x509_certificate

生成和/或检查 OpenSSL 证书。

community.crypto.x509_certificate_pipe

生成和/或检查 OpenSSL 证书。

community.crypto.openssl_dhparam

生成 OpenSSL Diffie-Hellman 参数。

community.crypto.openssl_pkcs12

生成 OpenSSL PKCS#12 存档。

community.crypto.openssl_privatekey

生成 OpenSSL 私钥。

community.crypto.openssl_privatekey_pipe

生成 OpenSSL 私钥，无需磁盘访问。

community.crypto.openssl_publickey

从其私钥生成 OpenSSL 公钥。

community.crypto.openssl_csr_info

提供 OpenSSL 证书签名请求 (CSR) 的信息。

community.crypto.parse_serial 过滤器插件

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

示例

- name: Generate an OpenSSL Certificate Signing Request
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    common_name: www.ansible.com

- name: Generate an OpenSSL Certificate Signing Request with an inline key
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_content: "{{ private_key_content }}"
    common_name: www.ansible.com

- name: Generate an OpenSSL Certificate Signing Request with a passphrase protected private key
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    privatekey_passphrase: ansible
    common_name: www.ansible.com

- name: Generate an OpenSSL Certificate Signing Request with Subject information
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    country_name: FR
    organization_name: Ansible
    email_address: [email protected]
    common_name: www.ansible.com

- name: Generate an OpenSSL Certificate Signing Request with subjectAltName extension
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    subject_alt_name: 'DNS:www.ansible.com,DNS:m.ansible.com'

- name: Generate an OpenSSL CSR with subjectAltName extension with dynamic list
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    subject_alt_name: "{{ item.value | map('regex_replace', '^', 'DNS:') | list }}"
  with_dict:
    dns_server:
    - www.ansible.com
    - m.ansible.com

- name: Force regenerate an OpenSSL Certificate Signing Request
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    force: true
    common_name: www.ansible.com

- name: Generate an OpenSSL Certificate Signing Request with special key usages
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    common_name: www.ansible.com
    key_usage:
      - digitalSignature
      - keyAgreement
    extended_key_usage:
      - clientAuth

- name: Generate an OpenSSL Certificate Signing Request with OCSP Must Staple
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    common_name: www.ansible.com
    ocsp_must_staple: true

- name: Generate an OpenSSL Certificate Signing Request for WinRM Certificate authentication
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/winrm.auth.csr
    privatekey_path: /etc/ssl/private/winrm.auth.pem
    common_name: username
    extended_key_usage:
    - clientAuth
    subject_alt_name: otherName:1.3.6.1.4.1.311.20.2.3;UTF8:username@localhost

- name: Generate an OpenSSL Certificate Signing Request with a CRL distribution point
  community.crypto.openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    common_name: www.ansible.com
    crl_distribution_points:
      - full_name:
          - "URI:https://ca.example.com/revocations.crl"
        crl_issuer:
          - "URI:https://ca.example.com/"
        reasons:
          - key_compromise
          - ca_compromise
          - cessation_of_operation

返回值

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

键	描述
备份文件 字符串	创建的备份文件的名称。 已返回: 如果 backup 为 true，则已更改 示例: "/path/to/www.ansible.com.csr.2019-03-09@11:22~"
基本约束 列表 / 元素=字符串	指示证书是否属于 CA 已返回: 已更改或成功 示例: ["CA:TRUE", "pathLenConstraint:0"]
csr 字符串 在 community.crypto 1.0.0 中添加	（当前或生成的）CSR 的内容。 已返回: 如果 state 为 present 且 return_content 为 true
扩展密钥用法 列表 / 元素=字符串	对公钥用途的额外限制 已返回: 已更改或成功 示例: ["clientAuth"]
文件名 字符串	生成的证书签名请求的路径 已返回: 已更改或成功 示例: "/etc/ssl/csr/www.ansible.com.csr"
密钥用法 列表 / 元素=字符串	可以使用公钥的用途 已返回: 已更改或成功 示例: ["digitalSignature", "keyAgreement"]
name_constraints_excluded 列表 / 元素=字符串 在 community.crypto 1.1.0 中添加	CA 不能为其签名证书的排除子树列表。 已返回: 已更改或成功 示例: ["email:.com"]
name_constraints_permitted 列表 / 元素=字符串 在 community.crypto 1.1.0 中添加	要为其签名证书的允许子树列表。 已返回: 已更改或成功 示例: ["email:.somedomain.com"]
ocsp_must_staple 布尔值	指示证书是否启用了 OCSP 必须钉住功能 已返回: 已更改或成功 示例: false
私钥 字符串	为生成 CSR 的 TLS/SSL 私钥的路径 如果私钥已在 privatekey_content 中提供，则将为 none。 已返回: 已更改或成功 示例: "/etc/ssl/private/ansible.com.pem"
主题 list / elements=list	附加到 CSR 的主题元组列表 已返回: 已更改或成功 示例: [["CN", "www.ansible.com"], ["O", "Ansible"]]
subjectAltName 列表 / 元素=字符串	此 CSR 有效的备用名称 已返回: 已更改或成功 示例: ["DNS:www.ansible.com", "DNS:m.ansible.com"]

作者

• Yanis Guenane (@Spredzy)

• Felix Fontein (@felixfontein)

集合链接

• 问题跟踪器
• 存储库 (源代码)
• 寻求帮助 (加密)
• 寻求帮助 (ACME)
• 提交错误报告
• 请求功能
• 交流