DV 憑證生命周期由這些主要步驟所組成:
一發行憑證後,您即可以執行任何這些動作:
若要建構您的要求本文和提交訂單要求,您需要收集一些關鍵部份的資料:
您一收集由憑證保護安全的網域名稱後,應該可以用以下兩個要求本文參數之一輸入這些網域名稱。
參數 | 類型 | 說明 |
---|---|---|
common_name
|
string | 由憑證保護安全的主要網域。 |
dns_names
|
array |
由憑證保護安全的任何其他網域。 新增網域到此參數中可能產生額外的費用。 |
所有包括「附加」功能的 DV 憑證訂單,允許您免費涵蓋您網域的根和 www 子網域。建構您的要求本文時,新增基本網域 ([your-domain].com) 到 common_name
參數,然後到其他版本的網域 (www.[your-domain].com) 到 dns_names
陣列。
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」是用於 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 方法時,可以指定在傳送 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]。
"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 端點完成此操作。
到此端點的成功 POST 將會產生 201 Created HTTP 回應代碼。回應本文將包括資料的一些主要部份,可用於檢查訂單的狀態,以及在一發行後下載憑證。
id
– 訂單 ID,用於檢查訂單詳細資料和執行 DCV 動作。certificate_id
– 憑證 ID,用於下載已發行的憑證。dcv_random_value
– 隨機產生的權杖,用於 dns-txt-token 和 http-token DCV 方法。此權杖在 30 天後到期。如需更多有關在要求本文中使用的每個參數的資訊,請參閱訂購 DV SSL – 要求參數表。
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"
}
]
}'
{
"id": 112233,
"certificate_id": 123456
}
{
"id": 112233,
"certificate_id": 123456,
"dcv_random_value": "icru1984rnekfj"
}
提交訂單後,您可以使用訂單資訊端點取得訂單詳細資料和檢閱提交的資訊。
下單後,可能會有幾次需要取消訂單。要取消訂單,您要將擱置中狀態變更為已取消。使用到更新訂單狀態端點的 PUT 完成。
此端點的成功 PUT 傳回 204 No Content HTTP 回應。
status
參數僅允許 CANCELED
(區分大小寫) 的值。
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."
}'
// empty
提交 DV 訂單時,您要證明對訂單上的網域擁有控制權。
無論哪一個 DCV 方法,您都必須完成由憑證保護安全的每個網域的 DCV。例如,如果選擇 dns-txt-token
方法,您必篩在訂單上為每個網域建立 DNS TXT 記錄。
如果 dcv_emails
陣列包括在回應本文中,DCV 電郵會傳送到陣列中定義的位址。否則,DCV 電郵會傳送到這些位址:
若要在您的電郵用戶收件匣中完成電郵 DCV,請用主旨尋找電郵[需要的行動]核准 yourdomain 的[yourdomain]{訂單編號} 並遵照指示。
如果您需要重新傳送已提交訂單的 DCV 電郵,您可以使用 DV SSL:重新傳送電郵端點 ({{order_id}}提交訂單時,用回應本文中傳回的訂單 ID 取代預留位置)。
如果您不再有隨機值,或需要產生一個新的,您可以使用 DV SSL:產生 DCV 權杖端點,{{order_id}}在您提交訂單時,用回應本文中包括的訂單 ID 取代預留位置)。
請遵照這些步驟完成 DNS TXT DCV,並證明對您的網域有控制權:
dcv_random_value
。您一新增用於訂單上所有網域的 DNS TXT 記錄後,您已準備好讓我們確認 TXT 記錄 (請參閱「檢查 DCV」)。
請遵照這些步驟完成 HTTP 權杖 DCV,並證明對您的網域有控制權:
dcv_random_value
。隨機權杖新增到 DNS TXT 記錄中 (DNS TXT 方法) 或 fileauth.txt 上傳到指定位置 (HTTP DCV 方法) 用於訂單的每個網域,表示您已準備好執行 DCV 檢查。使用到 DV SSL:檢查 DCV 端點的 PUT 完成。
到此端點的 PUT 傳回四種可能的回應:
invalid_dns_txt
– 找不到 DNS TXT 記錄,或包含一個或更多網域的錯誤隨機值。確認訂單上的所有網域都有附正確隨機值的適當 DNS TXT 記錄。file_random_value_not_found
– 找不到 fileauth.txt,或包含一個或更多網域的錯誤隨機值。確認檔案的訂單上的所有網域在正確目錄中、公開可用並包含正確的隨機值。invalid_dns_method
– 訂單的 DCV 方法設定為電郵。尋找已傳送的電郵,並完成 DCV 指示或變更 DCV 方法。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}}'
{
"order_status": "pending",
"certificate_id": 123456,
"dcv_status": "valid"
}
{
"errors": [
{
"code": "invalid_dns_txt",
"message": "Could not find a valid TXT record for one or more domains."
}
]
}
{
"errors": [
{
"code": "file_random_value_not_found",
"message": "Could not find the random value at the expected file location for one or more domains."
}
]
}
{
"errors": [
{
"code": "invalid_dns_method",
"message": "An error occurred while processing your request."
}
]
}
提交您的訂單和完成每個網域的 DCV 後,您將要知道訂單狀態變更和憑證何時準備好以下載。這樣做的最好方式是使用到狀態變更清單端點的 GET。
到此端點的 GET 傳回三種可能的回應:
orders
陣列) – 訂單陣列列出在指定時段中已變更狀態的所有訂單。當您的訂單狀態從擱置變成發行時,將會出現在清單中。如果傳回多份訂單,請使用訂單 ID 或憑證 ID 尋找訂單。{}
) 表示在指定的時段沒有任何訂單有狀態變更。增加時段或等待傳送另一個請求。time_frame_too_long
錯誤代碼的回應,表示 URL 查詢字串中指定的時段超過最大值。將時段減少為小於 10080 分鐘 (7 天) 的值。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}}'
{
"orders": [
{
"order_id": 112233,
"certificate_id": 123456,
"status": "issued"
}
]
}
{}
{
"errors": [
{
"code": "time_frame_too_long",
"message": "An error occurred while processing your request."
}
]
}
訂單狀態從擱置變成發行後,您的憑證已準備好可以下載。視您的需求而定,有四個您可以用於下載您的憑證的端點:
重新發行憑證允許您新增、移除或交換網域名稱、更新 CSR 或變更憑證的簽章雜湊,不需要提交新訂單。重行發行的憑證將有新憑證 ID,但訂單 ID 相同。核准重新發行後,發行新憑證且需要重新安裝。
重新發行憑證時,您需要提供這項資料:
即使上述詳細資料有一些保持不變,您仍需要將其加入重新發行要求中。
請注意,有些變更,例如加入其他 SAN ('dns_names') 可能產生額外的費用。
可能必須為其中一些或全部的網域執行 DCV。
重新發行憑證端點接受下列選用的參數:
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
}
}'
{
"id": 112233,
"requests": [
{
"id": 332211
}
]
}
{
"id": 112233,
"certificate_id": 111112
}
發行您的訂單後,您可以視需要提交撤銷憑證。
在 DigiCert 撤銷憑證前,必須由 CertCentral 中的系統管理員核准所有撤銷要求。此核准步驟是必需的,而且不可略過。
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."
}'
{
"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."
}