Skip to main content

SPEKE Key ID Override

Context​

SPEKE (Secure Packager and Encoder Key Exchange) is an open protocol defined by AWS that allows packagers to acquire encryption keys from a DRM key service. It is based on CPIX, which means, a caller would create an XML template describing all the necessary keys, and assigning a Key ID (GUID) to each key and submit this template to the key service. The key service inserts the generated keys into the same document and returns the augmented document back. The packager then uses the keys to encrypt the content.

Many packagers these days decide to use SPEKE for key acquisition.

Problem​

In an attempt to make the process as simple as possible for the users, some packagers treat the Key ID as an internal detail and do not expose it to the users. Users, however, need the value of the Key IDs so that later an entitlement can be granted for an end user to access a specific Key ID.

The Key ID can later be extracted from a generated manifest file, but this is sometimes inconvenient and can only be done after packaging is completed.

The problem is especially severe, as the AWS Elemental services including (MediaConvert and MediaPackage) do not expose the Key ID.

Solution: Key ID Override​

Axinom Key Service provides a Key ID Override feature.

If activated, the key service will ignore the Key ID (kid) in the key request replacing it with a value generated according to a known published algorithm, making it possible to the users to compute them themselves instead of getting them from the packager.

The algorithm implemented by the Axinom DRM Key Service is described below.

Also, code samples are available for implementing the algorithm in a few popular languages.

Such behavior is supported by the SPEKE specification:

It [the requestor] passes the KID to the DRM key provider in its requests. Almost always, the key provider responds using the same KID, but it can provide a different value for the KID in the response.

Implementors of the SPEKE client functionality should consider the override possibility and be prepared to handle deviating Key IDs in the response.

warning

Before using this feature, make sure your packager supports the overriding behavior. If it is not described in the vendor’s documentation, you can run the packaging with and without the override feature and compare the Key IDs added to the manifest file.

Caution

Currently, AWS MediaConvert don’t support Key ID override with SPEKE v1. We recommend to use SPEKE v2 instead.

Activating the Key ID Override Functionality​

Append the following parameter to the key service Url: overrideKeyIds=true.

For example:

For SPEKE v1:
https://key-server-management.axprod.net/api/Speke?overrideKeyIds=true

For SPEKE v2:
https://key-server-management.axprod.net/api/SpekeV2?overrideKeyIds=true

Key ID Derivation Algorithm​

Essentially, we take all the input parameters contributing to the uniqueness of the Key ID, compute a SHA256 hash of them, and then XOR the first and second halves of the hash to reduce the output to 128 bits. The resulting 128 bits are then converted to a GUID.

The input parameters for the algorithm slightly vary for SPEKE v1 and SPEKE v2.

All the parameters are string values.

Common parameters for SPEKE v1 and SPEKE v2:

  • TenantId - Customer’s Axinom DRM Tenant ID (to be found under My Mosaic / DRM / Key Service configuration).
  • Content ID - The identifier of a video asset or a stream. It’s called "Resource ID" in AWS MediaConvert and MediaPackage. In the request CPIX, it is the id attribute of the root cpix:CPIX element for SPEKE v1 and the contentId attribute for SPEKE v2.
  • Content Key Period Index - When key rotation is enabled, each SPEKE key request contains a zero-based sequential period index number. Use "0" when no key rotation is enabled/supported.

SPEKE v1 specific parameters:

  • Key ID Index - the Key ID index in the request. Should be set to "0", as the SPEKE v1 protocol specifies only one key per request.
tip

Axinom implementation supports multiple keys even with SPEKE v1 request, therefore, a non-zero value can also be set for multiple keys.

SPEKE v2 specific parameters:

  • Protection Scheme - "cenc" or "cbcs" encryption scheme used for packaging content.
  • Intended Track Type - When multiple keys are requested, the intended-track-type shall be set.
tip

For example, AWS sets "VIDEO" for the first content key and "AUDIO" for the second content key.

The algorithm is as follows:

For SPEKE v1: InputParameters = "<TenantId>" + "<Content ID>" + "<Content Key Period Index>" + "<Key ID Index>"

For SPEKE v2: InputParameters = "<TenantId>" + "<Content ID>" + "<Protection Scheme>" + "<Content Key Period Index>" + "<Intended Track Type>"

BaseHash = SHA256(InputParameters)

PartOneHash = Take first 16 bytes of BaseHash

PartTwoHash = Take the last 16 bytes of BaseHash

XorResult = PartOneHash XOR PartTwoHash

Key ID = XorResult to GUID // GUID must be generated using little-endian byte order as in Microsoft .NET.

Sample Key Derivation Algorithm Implementation​

See SPEKE Key ID Override Samples.

Packager-specific considerations​

AWS MediaConvert and MediaPackage​

AWS tools do support the Key ID override functionality, however only if SPEKE v2 is used. With SPEKE v1 the Key ID override is not supported.

warning

At the time of writing, the SPEKE v2 protocol is only supported by AWS MediaPackage; not by MediaConvert.

Protection Scheme​

Currently, AWS doesn’t allow to set the protection scheme explicitly. Therefore, DASH-ISO packaging will always result in "cenc" and Apple HLS and CMAF will result in "cbcs" being applied.

Key Rotation and Content Key Periods​

When key rotation is enabled, the AWS MediaPackage requests a Key ID from the SPEKE v1 endpoint on regular intervals. For example, if the key rotation interval is set to 3600 (in seconds - equals 1 hour), AWS MediaPackage sends a new request every hour.

When the Key ID Override functionality is activated, the Key IDs are overridden based on their content key period index. With each request Content Key Period the index will increase by 1 (starting at "0").

For example:

<cpix:ContentKeyPeriod id="keyPeriod_22ebd583-732e-4ab3-9393-7ad173355736" index="0"/>

<cpix:ContentKeyPeriod id="keyPeriod_22ebd583-732e-4ab3-9393-7ad173355736" index="1"/>

<cpix:ContentKeyPeriod id="keyPeriod_22ebd583-732e-4ab3-9393-7ad173355736" index="2"/>

...

<cpix:ContentKeyPeriod id="keyPeriod_22ebd583-732e-4ab3-9393-7ad173355736" index="999"/>

It is up to the user to map the indexes and thereby the generated Key IDs to specific time periods, if necessary. For example, the user could do it based on knowing the key rotation period and the stream start time.

Request Variations regarding Content Key Periods​

MediaConvert and MediaPackage form their SPEKE v1 requests slightly differently:

The MediaConvert service (which is used to encode VOD content) does not contain any ContentKeyPeriod elements in the request which is used in key rotation. Therefore, when deriving the KID, use "0" for the contentKeyPeriodIndex value as the SPEKE v1 endpoint assumes the content key period index as zero when not present.

The MediaPackage service which also provides key rotation functionality always contains a ContentKeyPeriod element with the index "0" even if key rotation is not enabled Therefore, when key rotation is disabled, both MediaConvert and MediaPackage get the same overridden Key ID from the Axinom Key Service SPEKE v1 endpoint.

Parameters mapping to the AWS User Interface​

Following is a sample screenshot from AWS MediaPackage which shows where input parameters needed for the key derivation algorithm are configured.

Sample encryption settings used in AWS:

AWS user intercace - screenshot

Configuring AWS - screenshot

Based on above settings the following values are to be used for the key derivation algorithm:

  • Tenant ID: customer’s Axinom DRM Key Service Tenant ID (can be found under My Mosaic / DRM / Key Service Configuration).
  • Content ID: "test_content"
  • Protection Scheme:
    • "cenc" for "Live DASH-ISO" packaging type
    • "cbcs" for "Live CMAF Apple HLS" packaging type
  • Content Key Period Index: "0" (Since key rotation is disabled)
  • Intended Track Type for key one: "VIDEO"
  • Intended Track Type for key two: "AUDIO"
note

AWS only supports two keys in the request currently. All video streams will use the first key, and all audio streams will use the second key. Therefore, the intended track type will always have the above values.

Alternative Solutions​

Instead of changing the Key ID in the Key Service, one could set up a proxy between the packager and the Key Service that would intercept the requests and store the Key ID before it is forwarded to the Key Service.

See SPEKE Key ID Extraction.

See also​