DV 证书生命周期

DV 证书生命周期包括以下主要步骤:

  • 准备 DV 证书请求
  • 提交 DV 证书订单
  • (可选)取消证书订单
  • 完成域控制验证 (DCV)
  • 检查订单状态
  • 下载颁发的证书

颁发证书后,您可以执行以下任意操作:

  • 补发证书
  • 吊销证书
整个 DV 证书生命周期

准备 DV 证书请求

要构建您的请求主体并提交订单请求,您需收集一些重要信息:

  • 需要证书保护的域名
  • 在需要安装证书的服务器上生成的证书签名请求 (CSR)
  • 证书的有效期(证书有效的时间期限)
  • 用于证明对域的控制权的 DCV 方法

域名

收集需要证书保护的域名后,应将其输入到两个请求主体参数的其中一个参数中。

参数 类型 描述
common_name 字符串 需要证书保护的主域。
dns_names 数组 需要证书保护的任何其他域名。
将域添加到此参数可能产生额外费用。

所有 DV 证书订单均包括“Plus”功能,允许您包括根和域的 www 子域,不会产生额外费用。在构建请求主体时,请将基域 ([your-domain].com) 添加到 common_name 参数,再将另一个版本的域 (www.[your-domain].com) 添加到 dns_names 数组。

证书签名请求 (CSR)

应该在需要安装证书的服务器上生成证书签名请求 (CSR)。生成后,在请求主体的 csr 参数中输入 PEM 格式的 CSR。请参阅创建 CSR(证书签名请求)了解更多信息。

有效期

在订购证书时,必须指定证书的有效期。您可以使用以下任一参数确定证书的有效期。

参数 类型 描述
validity_years int 使用此参数指定以年为单位的证书有效期。
允许的值:1,2
validity_days int 使用此参数指定以天为单位的证书有效期。
custom_expiration_date 字符串 使用此参数指定证书到期的具体日期。
格式:yyyy-MM-dd

如果在请求主体中包括多个有效期参数,我们会遵循如下优先顺序:custom_expiration_date > validity_days > validity_years.

DCV 方法

电子邮件 DCV 是默认用于 DV 证书订单的 DCV 方法。如果需要,您可以通过在请求主体中包括 dcv_method 参数来更改默认 DCV 方法。dcv_method 参数接受以下值:

描述
email 将 DCV 电子邮件发送到我们在域的 WHOIS 记录中找到的任何电子邮件地址(例如,管理员和技术联系人)以及域的五个构造的电子邮件地址(admin、administrator、webmaster、hostmaster 和 postmaster
@[domain_name])。
使用此方法时,您可以通过包括 dcv_emails 对象来定义特定的电子邮件范围。
dns‑txt‑token 在响应主体中返回要添加到域的 DNS TXT 记录的随机值令牌。使用此方法需要能够修改域 DNS 记录。
http‑token 在响应主体中返回要放置在需要证书保护的网站的 .txt 文件中的随机值令牌。使用此方法需要能够向 Web 服务器上传文件。

请参阅域控制验证 (DCV) 方法了解关于不同 DCV 方法及如何完成验证的更多信息。

(可选)dcv_emails 数组

使用电子邮件 DCV 方法时,可以指定在发送 DCV 电子邮件时要使用的电子邮件地址。因此,需在请求主体中包括 dcv_emails 数组并为订单上的每个域添加一个条目。

使用此参数时,输入的电子邮件地址必须在域的 WHOIS 记录中指定或者是该域的其中一个默认的电子邮件地址(根据行业标准定义为:admin、administrator、webmaster、hostmaster 和/或 postmaster @[domain_name])。而且,我们仅向指定的电子邮件地址发送 DCV 电子邮件。

例如,如果您指定了 john.doe@,[domain_name],我们不会向任何默认的电子邮件地址发送 DCV 电子邮件。或者如果您指定了 admin@[domain.com,],我们不会向 john.doe@ 发送 DCV 电子邮件[domain_name]。

Example dcv_emails array
"dcv_emails": [
  { 
    "dns_name": "example.com",
    "email_domain": "example.com",
    "email": "hostname@example.com"
  },
  { 
    "dns_name": "my.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  },
  { 
    "dns_name": "another.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  }
]

提交 DV 证书订单

现在您已经收集了上述信息,可以构建请求主体并提交订单请求。可以通过 POST 到订购 DV SSL 端点执行此操作。

成功 POST 到此端点会返回 201 Created HTTP 响应代码。响应主体包含一些重要信息,可用于检查订单的状态以及在颁发证书后下载证书。

  • id – 用于检查订单详细信息及执行 DCV 操作的订单编号。
  • certificate_id – 用于下载已颁发的证书的证书 ID。
  • dcv_random_value – 用于 dns-txt-token 和 http-token DCV 方法的随机生成的令牌。此令牌的有效期是 30 天。

有关在请求主体中使用的每个参数的更多信息,请参阅订购 DV SSL - 请求参数表。

cURL
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "dns_names": [
            "sub.example.com",
            "app.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 45
        },
        "signature_hash": "sha256",
        "organization_units": [
            "Accounting department"
        ]
    },
    "validity_years": 2,
    "comments": "Message for the approver",
    "disable_renewal_notifications": true,
    "dcv_method": "email",
    "locale": "en",
    "dcv_emails": [
      { 
        "dns_name": "example.com",
        "email_domain": "example.com",
        "email": "hostname@example.com"
      },
      { 
        "dns_name": "sub.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      },
      { 
        "dns_name": "app.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      }
    ],
    "payment_method": "balance",
    "custom_fields": [
        {
            "metadata_id": 11,
            "value": "Invoice #00001"
        }
    ]
}'
201 Created (email)
{
  "id": 112233,
  "certificate_id": 123456
}
201 Created (dns-txt-token or http-token)
{
  "id": 112233,
  "certificate_id": 123456,
  "dcv_random_value": "icru1984rnekfj"
}

提交订单后,您可以使用订单信息端点获取订单详细信息及查看提交的信息。

(可选)取消证书订单

提交订单后,您可能需要取消订单。要取消订单,需将状态从待处理更改为已取消。可以通过 PUT 到更新订单状态端点执行此操作。

成功 PUT 到此端点会返回 204 No Content HTTP 响应。

status 参数仅允许值 CANCELED(区分大小写)。

cURL
curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/status' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "status": "CANCELED",
    "note": "Message about the cancellation."
}'
204 No Content
// empty

完成域控制验证 (DCV)

提交 DV 订单后,现在需证明对订单上所列域的控制权。

无论选择哪种 DCV 方法,都必须为需要证书保护的每个域完成 DCV。例如,如果选择了 dns-txt-token 方法,必须为订单上的每个域创建 DNS TXT 记录。

电子邮件 DCV 方法

如果在响应主体中包括 dcv_emails 数组,则会向数组中指定的电子邮件地址发送 DCV 邮件。或者向以下电子邮件地址发送 DCV 邮件:

  • 在域的 WHOIS 记录中找到的所有电子邮件地址
  • 以下五个构造的电子邮件地址:
    • admin@[domain_name]
    • administrator@[domain_name]
    • webmaster@[domain_name]
    • hostmaster@[domain_name]
    • postmaster@[domain_name]

要完成电子邮件 DCV,请在您的电子邮件客户端收件箱中找到主题为 的电子邮件[所需操作]审批证书请求:[yourdomain]{订单编号} 并按照说明进行操作。

如果需要为已提交的订单重新发送 DCV 电子邮件,可以使用 DV SSL:重新发送电子邮件端点(将 {{order_id}} 占位符替换为当您提交订单时在响应主体中返回的订单编号)。

DNS TXT DCV 方法

如果您不再持有随机值或需要生成新的随机值,可以使用 DV SSL:创建 DCV 令牌端点,将 {{order_id}} 占位符替换为当您提交订单时在响应主体中包括的订单编号)。

请按照以下步骤完成 DNS TXT DCV 并证明对域的控制权:

  1. 复制当您提交订单时在响应主体中返回的 dcv_random_value
  2. 转到 DNS 提供商的网站并创建新的 TXT 记录。
  3. 在“TXT 值”字段中,输入您复制的随机值。
  4. 主机字段
    1. 基域(例如,[yourdomain].com)
      您要验证基域吗?将主机字段留空或添加 @ 符号(取决于您的 DNS 提供商要求)。
    2. 子域(例如,[your.domain].com)
      您要验证子域吗?在主机字段中,添加您要验证的子域。
  5. 在记录类型字段(或同等字段)中,选择 TXT
  6. 选择生存时间 (TTL) 值或使用 DNS 提供商的默认值。
  7. 保存记录。
  8. 为订单上的每个域重复以上步骤。

为订单上的所有域添加 DNS TXT 记录后,您现在可以要求我们验证 TXT 记录(请参阅“检查 DCV”)。

HTTP 令牌 DCV 方法

请按照以下步骤完成 HTTP 令牌 DCV 并证明对域的控制权:

  1. 复制当您提交订单时在响应主体中返回的 dcv_random_value
  2. 将您复制的随机值粘贴到您的首选文本编辑器中。
  3. 使用文件名 fileauth.txt 保存文件。
  4. 在 Web 服务器上,将 fileauth.txt 文件上传到以下位置:[yourdomain]/.well-known/pki-validation/fileauth.txt

执行 DCV 检查

为订单上的每个域将随机值添加到 DNS TXT 记录(DNS TXT 方法)或将 fileauth.txt 上传到指定位置(HTTP DCV 方法)后,您现在可以执行 DCV 检查。可以通过放置到 DV SSL:检查 DCV 端点执行此操作。

放置到此端点可能返回四种响应:

  • 200 OK – DCV 成功完成
  • 400 Bad Request – 此响应有三种可能的错误代码:
    • invalid_dns_txt – 找不到 DNS TXT 记录或包含一个或多个域的错误的随机值。请确认订单上的所有域有具有正确随机值的相应 DNS TXT 记录。
    • file_random_value_not_found – 找不到 fileauth.txt 或包含一个或多个域的错误的随机值。请确认订单上的所有域位于正确的目录中、公开发布并且包含正确的随机值。
    • invalid_dns_method – 此订单的 DCV 方法已经设置为电子邮件。找到发送的电子邮件并按照 DCV 说明完成操作,或更改 DCV 方法。
cURL
curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/check-dcv' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "order_status": "pending",
  "certificate_id": 123456,
  "dcv_status": "valid"
}
400 (dns-txt-token)
{
  "errors": [
    {
      "code": "invalid_dns_txt",
      "message": "Could not find a valid TXT record for one or more domains."
    }
  ]
}
400 (http-token)
{
  "errors": [
    {
      "code": "file_random_value_not_found",
      "message": "Could not find the random value at the expected file location for one or more domains."
    }
  ]
}
400 (email)
{
  "errors": [
    {
      "code": "invalid_dns_method",
      "message": "An error occurred while processing your request."
    }
  ]
}

检查订单状态

提交订单并且为每个域完成 DCV 后,您希望知道订单状态何时发生更改以及何时可以下载证书。最好的方法是使用 GET 到状态变更列表端点。

GET 到此端点可能返回四种响应:

  • 200 OKorders 数组)- 订单数组列出在指定时间段内更改了状态的所有订单。当您的订单状态从待处理更改为已发布时,将显示在此列表中。如果返回多个订单,则使用订单编号或证书编号查找订单。
  • 200 OK(空对象)- 具有空对象 ({}) 的响应意味着在指定时间段内没有订单的状态发生更改。可扩大时间段或等待再次发送请求。
  • 400 Bad Request – 具有 time_frame_too_long 错误代码的响应意味着在 URL 查询字符串中指定的时间段超出最大值。可将时间段缩短至小于 10080 分钟(7 天)的值。

cURL
curl -X GET \
  'https://www.digicert.com/services/v2/order/certificate/status-changes?minutes=10' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "orders": [
    {
      "order_id": 112233,
      "certificate_id": 123456,
      "status": "issued"
    }
  ]
}
200 OK (no orders found)
{}
400 Bad Request
{
  "errors": [
    {
      "code": "time_frame_too_long",
      "message": "An error occurred while processing your request."
    }
  ]
}

下载 DV 证书

订单状态从待处理更改为已颁发后,您的证书可供下载。根据您的需要,您可以使用四个端点下载证书:

补发 DV 证书

通过补发证书可添加、删除或掉换域名、更新 CSR 或更改证书的签名哈希,无需提交新订单。补发证书将拥有新的证书编号,但订单编号相同。补发请求得到批准后,将颁发新证书并且需要重新安装证书。

补发证书时,您需提供此信息:

  • 公用名
  • SAN(包括 dns_names 参数中的当前 SAN 以及需要保护的任何其他 SAN)
  • CSR(要获取并重复使用当前的 CSR,请使用请求信息端点)
  • 服务器平台 ID(选项列于此处

即使上面的部分信息相同,您仍然需要在补发请求中包括这些信息。

请注意,进行特定更改,例如添加更多 SAN(“dns_names”),可能会产生额外费用。

可能需要对部分或全部域执行 DCV。

补发证书端点接受以下可选参数:

  • 备注 - 在请求中添加给审批者的消息。
  • skip_approval - 允许立即提交请求以进行验证,无需批准补发请求。
cURL
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/reissue' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "certificate": {
    "common_name": "example.com",
    "dns_names": [
        "sub.example.com"
    ],
    "csr": "<csr>",
    "server_platform": {
      "id": 2
    },
    "signature_hash": "sha256"
    "skip_approval": true
  }
}'
201 Created
{
  "id": 112233,
  "requests": [
    {
      "id": 332211
    }
  ]
}
201 skip_approval
{
  "id": 112233,
  "certificate_id": 111112
}

补发完成后,下载新证书(请参阅下载 DV 证书)。

通过使用列出补发证书端点可以获取订单的完整补发记录。

吊销 DV 证书

发出订单后,如有需要,可以提交吊销请求。

所有吊销请求必须由 CertCentral 中的管理员批准后,DigiCert 才会吊销证书。必须执行该审批步骤,不可跳过。

您可以使用以下两个端点的其中一个吊销证书:

  • 吊销证书 - 使用此端点可按照证书编号吊销特定证书。
  • 吊销订单证书 - 使用此端点可吊销与特定订单编号关联的所有证书。

两个端点都使用相同的请求主体参数。

提交吊销请求后,需要由管理员使用更新请求状态端点批准请求。

cURL
curl -X PUT \
  'https://www.digicert.com/services/v2/certificate/{{certificate_id}}/revoke' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "comments": "I no longer need this cert."
}'
201 Created
{
  "id": 1,
  "date": "2016-02-10T17:06:15+00:00",
  "type": "revoke",
  "status": "pending",
  "requester": {
    "id": 14,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@digicert.com"
  },
  "comments": "I no longer need this cert."
}