本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# SPEKE API v2 - DASH-IF 規格的自訂和限制
<a name="speke-constraints-v2"></a>

DASH 產業論壇 [CPIX 2.3 規格](https://dashif.org/docs/CPIX2.3/Cpix.html)支援多種使用案例和拓撲。SPEKE API v2.0 規格同時定義 CPIX 設定檔和 CPIX 的 API。為了實現這兩個目標，它遵循具有下列自訂和限制條件的 CPIX 規格：

**CPIX 設定檔**
+ SPEKE 遵循 Encryptor Consumer 工作流程。
+ 對於加密的內容金鑰，SPEKE 會套用下列限制：
  + SPEKE 不支援請求或回應承載的數位簽章驗證 (XMLDSIG)。
  + SPEKE 需要 2048 RSA 型憑證。
+ SPEKE 只會利用一部分的 CPIX 功能：
  + SPEKE 會省略`UpdateHistoryItemList`功能。如果回應中存在清單，SPEKE 會忽略該清單。
  + SPEKE 會省略根/分葉金鑰功能。如果`ContentKey@dependsOnKey`屬性存在於回應中，SPEKE 會忽略該屬性。
  + SPEKE 會省略 `BitrateFilter`元素和 `VideoFilter@wcg` 屬性。如果 CPIX 承載中存在這些元素或屬性，則 SPEKE 會忽略它。
+ 只有[標準承載元件頁面](standard-payload-components-v2.md)或[加密合約頁面](encryption-contract-v2.md)中參考為「支援」的元素或屬性，才能用於與 SPEKE v2 交換的 CPIX 文件。
+ 當加密程式包含在 CPIX 請求中時，所有元素和屬性都應在金鑰提供者 CPIX 回應中包含有效值。如果沒有，加密程式應停止並擲回錯誤。
+ SPEKE 支援具有 `KeyPeriodFilter` 元素的金鑰輪換。SPEKE 僅使用 `ContentKeyPeriod@index`來追蹤金鑰期間。
+ 對於 HLS 訊號，必須使用多個`DRMSystem.HLSSignalingData`元素：一個`DRMSystem.HLSSignalingData@playlist`屬性值為「媒體」，另一個`DRMSystem.HLSSignalingData@playlist`屬性值為「主要」。
+ 當請求金鑰時，加密程式必須使用 `ContentKey` 元素上的可選 `@explicitIV` 屬性。金鑰提供者可以使用 `@explicitIV` 來回應 IV，即使該屬性未包含在請求中。
+ 加密程式會建立金鑰識別符 (`KID`)，無論任何指定的內容 ID 和金鑰期間都將提供相同識別符。金鑰提供者會在對請求文件的回應中包括 `KID`。
+ 加密程式應包含 `CPIX@contentId` 屬性的值。接收此屬性的空值時，金鑰提供者應傳回描述為「缺少 CPIX@contentId」的錯誤。 `CPIX@contentId`值無法由金鑰提供者覆寫。

   `CPIX@id` 如果不是 null，則金鑰提供者應忽略 值。
+ 加密程式應包含 `CPIX@version` 屬性的值。收到此屬性的空值時，金鑰提供者應傳回描述為「缺少 CPIX@version」的錯誤。收到具有不支援版本的請求時，金鑰提供者傳回的錯誤描述應為「不支援的 CPIX@version」。

   `CPIX@version` 值無法由金鑰提供者覆寫。
+ 加密程式應為每個請求的金鑰包含 `ContentKey@commonEncryptionScheme` 屬性的值。接收此屬性的空值時，金鑰提供者應傳回描述為 'Missing ContentKey@commonEncryptionScheme for KID ' `id` 的錯誤。

  唯一的 CPIX 文件不能混合不同`ContentKey@commonEncryptionScheme`屬性的多個值。接收這類組合時，金鑰提供者應傳回描述為「不合規 ContentKey@commonEncryptionScheme 組合」的錯誤。

  並非所有`ContentKey@commonEncryptionScheme`值都與所有 DRM 技術相容。接收這類組合時，金鑰提供者應傳回描述為 'ContentKey@commonEncryptionScheme 與 DRMSystem `id` ' 不相容的錯誤。

   `ContentKey@commonEncryptionScheme` 值無法由金鑰提供者覆寫。
+ 在 CPIX 回應內文中接收 `DRMSystem@PSSH`和 `DRMSystem.ContentProtectionData` innerXML `<pssh>`元素的不同值時，加密程式應停止並擲回錯誤。 innerXML 

**CPIX 的 API**
+ 金鑰提供者應包含 `X-Speke-User-Agent` HTTP 回應標頭的值。
+ 符合 SPEKE 的加密程式做為用戶端，並將 POST 操作傳送至金鑰提供者端點。
+ 加密程式應包含 `X-Speke-Version` HTTP 請求標頭的值，搭配請求使用的 SPEKE 版本，配方為 MajorVersion.MinorVersion,例如 SPEKE v2.0 的 '2.0'。如果金鑰提供者不支援加密程式用於目前請求的 SPEKE 版本，金鑰提供者應傳回描述為「不支援的 SPEKE 版本」的錯誤，且不會盡力處理 CPIX 文件。

  在回應請求時，金鑰提供者無法修改加密程式定義的`X-Speke-Version`標頭值。
+ 在回應內文中收到錯誤時，加密程式應該擲回錯誤，而不是使用 SPEKE v1.0 版本控制重試請求。

  如果金鑰提供者未傳回錯誤，但無法傳回包含必要資訊的 CPIX 文件，加密程式應停止並擲回錯誤。

下表摘要說明 金鑰提供者必須在訊息內文中傳回的標準訊息。錯誤情況下的 HTTP 回應碼應為 4XX 或 5XX，絕不應為 200。422 錯誤代碼可用於與 SPEKE/CPIX 相關的所有錯誤。


| 錯誤案例 | 錯誤訊息 | 
| --- | --- | 
|  未定義 CPIX@contentId   |  缺少 CPIX@contentId  | 
|  CPIX@version 未定義  |  缺少 CPIX@version  | 
|  不支援 CPIX@version  |  不支援的 CPIX@version  | 
|  未定義 ContentKey@commonEncryptionScheme   |  缺少 KID 的 ContentKey@commonEncryptionScheme `id`（其中 `id`等於 ContentKey@kid 值）  | 
|  單一 CPIX 文件中使用的多個 ContentKey@commonEncryptionScheme 值  |  不合規的 ContentKey@commonEncryptionScheme 組合  | 
|  ContentKey@commonEncryptionScheme 與 DRM 技術不相容  |  ContentKey@commonEncryptionScheme 與 DRMSystem 不相容 `id`（其中 `id`等於 DRMSystem@systemId 值）  | 
|  X-Speke-Version 標頭值不是支援的 SPEKE 版本  |  不支援的 SPEKE 版本  | 
|  加密合約格式錯誤  |  格式不正確的加密合約  | 
|  加密合約與 DRM 安全層級限制條件相衝突  |  不支援請求的 CPIX 加密合約  | 
|  加密合約不包含任何 VideoFilter 或 AudioFilter 元素  |  缺少 CPIX 加密合約  |