SPEKE API v2 - Customizations and constraints to the DASH-IF specification

SPEKE follows the Encryptor Consumer workflow.

For encrypted content keys, SPEKE applies the following restrictions:

SPEKE leverages only a subset of CPIX functionalities:

Only the elements or attributes referenced as 'Supported' on the Standard Payload Components page or the Encryption contract page can be used in CPIX documents exchanged with SPEKE v2.

When included in a CPIX request by the encryptor, all elements and attributes shall carry a valid value in the key provider CPIX response. If not, the encryptor shall stop and throw an error.

SPEKE supports key rotation with KeyPeriodFilter elements. SPEKE uses only the ContentKeyPeriod@index to track the key period.

For HLS signaling, multiple DRMSystem.HLSSignalingData elements must be used: one with a DRMSystem.HLSSignalingData@playlist attribute value of ‘media’, and another one with a DRMSystem.HLSSignalingData@playlist attribute value of ‘master’.

When requesting keys, the encryptor might use the optional @explicitIV attribute on the ContentKey element. The key provider can respond with an IV using @explicitIV, even if the attribute is not included in the request.

The encryptor creates the key identifier (KID), which stays the same for any given content ID and key period. The key provider includes the KID in its response to the request document.

The encryptor shall include a value for the CPIX@contentId attribute. When receiving an empty value for this attribute, the key provider shall return an error with description 'Missing CPIX@contentId'. CPIX@contentId value cannot be overriden by the key provider.

CPIX@id value, if not null, shall be ignored by the key provider.

The encryptor shall include a value for the CPIX@version attribute. When receiving an empty value for this attribute, the key provider shall return an error with description 'Missing CPIX@version'. When receiving a request with an unsupported version, the error description returned by the key provider shall be 'Unsupported CPIX@version'.

CPIX@version value cannot be overriden by the key provider.

The encryptor shall include a value for the ContentKey@commonEncryptionScheme attribute for each requested key. When receiving an empty value for this attribute, the key provider shall return an error with description 'Missing ContentKey@commonEncryptionScheme for KID id '.

A unique CPIX document cannot mix multiple values for different ContentKey@commonEncryptionScheme attributes. When receiving such a combination, the key provider shall return an error with description 'Non compliant ContentKey@commonEncryptionScheme combination'.

Not all ContentKey@commonEncryptionScheme values are compatible with all DRM technologies. When receiving such a combination, the key provider shall return an error with description 'ContentKey@commonEncryptionScheme non compatible with DRMSystem id '.

ContentKey@commonEncryptionScheme value cannot be overriden by the key provider.

When receiving different values for DRMSystem@PSSH and DRMSystem.ContentProtectionData innerXML <pssh> element in the CPIX response body, the encryptor shall stop and throw an error.

The key provider shall include a value for the X-Speke-User-Agent HTTP response header.

A SPEKE-compliant encryptor acts as a client and sends POST operations to the key provider endpoint.

The encryptor shall include a value for the X-Speke-Version HTTP request header, with the SPEKE version used with the request, formulated as MajorVersion.MinorVersion, like '2.0' for SPEKE v2.0. If the key provider doesn’t support the SPEKE version used by the encryptor for the current request, the key provider shall return an error with description 'Unsupported SPEKE version' and not try to process the CPIX document on a best effort basis.

The X-Speke-Version header value defined by the encryptor cannot be modified by the key provider in the response to the request.

When receiving errors in the response body, the encryptor shall throw an error and not retry the request with a SPEKE v1.0 versioning.

If the key provider doesn’t return an error but fails to return a CPIX document that includes the mandatory information, the encryptor should stop and throw an error.