DV 中间证书颁发

使用 API 订购 DV 证书时,经常需要花费许多时间等待颁发证书。按照此工作流指南中的步骤,您可以使用我们的直接颁发 DV 证书功能立即获取颁发的 DV 证书,并将您的 API 调用次数减少最多 70%。

要请求 Encryption Everywhere DV 证书,必须按照这些步骤为您的帐户配置 AuthKey。否则,在提交请求时将收到 auth_key_not_setup 错误。

概览

为了充分使用直接颁发功能,在提交 DV 证书订单前必须完成这些步骤:

  1. 为您的 CertCentral 帐户创建 AuthKey。
  2. 为 DV 证书订单生成证书签名请求 (CSR)。
  3. 创建时间戳以确定请求令牌有效期限。
  4. 使用 AuthKey 和 CSR 构建请求令牌。
  5. 将生成的请求令牌添加到 DV 证书需要保护的域。
  6. 提交 DV 证书订单。

如果这些步骤已全部完成,在提交 DV 证书订单时,我们将立即向您颁发 DV 证书并在响应主体中返回证书。如果跳过任一步骤,则不会立即颁发证书。

第 1 步:创建 AuthKey

首先,请为您的 CertCentral 帐户创建 AuthKey。您将使用该密钥生成请求令牌,用于证明对域的控制权。您可以使用 POST 到创建 AuthKey 端点创建 AuthKey。

成功 POST 到此端点会返回 200 OK HTTP 响应。响应主体包括两个重要信息:

  • auth_key_id - 所创建的 AuthKey 的唯一 ID。
  • auth_key - 为您的 CertCentral 帐户生成的 AuthKey。

您的 CertCentral 帐户只能有一个 AuthKey。如果您的帐户已经有 AuthKey,则创建 AuthKey 端点将返回 400 Bad Request HTTP 响应和 auth_key_exists_for_account 错误。如果遇到该错误,可以使用 AuthKey 详情端点获取现有 AuthKey。

cURL
curl -X POST \
  https://www.digicert.com/services/v2/account/auth-key \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "auth_key_id": "{{auth_key_id}}",
  "auth_key": "{{auth_key}}"
}
400 Bad Request
{
  "errors": [
    {
      "code": "auth_key_exists_for_account",
      "message": "An error occurred while processing your request."
    }
  ]
}

第 2 步:生成证书签名请求 (CSR)

您的帐户拥有 AuthKey 后,下一步是为证书订单创建 CSR。您需要通过 CSR 生成请求令牌。务必在需要安装证书的服务器上生成 CSR。

在创建 CSR 时需要帮助?请参阅创建 CSR(证书签名请求)

第 3 步:创建时间戳

时间戳决定请求令牌的 30 天有效期的开始日期。在创建时间戳时,确保产生的有效期限与您提交 DV 证书订单的时间重合。如果提交订单的时间早于或晚于有效期限,将无法直接颁发证书。

您可以创建未来日期的时间戳。但是,不要在该日期之前提交 DV 证书订单。因为请求令牌暂时不是"有效"的,它不能用于验证域。

确定请求令牌的有效期限应该从什么时候开始后,需使用如下格式的时间戳:

generic
yyyyMMddhhmmss

例如,October 21, 2019 1:30:12 PM 将变成 20191021133012

第 4 步:生成请求令牌

请求令牌有 30 天有效期,该有效期由时间戳中的数据确定。在生成请求令牌时,确保 30 天的时间戳期限与您提交证书订单的时间重合。

现在有了 AuthKey、CSR 和时间戳,可以生成请求令牌以证明对域的控制权。该请求令牌允许您在下达证书订单之前设置域的 DNS TXT 记录或 fileauth.txt 文件。

生成请求令牌的方法

  1. 通过在 PEM 格式的 CSR 前面追加时间戳的方式构建需要哈希的密码。
  2. 使用 HMAC-SHA256 并以 AuthKey 作为密钥,对密码进行哈希。
  3. 将产生的十六进制哈希转换成十进制 (base10) 哈希值。
  4. 将十进制哈希值转换成 base36 哈希值。
  5. 确保 base36 哈希值的长度至少有 50 个字符。如果没有,则在前面追加 0 (0),直至长度达到 50 个字符。
  6. 通过在 base36 哈希值前面追加时间戳的方式构建最终的请求令牌。

该伪码示例显示了如何按照上述步骤生成请求令牌。

generic
# Declare AuthKey, CSR, and timestamp
auth_key = 'certcentral_account_auth_key'
csr = 'pem_formatted_csr'
timestamp = 'yyyyMMddhhmmss'

# Construct secret to be hashed
secret = timestamp + csr

# Hash secret using HMAC-SHA256 and auth_key
hash = hmac.sha256(secret, auth_key)

# Convert hexadecimal hash to decimal
decimal_hash = convertToBase10(hash)

# Convert decimal_hash to base36
base36_hash = convertToBase36(decimal_hash)

# If base36_hash length is < 50, prepend with zeros
valid_hash = base36_hash.padStart(50, '0')

# Construct final request token
request_token = timestamp + valid_hash

第 5 步:放置请求令牌

对于直接颁发 DV 证书,在订购证书之前,必须将请求令牌放在以下其中一个位置:

  • 域的 DNS TXT 记录中。
  • 位于您的网站预定义位置的 fileauth.txt 文件中。

放置请求令牌后,可以提交 DV 证书订单。

DNS TXT

可以通过创建含有请求令牌的 DNS TXT 记录的方式证明对 DV 证书订单上的域的控制权。创建 DNS TXT 记录后,可以请求 DV 证书

在为请求令牌使用 DNS TXT 时,务必将 dcv_method 值设置为 dns-txt-token

  1. 转到 DNS 提供商的网站并创建新的 TXT 记录。

  2. TXT 值字段中,粘贴请求令牌。

  3. 根据您的证书订单和要保护的域,请为主机字段执行以下操作之一:

    • 基域(例如,example.com)
      留空或输入 @ 符号(取决于您的 DNS 要求)。
    • 子域
      输入证书需要保护的子域。
    • 授权域名
      输入 _dnsauth
  4. 在记录类型字段(或同等字段)中,选择 TXT。

  5. 选择生存时间 (TTL) 值或使用 DNS 提供商的默认值。

  6. 保存记录。

  7. 提交 DV 证书订单,确保将 dcv_method 设置为 dns-txt-token

文件认证

可以通过将含有请求令牌的 fileauth.txt 文件放在您网站的预定义位置进行托管的方式证明对 DV 证书订单上的域的控制权。请务必要避免使用文件认证的一些常见错误

将文件放在您的网站上后,可以请求 DV 证书

在为请求令牌使用文件认证时,务必将 dcv_method 值设置为 http-token

  1. 打开文本编辑器(例如,记事本)并粘贴请求令牌。

  2. 将文件另存为 fileauth.txt。

  3. 将文件放在您网站的此位置(根据需要创建目录):

    http://[domain.name]/.well-known/pki-validation/fileauth.txt

在基于 Windows 的服务器上,必须通过命令行创建 .well-known 文件夹:mkdir .well-known

  1. 提交 DV 证书订单,确保将 dcv_method 设置为 http-token

第 6 步:提交 DV 证书订单

放置请求令牌后,可以提交 DV 证书订单请求。可以通过 POST 到订购 DV SSL 端点执行此操作。

成功 POST 到此端点会返回 201 Created HTTP 响应代码。由于满足所有立即颁发证书要求,在响应主体中将返回完整证书链。

下达 DV 证书订单时,确保 dcv_method 值与请求令牌的位置对应。

如果不满足任一先决条件,则不会立即颁发证书。您不会收到完整证书链,而是收到标准订购 DV SSL 响应主体

cURL (DNS TXT)
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",
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "validity_years": 1,
    "dcv_method": "dns-txt-token"
}'
cURL (File Auth)
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",
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "validity_years": 1,
    "dcv_method": "http-token"
}'
201 Created
{
  "id": 112339,
  "certificate_id": 132345,
  "certificate_chain": [
    {
      "subject_common_name": "example.com",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert SHA2 Secure Server CA",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert Global Root CA",
      "pem": "<pem_certificate>"
    }
  ]
}