OV/EV 憑證生命周期

OV/EV 憑證生命周期由這些主要步驟所組成:

  • 準備憑證要求
  • 提交憑證訂單
  • (選用) 取消憑證訂單
  • 完成網域控制驗證 (DCV)
  • 完成組織驗證
  • 檢查訂單狀態
  • 下載發行的憑證

一發行憑證後,您即可以執行任何這些動作:

  • 重新發行憑證
  • 撤銷憑證

準備憑證要求

若要建構您的要求本文和提交訂單要求,您需要收集一些關鍵部份的資料:

  • 由憑證保護安全的網域名稱。
  • 在安裝憑證所在的伺服器上產生的憑證簽章要求 (CSR)。
  • 憑證有效期間 (憑證應該有效的時間長度)。
  • 證明有網域的控制權時使用的 DCV 方法。
  • 正驗證的組織的法律名稱和註冊資料

網域名稱

您一收集由憑證保護安全的網域名稱後,應該可以用以下兩個要求本文參數之一輸入這些網域名稱。

參數 類型 說明
common_name string 由憑證保護安全的主要網域。
dns_names array 由憑證保護安全的任何其他網域。
新增網域到此參數中可能產生額外的費用。

所有 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 string 使用此參數指定憑證應到期的特定日期。
格式:yyyy-MM-dd

如果在要求內文中納入了一個以上的有效期參數,我們就會依如下所示排列其優先順序:custom_expiration_date > validity_days > validity_years.

DCV 方法

Email 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 檔案中的回應本文中,傳回隨機值權杖。使用此方法要求上傳檔案到網頁伺服器的功能。

如需更多有關不同的 DCV 方法與如何完成的資訊,請參閱證明對擱置的憑證訂單上的網域擁有控制權

(選填) dcv_emails array

使用電郵 DCV 方法時,可以指定在傳送 DCV 電郵時,應該使用的電郵地址。要這樣做,請在要求本文中加入 dcv_emails 陣列,然後新增用於訂單上每個網域的的項目。

使用此參數時,輸入的電郵地址必須在網域的 WHOIS 記錄中指定,或是用於網域的預設電郵地址之一 (依業界標準定義為 admin、administrator、webmaster、hostmaster 和/或 postmaster @[domain_name])。此外,我們將只會將 DCV 電郵傳送到指定的位址。

例如,如果您指定 john.doe@,[domain_name],我們將不傳送 DCV 電郵到任何預設的電郵地址。或如果您指定 admin@[domain.com,],我們將不會傳送 DCV 電郵到 john.doe@[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"
  }
]

提交憑證訂單

現在您已收集上述的資訊,您已準備好建構您的要求本文並提交您的訂單請求。使用到訂購 OV/EV SSL 端點的 POST 完成。請注意透過個別的端點訂購 Secure Site 產品系列

您可以在此處的 organization 物件中提交組織詳細資料和聯絡人。如果組織已有指派的 Id,您可以僅用字串 id 傳遞,毋須提供完整的組織資料。

到此端點的成功 POST 將會產生 201 Created HTTP 回應代碼。回應本文將包括資料的一些主要部份,可用於檢查訂單的狀態,以及在一發行後下載憑證。

  • id – 訂單 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 的[yourdomain]{訂單編號} 並遵照指示。

如果您需要重新傳送已提交訂單的 DCV 電郵,您可以使用重新傳送電郵端點 ({{order_id}}提交訂單時,用回應本文中傳回的訂單 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 OK (orders 陣列) – 訂單陣列列出在指定時段中已變更狀態的所有訂單。當您的訂單狀態從擱置變成發行時,將會出現在清單中。如果傳回多份訂單,請使用訂單 ID 或憑證 ID 尋找訂單。
  • 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 或變更憑證的簽章雜湊,不需要提交新訂單。重行發行的憑證將有新憑證 ID,但訂單 ID 相同。核准重新發行後,發行新憑證且需要重新安裝。

重新發行憑證時,您需要提供這項資料:

  • 一般名稱
  • SAN (包括 dns_names 參數中的目前 SAN 和要保護安全的任何其他 SAN)
  • CSR (若要取得和重複使用目前的 CSR,請使用要求資料端點)
  • 伺服器平台 ID (選項列在此處)

即使上述詳細資料有一些保持不變,您仍需要將其加入重新發行要求中。

請注意,有些變更,例如加入其他 SAN ('dns_names') 可能產生額外的費用。

可能必須為其中一些或全部的網域執行 DCV。

重新發行憑證端點接受下列選用的參數:

  • comments – 新增訊息到給核准者的要求中。
  • 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
}

完成重新發行後,下載新憑證 (請參閱下載憑證)。

您可以使用列出重新發行端點,取得訂單的完整重新發行歷史記錄。

撤銷憑證

發行您的訂單後,您可以視需要提交撤銷憑證。

在 DigiCert 撤銷憑證前,必須由 CertCentral 中的系統管理員核准所有撤銷要求。此核准步驟是必需的,而且不可略過。

您可以使用兩個端點之一撤銷憑證:

  • 撤銷憑證 – 使用此端點撤銷使用憑證 ID 的特定憑證。
  • 撤銷訂單憑證 – 使用此端點撤銷與訂單 ID 關聯的所有憑證。

兩個端點使用相同的要求本文參數。

提交撤銷要求後,要求需要由系統管理員使用更新要求狀態端點核准。

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."
}