OV/EV 证书生命周期

OV/EV 证书生命周期包括以下主要步骤:

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

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

  • 补发证书
  • 吊销证书

准备证书请求

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

  • 需要证书保护的域名。
  • 在需要安装证书的服务器上生成的证书签名请求 (CSR)。
  • 证书的有效期(证书有效的时间期限)。
  • 用于证明对域的控制权的 DCV 方法。
  • 经过验证的组织的法定名称和注册信息。

域名

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

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

所有 OV/EV 证书订单都允许在单域证书上免费包括一个特定的附加 SAN。在构建请求主体时,请将基域 ([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 是默认用于 OV/EV 证书订单的 DCV 方法。如果需要,您可以通过在请求主体中包括 dcv_method 参数来更改默认 DCV 方法。dcv_method 参数接受以下值:

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

请参阅证明对待处理证书订单上所列域的控制权,了解关于不同 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"
  }
]

提交证书订单

现在您已经收集了上述信息,可以构建请求主体并提交订单请求。可以通过 POST 到订购 OV/EV SSL 端点执行此操作。请注意,Secure Site 产品系列通过单独的端点进行订购

在此处的 organization 对象中提交组织详细信息和联系人。如果组织已经有分配的 ID,只需使用字符串 id 传递它,无需提供完整的组织信息。

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

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

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

cURL
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{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,
    "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",
    "organization": {
        "name": "Epigyne Unwieldiness llc",
        "assumed_name": "Epigyne Unwieldiness",
        "country": "us",
        "address": "932 Prospect Street",
        "address2": "Floor 08",
        "city": "Minneapolis",
        "state": "mn",
        "zip": "40849",
        "telephone": "666-186-6450",
        "container": {
            "id": 93288
        },
        "organization_contact": {
            "first_name": "Gia",
            "last_name": "Booth",
            "job_title": "Clinical Laboratory Technician",
            "email": "gia.booth@inbox.com",
            "telephone": "666-186-6450",
            "telephone_extension": "736"
        }
    },
    "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)

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

无论选择哪种 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 电子邮件,可以使用重新发送电子邮件端点(将 {{order_id}} 占位符替换为当您提交订单时在响应主体中返回的订单编号)。

DNS CNAME DCV 方法

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

  1. 复制当您提交订单时生成的 dcv_random_value。对于 OV/EV 订单,可以通过使用域信息端点并包括 include_dcv=true URL 查询字符串的方式检索此值。
  2. 转到 DNS 提供商的网站并创建新的 CNAME 记录。
  3. 在主机名字段(或同等字段)中,输入您复制的随机值。
  4. 在记录类型字段(或同等字段)中,选择 CNAME
  5. 在目标主机字段(或同等字段)中,输入 dcv.digicert.com(将 CNAME 记录指向 dcv.digicert.com)。
  6. 选择生存时间 (TTL) 值或使用 DNS 提供商的默认值。
  7. 保存记录。
  8. 为订单上的每个域重复以上步骤。

为订单上的所有域添加 DNS CNAME 记录后,您现在可以要求我们验证 CNAME 记录。

DNS TXT DCV 方法

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

  1. 复制当您提交订单时生成的 dcv_random_value。对于 OV/EV 订单,可以通过使用域信息端点并包括 include_dcv=true URL 查询字符串的方式检索此值。
  2. 转到 DNS 提供商的网站并创建新的 TXT 记录。
  3. 在“TXT 值”字段中,输入您复制的随机值。
  4. 主机字段
    1. 基域(例如,[yourdomain].com)
      您要验证基域吗?将主机字段留空或添加 @ 符号(取决于您的 DNS 提供商要求)。
    2. 子域(例如,[your.domain].com)
      您要验证子域吗?在主机字段中,添加您要验证的子域。
  5. 在记录类型字段(或同等字段)中,选择 TXT
  6. 选择生存时间 (TTL) 值或使用 DNS 提供商的默认值。
  7. 保存记录。
  8. 为订单上的每个域重复以上步骤。

为订单上的所有域添加 DNS TXT 记录后,您现在可以要求我们验证 TXT 记录。

HTTP 令牌 DCV 方法

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

  1. 在 CertCentral 中,复制“订单详细信息”页面的 HTTP 令牌信息。
  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 检查。可以通过 CertCentral 中的“订单详细信息”页面完成此操作。

在该页面的“订单状态”部分,单击仍被列为“等待 DCV”的每个域,然后单击"检查"以选中并确认 DCV 方法。

组织验证

除了域验证以外,所有 OV/EV 订单还要求进行组织验证。提交订单后,DigiCert 的验证团队将开始执行 OV/EV 组织验证流程。

必须完成组织验证和域验证后,才能颁发证书。

检查验证状态

您可以通过 GET 到组织验证详情端点检查组织的当前验证状态。

成功 GET 到此端点会返回 200 OK HTTP 响应。

cURL
curl -X GET \
  'https://www.digicert.com/services/v2/organization/{{organization_id}}/validation' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "validations": [
    {
      "type": "ov",
      "name": "OV",
      "description": "Normal Organization Validation",
      "status": "pending"
    },
    {
      "type": "ev",
      "name": "EV",
      "description": "Extended Organization Validation (EV)",
      "status": "pending",
      "verified_users": [
        {
          "id": 12,
          "first_name": "John",
          "last_name": "Smith"
        }
      ]
    }
  ]
}

检查订单状态

提交订单并且为每个域完成 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."
    }
  ]
}

下载证书

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

补发证书

通过补发证书可添加、删除或掉换域名、更新 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
}

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

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

吊销证书

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

所有吊销请求必须由 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."
}