DRM¶

drm:ingest-speke2¶

Retrieves DRM content keys (and their IVs) via SPEKE v2.0 (Secure Packager and Encoder Key Exchange). The tool builds a CPIX 2.3 request document that lists the desired key IDs and encryption scheme (without key material), POSTs it to the SPEKE key server, and parses the key server’s response, which fills in the content keys, IVs and the requested DRM signaling data (PSSH boxes, DASH ContentProtectionData, HLS signaling, PlayReady header data).

Authorization is optional and off by default, and three methods are supported: AWS SigV4 (use_sigv4, optionally assuming role_arn; falls back to the worker’s own AWS credentials otherwise), a custom header (api_key_header_name / api_key_header_value), and HTTP Basic auth (basic_auth_user / basic_auth_password). extra_headers covers anything else a particular endpoint might need.

Not every key server supports every DRM system; if the server doesn’t return signaling data for one of the requested drm_systems, the corresponding env vars are simply omitted for that DRM system.

Not every key server honors the key_id given in a content_keys entry either – castLabs DRMtoday, for example, always mints its own kid regardless of what was requested. Response content keys are therefore matched back to content_keys by list order, not by kid; the tool fails if the key server returns a different number of content keys than were requested.

The tool always exports these environment variables per requested key ([label] is the lowercased track_type, e.g. video/audio, de-duplicated with a numeric suffix if the same track type is used more than once). The _asset_id/_hex/_id_hex/_iv_hex suffixes deliberately mirror the ones drmtoday:ingest-cenc-key exports, so [env_prefix]_[label] can be passed straight into a shaka:package task’s drmkeys entry as key_env_prefix, or the individual {[env_prefix]_[label]_hex} / {..._id_hex} / {..._iv_hex} placeholders can be used directly wherever a key is needed:

• [env_prefix]_[label]_asset_id: the content_id used for the request

• [env_prefix]_[label]_id_uuid: the key id as dashed UUID string

• [env_prefix]_[label]_id_hex: the key id as hex string (no dashes)

• [env_prefix]_[label]_id_base64: the key id as base64 string

• [env_prefix]_[label]_base64: the content key as base64 string

• [env_prefix]_[label]_hex: the content key as hex string

• [env_prefix]_[label]_iv_base64: the IV as base64 string (if returned by the key server)

• [env_prefix]_[label]_iv_hex: the IV as hex string (if returned by the key server)

• [env_prefix]_[label]_scheme: the encryption scheme confirmed by the key server

For each requested DRM system ([drm] is wv/pr/fp for Widevine/PlayReady/FairPlay) that the key server returned data for:

• [env_prefix]_[label]pssh[drm]_base64 / _hex: the PSSH box

• [env_prefix]_[label]cpd[drm]_base64: the DASH cpix:ContentProtectionData

• [env_prefix]_[label]mss[drm]_base64: the Smooth Streaming protection header data (PlayReady only)

• [env_prefix]_[label]hls_media[drm]_base64 / _txt: the HLS media playlist signaling data

• [env_prefix]_[label]hls_master[drm]_base64 / _txt: the HLS master playlist signaling data

Example. key_id is optional per entry – when omitted, a random key id is generated, which is the common case since it’s the key server that ties a key to a kid, not the caller:

{
"parameters": {
    "endpoint_url": "https://{gateway_id}.execute-api.{region}.amazonaws.com/{stage}/speke/v2",
    "content_id": "vtk_integration_test_{job_id}",
    "content_keys": [
        {"track_type": "VIDEO"},
        {"track_type": "AUDIO"}
    ],
    "encryption_scheme": "cbcs",
    "env_prefix": "key"
},
"tool": "drm:ingest-speke2"
}

A SPEKE v2.0 endpoint that additionally requires AWS SigV4 authorization (an API Gateway with an AWS_IAM authorizer), supports PlayReady, and pins an explicit key_id for one of the two keys:

{
"parameters": {
    "endpoint_url": "https://{gateway_id}.execute-api.{region}.amazonaws.com/{stage}/speke/v2",
    "content_id": "vtk_integration_test_{job_id}",
    "content_keys": [
        {"track_type": "HD", "key_id": "fa3d215e-14e0-4c0e-b6a1-cffb0e2f2b0a"},
        {"track_type": "AUDIO"}
    ],
    "encryption_scheme": "cbcs",
    "drm_systems": ["WIDEVINE", "PLAYREADY", "FAIRPLAY"],
    "use_sigv4": true,
    "role_arn": "arn:aws:iam::{customer_account_id}:role/{role_that_trusts_this_worker}",
    "env_prefix": "key"
},
"tool": "drm:ingest-speke2"
}

Chained into a shaka:package task via key_env_prefix (with env_prefix: "key" above, the video/audio labels become key_video/key_audio):

{
"parameters": {
    "drmkeys": [
        {"key_label": "video_key_01", "key_streamtype": "HD", "key_env_prefix": "key_video"},
        {"key_label": "audio_key_01", "key_streamtype": "AUDIO", "key_env_prefix": "key_audio"}
    ]
},
"tool": "shaka:package"
}