community.crypto.ecs_certificate 模块 – 使用 Entrust Certificate Services (ECS) API 请求 SSL/TLS 证书

注意

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

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

要安装它，请使用： ansible-galaxy collection install community.crypto。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。

要在剧本中使用它，请指定： community.crypto.ecs_certificate。

概要

• 使用 Entrust Certificate Services (ECS) API 创建、重新颁发和续订证书。

• 需要 Entrust Certificate Services (ECS) API 的凭据。

• 为了请求证书，证书签名请求中使用的域名和组织必须已经在 ECS 系统中验证。此模块 _不_ 负责执行这些步骤。

要求

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

• PyYAML >= 3.11

• cryptography >= 1.6

参数

参数	注释
additional_emails 列表 / 元素=字符串	接收证书交付通知和过期通知的其他电子邮件地址列表。
backup 布尔值	是否应为 path 中的证书创建备份。 选项 false ← (默认) true
cert_expiry 字符串	证书应设置为过期的日期，采用符合 RFC3339 的日期或日期时间格式。例如，2020-02-23，2020-02-23T15:00:00.05Z。 cert_expiry 仅支持 request_type=new 或 request_type=renew 的请求。如果 request_type=reissue，cert_expiry 将用于第一次证书颁发，但后续颁发将与初始证书具有相同的过期日期。 重新颁发的证书将始终与原始证书具有相同的过期日期。 请注意，仅支持使用日期（日、月、年）来指定过期日期。如果您选择使用过期日期指定过期时间，则该时间将调整为东部标准时间 (EST)。这可能会意外地将您的过期日期更改为前一天。 仅适用于具有池化库存模型的帐户。 只能指定 cert_expiry 或 cert_lifetime 之一。
cert_lifetime 字符串	证书的有效期。 适用于具有非池化库存模型的帐户的所有证书。 cert_lifetime 仅支持 request_type=new 或 request_type=renew 的请求。如果 request_type=reissue，cert_lifetime 将用于第一次证书颁发，但后续颁发将与初始证书具有相同的过期日期。 适用于使用池化库存模型的帐户的证书类型为cert_type=CDS_INDIVIDUAL、CDS_GROUP、CDS_ENT_LITE、CDS_ENT_PRO或SMIME_ENT的证书。 P1Y 代表有效期为 1 年的证书。 P2Y 代表有效期为 2 年的证书。 P3Y 代表有效期为 3 年的证书。 只能指定 cert_expiry 或 cert_lifetime 之一。 选项 "P1Y" "P2Y" "P3Y"
cert_type 字符串	指定请求的证书类型。 如果证书正在重新颁发或续期，则忽略此参数，并使用初始证书的cert_type。 选项 "STANDARD_SSL" "ADVANTAGE_SSL" "UC_SSL" "EV_SSL" "WILDCARD_SSL" "PRIVATE_SSL" "PD_SSL" "CODE_SIGNING" "EV_CODE_SIGNING" "CDS_INDIVIDUAL" "CDS_GROUP" "CDS_ENT_LITE" "CDS_ENT_PRO" "SMIME_ENT"
client_id 整数	提交证书签名请求的客户端 ID。 如果未指定客户端 ID，则证书将以 ID 为 1 的主客户端的名义提交。 使用除主客户端以外的客户端时，不能指定org参数。 颁发的证书的主体可分辨名称中将包含由客户端表示的组织值。 默认值：1
csr 字符串	Base-64 编码的证书签名请求 (CSR)。csr 接受带有或不带有 PEM 格式的 Base-64 字符串。 当request_type=reissue 或 request_type=renew时，如果没有提供csr，则证书将使用与正在续期或重新颁发的证书相同的公钥生成。 如果指定了subject_alt_name，它将覆盖 CSR 中的主题备用名称。 如果指定了eku，它将覆盖 CSR 中的扩展密钥用法。 如果指定了ou，它将覆盖 CSR 主体可分辨名称中存在的组织单位“ou=”（如有）。 不会使用 CSR 中的组织“O=”字段。它将在颁发的证书中被org（如果存在）替换，如果不存在，则使用与client_id关联的组织。
ct_log 布尔值	为了符合浏览器要求，此证书可能会发布到证书透明度 (CT) 日志。这是一种最佳实践技术，可帮助域所有者监控为其域颁发的证书。请注意，并非所有证书都符合 CT 日志记录的条件。 如果未指定ct_log，则证书使用帐户默认设置。 如果指定了ct_log并且帐户设置允许，则ct_log将覆盖帐户默认设置。 如果ct_log设置为false，但帐户设置为“始终记录”，则证书生成将失败。 选项 false true
custom_fields 字典	要与证书请求和证书关联的自定义字段的映射。 仅当为您的帐户启用了自定义字段时才受支持。 指定的每个自定义字段都必须是您为帐户定义的自定义字段。
date1 字符串	自定义日期字段。
date2 字符串	自定义日期字段。
date3 字符串	自定义日期字段。
date4 字符串	自定义日期字段。
date5 字符串	自定义日期字段。
dropdown1 字符串	自定义下拉字段。
dropdown2 字符串	自定义下拉字段。
dropdown3 字符串	自定义下拉字段。
dropdown4 字符串	自定义下拉字段。
dropdown5 字符串	自定义下拉字段。
email1 字符串	自定义电子邮件字段。
email2 字符串	自定义电子邮件字段。
email3 字符串	自定义电子邮件字段。
email4 字符串	自定义电子邮件字段。
email5 字符串	自定义电子邮件字段。
number1 浮点数	自定义数字字段。
number2 浮点数	自定义数字字段。
number3 浮点数	自定义数字字段。
number4 浮点数	自定义数字字段。
number5 浮点数	自定义数字字段。
text1 字符串	自定义文本字段（最多 500 个字符）
text10 字符串	自定义文本字段（最多 500 个字符）
text11 字符串	自定义文本字段（最多 500 个字符）
text12 字符串	自定义文本字段（最多 500 个字符）
text13 字符串	自定义文本字段（最多 500 个字符）
text14 字符串	自定义文本字段（最多 500 个字符）
text15 字符串	自定义文本字段（最多 500 个字符）
text2 字符串	自定义文本字段（最多 500 个字符）
text3 字符串	自定义文本字段（最多 500 个字符）
text4 字符串	自定义文本字段（最多 500 个字符）
text5 字符串	自定义文本字段（最多 500 个字符）
text6 字符串	自定义文本字段（最多 500 个字符）
text7 字符串	自定义文本字段（最多 500 个字符）
text8 字符串	自定义文本字段（最多 500 个字符）
text9 字符串	自定义文本字段（最多 500 个字符）
eku 字符串	如果指定，则覆盖csr中的密钥用法。 选项 "SERVER_AUTH" "CLIENT_AUTH" "SERVER_AND_CLIENT_AUTH"
end_user_key_storage_agreement 布尔值	代码签名证书的最终用户必须在密码安全硬件上生成和存储此请求的私钥，才能符合 Entrust CSP 和订阅协议。如果请求类型为CODE_SIGNING或EV_CODE_SIGNING的证书，则当且仅当您承认将告知用户此要求时，必须将end_user_key_storage_agreement设置为 true。 仅适用于值为CODE_SIGNING和EV_CODE_SIGNING的cert_type。 选项 false true
entrust_api_client_cert_key_path 路径 / 必需	用于向 Entrust 证书服务 (ECS) API 进行身份验证的客户端证书密钥的路径。
entrust_api_client_cert_path 路径 / 必需	用于向 Entrust 证书服务 (ECS) API 进行身份验证的客户端证书的路径。
entrust_api_key 字符串 / 必需	用于向 Entrust 证书服务 (ECS) API 进行身份验证的密钥（密码）。
entrust_api_specification_path 路径	定义 Entrust 证书服务 (ECS) API 配置的规范文件的路径。 您可以使用此方法保留规范的本地副本，以避免每次使用模块时都下载它。 默认值："https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml"
entrust_api_user 字符串 / 必需	用于向 Entrust 证书服务 (ECS) API 进行身份验证的用户名。
force 布尔值	如果使用 force，则无论path 是否指向现有的有效证书，都会请求证书。 如果request_type=renew，如果正在续期的证书在过去 30 天内已颁发，则强制续期将失败，而不管remaining_days的值或cert_days的返回值如何 - ECS API 不支持对至少 30 天前的证书执行“续期”操作。 选项 false ← (默认) true
full_chain_path 路径	证书、中间证书和根证书的完整证书链的目标路径。
org 字符串	要包含在证书中的组织“O=”。 如果未指定org，则使用由client_id表示的客户端的组织。 除非cert_type为PD_SSL，如果client_id的值不是“1”（主客户端），则可能未指定此字段。对于非主客户端，证书只能使用该客户端的组织颁发。
ou 列表 / 元素=字符串	要包含在证书中的组织单位“OU=”。 ou的行为取决于您的帐户是否启用了组织单位。如果您的帐户禁用了组织单位支持，则将忽略来自csr和ou参数的组织单位。 如果同时指定了csr和ou，则ou中的值将覆盖csr主题区别名称中存在的OU字段。 如果对于续订或重新颁发操作均未指定csr或ou，则会重用初始证书中的OU字段。 将忽略来自csr的无效OU，但ou中任何无效的组织单位都将导致错误，提示“未批准的OU”。如果提供了未批准的组织单位，则可以使用ou参数强制失败。 当前产品最多只能指定一个OU。多个OU预留给未来的产品。
路径 路径 / 必需	作为PEM编码证书的生成证书的目标路径。 如果此位置的证书不是Entrust颁发的证书，即使当前证书在技术上有效，也始终会请求新证书。 如果此位置已经有Entrust证书，是否替换它取决于remaining_days计算。 如果正在替换现有证书（请参阅remaining_days、force和tracking_id），是否请求新证书或续订或重新颁发现有证书取决于request_type。
remaining_days 整数	证书必须剩余有效的几天数。如果cert_days < remaining_days，则将使用request_type获取新证书。 如果request_type=renew，如果正在续订的证书是在过去30天内颁发的，则续订将失败，因此请不要设置一个remaining_days值，该值在被操作的证书的完整生命周期内不足30天。 例如，如果您请求生命周期为90天的证书，请不要将remaining_days设置为60或更高的值。 force选项可用于确保始终获取新证书。 默认值： 30
request_type 字符串	如果tracking_id引用要重新颁发的有效证书，或者path中已经存在证书，但已指定force或cert_days < remaining_days，则执行的操作。 指定request_type=validate_only表示请求将针对ECS API进行验证，但不会颁发证书。 指定request_type=new表示将始终提交证书请求并颁发新证书。 指定request_type=renew表示将续订现有证书（如果存在，则由tracking_id指定，否则由path指定）。如果没有要续订的证书，则会请求新证书。 指定request_type=reissue表示将重新颁发现有证书（如果存在，则由tracking_id指定，否则由path指定）。如果没有要重新颁发的证书，则会请求新证书。 如果证书是在过去 30 天内签发的，则 renew 操作无效，将失败。 请注意，reissue 操作将导致重新签发的证书被吊销，请谨慎使用。 仅当 request_type=new 时才支持check_mode。 例如，设置 request_type=renew 和 remaining_days=30，并在多个剧本运行中指向同一个证书，这意味着在第一次运行时将请求新的证书。然后，在未来的运行中，直到证书距离过期还有 30 天以内，才会执行 ECS 的“renew”操作。 选项 "new" ← (默认) "renew" "reissue" "validate_only"
requester_email 字符串 / 必需	与证书跟踪信息关联的请求者邮箱，用于接收证书的交付和过期通知。
requester_name 字符串 / 必需	与证书跟踪信息关联的请求者姓名。
requester_phone 字符串 / 必需	与证书跟踪信息关联的请求者电话号码。
subject_alt_name 列表 / 元素=字符串	主题备选名称标识符，作为值的数组（适用于值为 STANDARD_SSL、ADVANTAGE_SSL、UC_SSL、EV_SSL、WILDCARD_SSL、PRIVATE_SSL 和 PD_SSL 的 cert_type）。 如果您正在请求新的 SSL 证书，并且传递了 subject_alt_name 参数，则会忽略 CSR 中的任何 SAN 名称。如果没有传递 subjectAltName 参数，则使用 CSR 中的 SAN 名称。 请参阅 request_type，以了解有关重新签发和续订期间 SAN 的更多信息。 对于 STANDARD_SSL 类型证书，如果证书的 CN 为 <domain>.<tld>，则仅接受 www.<domain>.<tld> 值。如果证书的 CN 为 www.<domain>.<tld>，则仅接受 <domain>.<tld> 值。
tracking_id 整数	要重新签发或续订的证书的跟踪 ID。 如果 request_type=new 或 request_type=validate_only，则 tracking_id 无效。 如果 path 中存在证书并且它是 ECS 证书，则将忽略 tracking_id。 如果 path 中不存在证书，或者存在但来自其他提供商，则将由 tracking_id 表示的证书进行续订或重新签发，并保存到 path。 如果 path 中不存在证书，并且 force 和 remaining_days 参数未指示需要新证书，则将由 tracking_id 引用的证书保存到 path。 当已知证书当前不存在于服务器上，但您希望通过 Ansible 剧本续订或重新签发它时，可以使用此方法。例如，如果您指定了 request_type=renew、已签发证书的 tracking_id 和不存在文件的 path，则任务的第一次运行将下载由 tracking_id 指定的证书（假设它仍然有效）。任务的未来运行将（如果适用 - 请参阅 force 和 remaining_days）续订现在存在于 path 中的证书。
tracking_info 字符串	附加到证书记录的自由格式跟踪信息。

属性

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

备注

注意

• 必须将 path 指定为证书的输出位置。

另请参阅

另请参阅

community.crypto.openssl_privatekey

可用于创建私钥（证书和帐户）。

community.crypto.openssl_csr

可用于创建证书签名请求 (CSR)。

community.crypto.to_serial 过滤器插件

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

示例

- name: Request a new certificate from Entrust with bare minimum parameters.
        Will request a new certificate if current one is valid but within 30
        days of expiry. If replacing an existing file in path, will back it up.
  community.crypto.ecs_certificate:
    backup: true
    path: /etc/ssl/crt/ansible.com.crt
    full_chain_path: /etc/ssl/crt/ansible.com.chain.crt
    csr: /etc/ssl/csr/ansible.com.csr
    cert_type: EV_SSL
    requester_name: Jo Doe
    requester_email: [email protected]
    requester_phone: 555-555-5555
    entrust_api_user: apiusername
    entrust_api_key: a^lv*32!cd9LnT
    entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
    entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key

- name: If there is no certificate present in path, request a new certificate
        of type EV_SSL. Otherwise, if there is an Entrust managed certificate
        in path and it is within 63 days of expiration, request a renew of that
        certificate.
  community.crypto.ecs_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr: /etc/ssl/csr/ansible.com.csr
    cert_type: EV_SSL
    cert_expiry: '2020-08-20'
    request_type: renew
    remaining_days: 63
    requester_name: Jo Doe
    requester_email: [email protected]
    requester_phone: 555-555-5555
    entrust_api_user: apiusername
    entrust_api_key: a^lv*32!cd9LnT
    entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
    entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key

- name: If there is no certificate present in path, download certificate
        specified by tracking_id if it is still valid. Otherwise, if the
        certificate is within 79 days of expiration, request a renew of that
        certificate and save it in path. This can be used to "migrate" a
        certificate to be Ansible managed.
  community.crypto.ecs_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr: /etc/ssl/csr/ansible.com.csr
    tracking_id: 2378915
    request_type: renew
    remaining_days: 79
    entrust_api_user: apiusername
    entrust_api_key: a^lv*32!cd9LnT
    entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
    entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key

- name: Force a reissue of the certificate specified by tracking_id.
  community.crypto.ecs_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    force: true
    tracking_id: 2378915
    request_type: reissue
    entrust_api_user: apiusername
    entrust_api_key: a^lv*32!cd9LnT
    entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
    entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key

- name: Request a new certificate with an alternative client. Note that the
        issued certificate will have it's Subject Distinguished Name use the
        organization details associated with that client, rather than what is
        in the CSR.
  community.crypto.ecs_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr: /etc/ssl/csr/ansible.com.csr
    client_id: 2
    requester_name: Jo Doe
    requester_email: [email protected]
    requester_phone: 555-555-5555
    entrust_api_user: apiusername
    entrust_api_key: a^lv*32!cd9LnT
    entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
    entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key

- name: Request a new certificate with a number of CSR parameters overridden
        and tracking information
  community.crypto.ecs_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    full_chain_path: /etc/ssl/crt/ansible.com.chain.crt
    csr: /etc/ssl/csr/ansible.com.csr
    subject_alt_name:
      - ansible.testcertificates.com
      - www.testcertificates.com
    eku: SERVER_AND_CLIENT_AUTH
    ct_log: true
    org: Test Organization Inc.
    ou:
      - Administration
    tracking_info: "Submitted via Ansible"
    additional_emails:
      - [email protected]
      - [email protected]
    custom_fields:
      text1: Admin
      text2: Invoice 25
      number1: 342
      date1: '2018-01-01'
      email1: [email protected]
      dropdown1: red
    cert_expiry: '2020-08-15'
    requester_name: Jo Doe
    requester_email: [email protected]
    requester_phone: 555-555-5555
    entrust_api_user: apiusername
    entrust_api_key: a^lv*32!cd9LnT
    entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
    entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key

返回值

常用的返回值已在 此处 记录，以下是此模块特有的字段

键	描述
backup_file 字符串	为证书创建的备份文件的名称。 返回值：已更改，如果backup 为 true 示例： "/path/to/www.ansible.com.crt.2019-03-09@11:22~"
backup_full_chain_file 字符串	为证书链创建的备份文件的名称。 返回值：已更改，如果backup 为 true 并且 full_chain_path 已设置。 示例： "/path/to/ca.chain.crt.2019-03-09@11:22~"
cert_days 整数	证书有效期剩余的天数。 返回值：成功 示例： 253
cert_details 字典	来自ECS API 获取证书调用的完整响应 JSON。 虽然保证响应内容与新的ECS API 版本向前兼容，但Entrust建议不要编写任何基于此字段内容执行操作的剧本。但是，它可能对调试、日志记录或审计目的有用。 返回值：成功
cert_status 字符串	ECS 中的证书状态。 当前可能的值（将来可能会扩展）：ACTIVE，APPROVED，DEACTIVATED，DECLINED，EXPIRED，NA，PENDING，PENDING_QUORUM，READY，REISSUED，REISSUING，RENEWED，RENEWING，REVOKED，SUSPENDED 返回值：成功 示例： "ACTIVE"
filename 字符串	生成的证书的目标路径。 返回值：已更改或成功 示例： "/etc/ssl/crt/www.ansible.com.crt"
serial_number 整数	已颁发证书的序列号。 此返回值为**整数**。如果需要以冒号分隔的十六进制字符串形式表示序列号，例如11:22:33，则需要使用community.crypto.to_serial将其转换为该格式。 返回值：成功 示例： 1235262234164342
tracking_id 整数	用于在ECS中引用和跟踪证书的跟踪ID。 返回值：成功 示例： 380079

作者

• Chris Trufan (@ctrufan)

集合链接

• 问题追踪器
• 代码库（源代码）
• 寻求帮助 (加密)
• 寻求帮助 (ACME)
• 提交错误报告
• 请求功能
• 通信