community.crypto.ecs_certificate 模块 – 使用 Entrust 证书服务 (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 证书服务 (ECS) API 创建、重新颁发和续订证书。

• 需要 Entrust 证书服务 (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 列表 / 元素=字符串	主题替代名称标识符，作为值的数组（适用于 cert_type 值为 STANDARD_SSL、ADVANTAGE_SSL、UC_SSL、EV_SSL、WILDCARD_SSL、PRIVATE_SSL 和 PD_SSL）。 如果您正在请求新的 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"
文件名 字符串	生成的证书的目标路径。 返回值： changed 或 success 示例： "/etc/ssl/crt/www.ansible.com.crt"
序列号 整数	已颁发证书的序列号。 此返回值为整数。如果您需要以冒号分隔的十六进制字符串形式表示序列号，例如 11:22:33，则需要使用 community.crypto.to_serial将其转换为该格式。 返回：成功 示例： 1235262234164342
tracking_id 整数	用于在 ECS 中引用和跟踪证书的跟踪 ID。 返回：成功 示例： 380079

作者

• Chris Trufan (@ctrufan)

资源链接

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