DV 憑證生命周期

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

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

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

  • 重新發行憑證
  • 撤銷憑證
整體 DV 憑證生命周期

準備 DV 憑證要求

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

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

網域名稱

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

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

所有包括「附加」功能的 DV 憑證訂單,允許您免費涵蓋您網域的根和 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 string 使用此參數指定憑證應到期的特定日期。
格式: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‑txt‑token 在要新增到網域上的 DNS TXT 記錄中的回應本文中,傳回隨機值權杖。使用此方法需要修改網域 DNS 記錄的功能。
http‑token 在放置在憑證保護安全的網站上的 .txt 檔案中的回應本文中,傳回隨機值權杖。使用此方法要求上傳檔案到網頁伺服器的功能。

如需更多有關不同的 DCV 方法和與如何完成的資訊,請參閱網域控制驗證 (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"
  }
]

提交 DV 憑證訂單

現在您已收集上述的資訊,您已準備好建構您的要求本文並提交您的訂單請求。使用 POST (公佈) 到訂購 OV/EV SSL 端點完成此操作。

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

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

如果您需要重新傳送已提交訂單的 DCV 電郵,您可以使用 DV SSL:重新傳送電郵端點 ({{order_id}}提交訂單時,用回應本文中傳回的訂單 ID 取代預留位置)。

DNS TXT DCV 方法

如果您不再有隨機值,或需要產生一個新的,您可以使用 DV SSL:產生 DCV 權杖端點,{{order_id}}在您提交訂單時,用回應本文中包括的訂單 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 端點的 PUT 完成。

到此端點的 PUT 傳回四種可能的回應:

  • 200 OK – DCV 成功完成。
  • 400 Bad Request (400 錯誤的要求) – 此回應有三種可能的錯誤代碼:
    • 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 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."
    }
  ]
}

下載 DV 憑證

訂單狀態從擱置變成發行後,您的憑證已準備好可以下載。視您的需求而定,有四個您可以用於下載您的憑證的端點:

重新發行 DV 憑證

重新發行憑證允許您新增、移除或交換網域名稱、更新 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
}

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

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

撤銷 DV 憑證

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

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