Using Raw Key

Shaka Packager supports raw keys, for which keys and key_ids are provided to Shaka Packager directly.

This is often used if you are managing the encryption keys yourself. It also allows you to support multi-DRM by providing custom PSSHs.

Synopsis

$ packager <stream_descriptor> ... \
  --enable_raw_key_encryption \
  --keys <key_info_string>[,<key_info_string>]... \
  [--pssh <concatenated_PSSHs>] \
  [Other options, e.g. DASH options, HLS options]

key_info_string is of the form:

label=<label>:key_id=<key_id>:key=<key>[:iv=<initialization_vector>]

Custom PSSH(s) can be provided in –pssh. If neither –pssh nor –protection_systems is specified, v1 common PSSH box is generated.

Examples

The examples below use the H264 streams created in Media Encoding.

• Example with pre-generated PSSH:

  $ packager \
    in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,drm_label=AUDIO \
    in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4,drm_label=SD \
    in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,drm_label=SD \
    in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4,drm_label=HD \
    in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,drm_label=HD \
    --enable_raw_key_encryption \
    --keys label=AUDIO:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519,label=SD:key_id=abba271e8bcf552bbd2e86a434a9a5d9:key=69eaa802a6763af979e8d1940fb88392,label=HD:key_id=6d76f25cb17f5e16b8eaef6bbf582d8e:key=cb541084c99731aef4fff74500c12ead \
    --pssh 000000317073736800000000EDEF8BA979D64ACEA3C827DCD51D21ED00000011220F7465737420636F6E74656E74206964 \
    --mpd_output h264.mpd \
    --hls_master_playlist_output h264_master.m3u8
  

• Common PSSH is generated if no PSSH or protection system flag is specified:

  $ packager \
    in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,drm_label=AUDIO \
    in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4,drm_label=SD \
    in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,drm_label=SD \
    in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4,drm_label=HD \
    in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,drm_label=HD \
    --enable_raw_key_encryption \
    --keys label=AUDIO:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519,label=SD:key_id=abba271e8bcf552bbd2e86a434a9a5d9:key=69eaa802a6763af979e8d1940fb88392,label=HD:key_id=6d76f25cb17f5e16b8eaef6bbf582d8e:key=cb541084c99731aef4fff74500c12ead \
    --mpd_output h264.mpd
  

• Example with FairPlay using ‘cbcs’ protection scheme:

  $ packager \
    in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,drm_label=AUDIO \
    in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4,drm_label=SD \
    in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,drm_label=SD \
    in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4,drm_label=HD \
    in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,drm_label=HD \
    --protection_scheme cbcs \
    --enable_raw_key_encryption \
    --keys label=AUDIO:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519:iv=11223344556677889900112233445566,label=SD:key_id=abba271e8bcf552bbd2e86a434a9a5d9:key=69eaa802a6763af979e8d1940fb88392:iv=22334455667788990011223344556677,label=HD:key_id=6d76f25cb17f5e16b8eaef6bbf582d8e:key=cb541084c99731aef4fff74500c12ead:iv=33445566778899001122334455667788 \
    --protection_systems FairPlay \
    --hls_master_playlist_output h264_master.m3u8 \
    --hls_key_uri skd://testAssetID
  

• Example with multi-drm (Widevine and PlayReady):

  $ packager \
    in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,drm_label=AUDIO \
    in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4,drm_label=SD \
    in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,drm_label=SD \
    in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4,drm_label=HD \
    in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,drm_label=HD \
    --enable_raw_key_encryption \
    --keys label=AUDIO:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519,label=SD:key_id=abba271e8bcf552bbd2e86a434a9a5d9:key=69eaa802a6763af979e8d1940fb88392,label=HD:key_id=6d76f25cb17f5e16b8eaef6bbf582d8e:key=cb541084c99731aef4fff74500c12ead \
    --protection_systems Widevine,PlayReady \
    --mpd_output h264.mpd
  

• Example with LAURL:

  $ packager \
    in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,drm_label=AUDIO \
    in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4,drm_label=SD \
    in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,drm_label=SD \
    in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4,drm_label=HD \
    in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,drm_label=HD \
    --enable_raw_key_encryption \
    --keys label=AUDIO:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519,label=SD:key_id=abba271e8bcf552bbd2e86a434a9a5d9:key=69eaa802a6763af979e8d1940fb88392,label=HD:key_id=6d76f25cb17f5e16b8eaef6bbf582d8e:key=cb541084c99731aef4fff74500c12ead \
    --protection_systems PlayReady \
    --playready_extra_header_data '<LAURL>https://example.com/pr</LAURL>' \
    --mpd_output h264.mpd
  

Note

Users are responsible for setting up the license servers and managing keys there unless they are using a cloud service provided by the DRM provider or third_parties.

Refer to player setup on how to config the DRM in Shaka Player.

Test vectors used in this tutorial

Key ID:

SD: abba271e8bcf552bbd2e86a434a9a5d9

HD: 6d76f25cb17f5e16b8eaef6bbf582d8e

AUDIO: f3c5e0361e6654b28f8049c778b23946

Key ID must be 16 bytes or 32 digits in HEX.

Key:

SD: 69eaa802a6763af979e8d1940fb88392

HD: cb541084c99731aef4fff74500c12ead

AUDIO: a4631a153a443df9eed0593043db7519

Key must be 16 bytes or 32 digits in HEX.

Widevine PSSH:

The PSSH 00000031707373… is generated using pssh-box script:

$ pssh-box.py --widevine-system-id \
  --content-id 7465737420636f6e74656e74206964 --hex

Configuration options

DRM related Stream descriptor fields

skip_encryption=0|1:

Optional. Defaults to 0 if not specified. If it is set to 1, no encryption of the stream will be made.

drm_label:

Optional value for custom DRM label, which defines the encryption key applied to the stream. Typically values include AUDIO, SD, HD, UHD1, UHD2. For raw key, it should be a label defined in –keys. If not provided, the DRM label is derived from stream type (video, audio), resolutions, etc. Note that it is case sensitive.

General encryption options

--protection_scheme <scheme>

Specify a protection scheme, ‘cenc’ or ‘cbc1’ or pattern-based protection schemes ‘cens’ or ‘cbcs’.

--crypt_byte_block

Specify the count of the encrypted blocks in the protection pattern, where block is of size 16-bytes.

There are three common patterns (crypt_byte_block:skip_byte_block): 1:9 (default), 5:5, 10:0.

Apply to video streams with ‘cbcs’ and ‘cens’ protection schemes only; ignored otherwise.

--skip_byte_block

Specify the count of the unencrypted blocks in the protection pattern.

Apply to video streams with ‘cbcs’ and ‘cens’ protection schemes only; ignored otherwise.

--vp9_subsample_encryption, --novp9_subsample_encryption

Enable / disable VP9 subsample encryption. Enabled by default.

--clear_lead <seconds>

Clear lead in seconds if encryption is enabled. Shaka Packager does not support partial encrypted segments, all the segments including the partial segment overlapping with the initial ‘clear_lead’ seconds are not encrypted, with all the following segments encrypted. If segment_duration is greater than ‘clear_lead’, then only the first segment is not encrypted. Default: 5

--protection_systems

Protection systems to be generated. Supported protection systems include Widevine, PlayReady, FairPlay, Marlin, and CommonSystem.

--playready_extra_header_data <string>

Extra XML data to add to PlayReady PSSH data. Can be specified even if using another key source.

Raw key encryption options

--enable_raw_key_encryption

Enable encryption with raw key (keys provided in command line)). This generates Common protection system if neither –pssh nor –protection_systems is specified. Use –pssh to provide custom protection systems or use –protection_systems to generate protection systems automatically.

--enable_raw_key_decryption

Enable decryption with raw key (keys provided in command line).

--keys <key_info_string[,key_info_string][,key_info_string]…>

key_info_string is of the form:

label=<label>:key_id=<key_id>:key=<key>[:iv=<initialization_vector>]

label can be an arbitrary string or a predefined DRM label like AUDIO, SD, HD, etc. Label with an empty string indicates the default key and key_id. The drm_label in Stream descriptors, which can be implicit, determines which key info is applied to the stream by matching the drm_label with the label in key info.

key_id and key should be 32-digit hex strings.

initialization_vector is an optional IV with the same format and semantics as the parameter for the –iv option below. This is mutually exclusive with that option.

--iv <16-digit or 32-digit hex string>

IV in hex string format. If not specified, a random IV will be generated. This flag should only be used for testing. IV must be either 8 bytes (16 digits HEX) or 16 bytes (32 digits in HEX).

--pssh <hex string>

One or more concatenated PSSH boxes in hex string format. If neither this flag nor –protection_systems is specified, a v1 common PSSH box will be generated.

pssh-box (Utility to generate PSSH boxes)

https://github.com/shaka-project/shaka-packager/tree/main/packager/tools/pssh