Dolby Hybrik DRM Packaging Integration Guide

Overview

This document describes how to integrate DRM encryption packaging in Dolby Hybrik encoder using PallyCon CPIX API.

The CPIX API is according to the Content Protection Information Exchange Format (CPIX) Standard Guide defined by the DASH Industry Forum. It defines the integration standard for the key exchange required to apply multi-DRM in the packaging process.

For more information about Hybrik encoder and PallyCon CPIX API, please refer to the links below.

Prerequisite

In order to follow the instructions in this document, you will need to have the following ready:

Dolby Hybrik account
Cloud Storage (Amazon S3 or Google Cloud Storage)
PallyCon service account
Basic knowledge about general HTTP API

Hybrik JSON example for DRM integration can be downloaded from Download page.

Step 1: Getting DRM Encryption Key

To perform DRM content encryption with Hybrik, you must first generate the encryption keys. You need to call PallyCon CPIX API as follows to generate encryption key and related data for each DRM.

The guide below is about calling the PallyCon CPIX API with an API test tool such as Postman. If you want to call the CPIX API through server programming such as Java, please refer to corresponding sample and guide document.

Requesting Widevine/PlayReady Key

The API test tool or server application calls the following PallyCon KMS server URL as specified in PallyCon CPIX API Guide. The {enc-token} part of the URL should be replaced with the value of the KMS token issued to the PallyCon service account. (Shown on PallyCon Console > Multi-DRM > DRM Settings screen)

https://kms.pallycon.com/v2/cpix/pallycon/getKey/{enc-token}

When calling the above URL, the following XML should be input in the HTTP Body (Content) part. You must replace the your-content-id value in the <cpix:CPIX id= part with the unique ID (CID) of the content to be packaged.

<?xml version="1.0" encoding="UTF-8"?>
<cpix:CPIX id="your-content-id" xmlns:cpix="urn:dashif:org:cpix" xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc"
    xmlns:speke="urn:aws:amazon:com:speke">
    <cpix:ContentKeyList>
        <cpix:ContentKey kid="key1" />
    </cpix:ContentKeyList>
    <cpix:DRMSystemList>
        <cpix:DRMSystem kid="key1" systemId="9a04f079-9840-4286-ab92-e65be0885f95" />
        <cpix:DRMSystem kid="key1" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed" />
    </cpix:DRMSystemList>
</cpix:CPIX>

The kid input value is used to distinguish the key to be issued for each track of multi-key packaging. In the case of single-key packaging, the same arbitrary value can be entered as in the example above.
In the systemId input value, enter a unique DRM System ID corresponding to PlayReady and Widevine as in the example.

If the KMS token and XML body are entered properly, the following response is returned for the HTTP POST request.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cpix:CPIX id="your-content-id" xmlns:cpix="urn:dashif:org:cpix" xmlns:enc="http://www.w3.org/2001/04/xmlenc#"
    xmlns:speke="urn:aws:amazon:com:speke" xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <cpix:ContentKeyList>
        <cpix:ContentKey explicitIV="N2Nyb2FobXRoY2hleDR6MA==" kid="f1d127a8-acfb-6fd2-dfa3-4d1af96770dc">
            <cpix:Data>
                <pskc:Secret>
                    <pskc:PlainValue>MITtRBJYxy1Z7UVCQFLHvA==</pskc:PlainValue>
                </pskc:Secret>
            </cpix:Data>
        </cpix:ContentKey>
    </cpix:ContentKeyList>
    <cpix:DRMSystemList>
        <cpix:DRMSystem kid="f1d127a8-acfb-6fd2-dfa3-4d1af96770dc" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
            <cpix:ContentProtectionData>CAESEPHRJ6is+2/S36NNGvlncNwaDGlua2FlbnR3b3JrcyIKdGVzdC1jaWQtMQ==
            </cpix:ContentProtectionData>
            <cpix:PSSH>
                AAAATnBzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAAC4IARIQ8dEnqKz7b9Lfo00a+Wdw3BoMaW5rYWVudHdvcmtzIgp0ZXN0LWNpZC0x
            </cpix:PSSH>
        </cpix:DRMSystem>
        <cpix:DRMSystem kid="f1d127a8-acfb-6fd2-dfa3-4d1af96770dc" systemId="9a04f079-9840-4286-ab92-e65be0885f95">
            <cpix:ContentProtectionData>
                cgIAAAEAAQBoAjwAVwBSAE0ASABFAEEARABFAFIAIAB4AG0AbABuAHMAPQAiAGgAdAB0AHAAOgAvAC8AcwBjAGgAZQBtAGEAcwAuAG0AaQBjAHIAbwBzAG8AZgB0AC4AYwBvAG0ALwBEAFIATQAvADIAMAAwADcALwAwADMALwBQAGwAYQB5AFIAZQBhAGQAeQBIAGUAYQBkAGUAcgAiACAAdgBlAHIAcwBpAG8AbgA9ACIANAAuADIALgAwAC4AMAAiAD4APABEAEEAVABBAD4APABQAFIATwBUAEUAQwBUAEkATgBGAE8APgA8AEsASQBEAFMAPgA8AEsASQBEACAAQQBMAEcASQBEAD0AIgBBAEUAUwBDAFQAUgAiACAAQwBIAEUAQwBLAFMAVQBNAD0AIgBrAHUAcQBZAG8AMQBOAEkAbwBvADgAPQAiACAAVgBBAEwAVQBFAD0AIgBxAEMAZgBSADgAZgB1AHMAMABtAC8AZgBvADAAMABhACsAVwBkAHcAMwBBAD0APQAiAD4APAAvAEsASQBEAD4APAAvAEsASQBEAFMAPgA8AC8AUABSAE8AVABFAEMAVABJAE4ARgBPAD4APABMAEEAXwBVAFIATAA+AGgAdAB0AHAAcwA6AC8ALwBsAGkAYwBlAG4AcwBlAC4AcABhAGwAbAB5AGMAbwBuAC4AYwBvAG0ALwByAGkALwBsAGkAYwBlAG4AcwBlAE0AYQBuAGEAZwBlAHIALgBkAG8APAAvAEwAQQBfAFUAUgBMAD4APAAvAEQAQQBUAEEAPgA8AC8AVwBSAE0ASABFAEEARABFAFIAPgA=
            </cpix:ContentProtectionData>
            <cpix:PSSH>
                AAACknBzc2gAAAAAmgTweZhAQoarkuZb4IhflQAAAnJyAgAAAQABAGgCPABXAFIATQBIAEUAQQBEAEUAUgAgAHgAbQBsAG4AcwA9ACIAaAB0AHQAcAA6AC8ALwBzAGMAaABlAG0AYQBzAC4AbQBpAGMAcgBvAHMAbwBmAHQALgBjAG8AbQAvAEQAUgBNAC8AMgAwADAANwAvADAAMwAvAFAAbABhAHkAUgBlAGEAZAB5AEgAZQBhAGQAZQByACIAIAB2AGUAcgBzAGkAbwBuAD0AIgA0AC4AMgAuADAALgAwACIAPgA8AEQAQQBUAEEAPgA8AFAAUgBPAFQARQBDAFQASQBOAEYATwA+ADwASwBJAEQAUwA+ADwASwBJAEQAIABBAEwARwBJAEQAPQAiAEEARQBTAEMAVABSACIAIABDAEgARQBDAEsAUwBVAE0APQAiAGsAdQBxAFkAbwAxAE4ASQBvAG8AOAA9ACIAIABWAEEATABVAEUAPQAiAHEAQwBmAFIAOABmAHUAcwAwAG0ALwBmAG8AMAAwAGEAKwBXAGQAdwAzAEEAPQA9ACIAPgA8AC8ASwBJAEQAPgA8AC8ASwBJAEQAUwA+ADwALwBQAFIATwBUAEUAQwBUAEkATgBGAE8APgA8AEwAQQBfAFUAUgBMAD4AaAB0AHQAcABzADoALwAvAGwAaQBjAGUAbgBzAGUALgBwAGEAbABsAHkAYwBvAG4ALgBjAG8AbQAvAHIAaQAvAGwAaQBjAGUAbgBzAGUATQBhAG4AYQBnAGUAcgAuAGQAbwA8AC8ATABBAF8AVQBSAEwAPgA8AC8ARABBAFQAQQA+ADwALwBXAFIATQBIAEUAQQBEAEUAUgA+AA==
            </cpix:PSSH>
        </cpix:DRMSystem>
    </cpix:DRMSystemList>
</cpix:CPIX>

For a detailed description of the above request and response example data, see the corresponding guide document.

Requesting FairPlay Key

In the same way as PlayReady/Widevine key request, you may send the following request data to the KMS server.

<?xml version="1.0" encoding="UTF-8"?>
<cpix:CPIX id="your-content-id" xmlns:cpix="urn:dashif:org:cpix" xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc" xmlns:speke="urn:aws:amazon:com:speke">
 <cpix:ContentKeyList>
     <cpix:ContentKey kid="key1"></cpix:ContentKey>
 </cpix:ContentKeyList>
 <cpix:DRMSystemList>
    <cpix:DRMSystem kid="key1" systemId="94ce86fb-07ff-4f43-adb8-93d2fa968ca2" />
 </cpix:DRMSystemList>
</cpix:CPIX>

The systemId value in the example above is the system ID for FairPlay DRM. (fixed value)

The response to the above request data example is as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cpix:CPIX id="your-content-id" xmlns:cpix="urn:dashif:org:cpix" xmlns:enc="http://www.w3.org/2001/04/xmlenc#" xmlns:speke="urn:aws:amazon:com:speke" xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <cpix:ContentKeyList>
        <cpix:ContentKey explicitIV="N2Nyb2FobXRoY2hleDR6MA==" kid="cfb7a0e1-c5c5-62df-6e32-dcaebcc8739b">
            <cpix:Data>
                <pskc:Secret>
                    <pskc:PlainValue>olwzn1wU8oHCxjWY1C6oyQ==</pskc:PlainValue>
                </pskc:Secret>
            </cpix:Data>
        </cpix:ContentKey>
    </cpix:ContentKeyList>
    <cpix:DRMSystemList>
        <cpix:DRMSystem kid="cfb7a0e1-c5c5-62df-6e32-dcaebcc8739b" systemId="94ce86fb-07ff-4f43-adb8-93d2fa968ca2">
            <cpix:HLSSignalingData>I0VYVC1YLUtFWTpNRVRIT0Q9U0FNUExFLUFFUyxVUkk9c2tkOi8vejdlZzRjWEZZdDl1TXR5dXZNaHptdz09</cpix:HLSSignalingData>
            <cpix:HLSSignalingData playlist="master">I0VYVC1YLVNFU1NJT04tS0VZOk1FVEhPRD1TQU1QTEUtQUVTLFVSST1za2Q6Ly96N2VnNGNYRll0OXVNdHl1dk1oem13PT0=</cpix:HLSSignalingData>
            <cpix:URIExtXKey>c2tkOi8vejdlZzRjWEZZdDl1TXR5dXZNaHptdz09</cpix:URIExtXKey>
        </cpix:DRMSystem>
    </cpix:DRMSystemList>
</cpix:CPIX>

Now that we have the encryption key information required for packaging PlayReady, Widevine, and FairPlay content, proceed to the next step.

Step 2: Generating Hybrik Encoded JSON

Set up the JSON data to be used for encoding/packaging operations in Hybrik using the encryption key and related information generated in step 1.

The following describes only the settings required for DRM encryption, and for the complete job settings for handling DASH and HLS packaging, please refer to the example JSON file in the download page.

DASH Encryption (PlayReady, Widevine)

Refer to Hybrik API documentation to generate JSON data for DASH packaging job. At this time, add the following encryption setting to apply PlayReady and Widevine to the DASH output.

"encryption": {
    "enabled": true,
    "schema": "aes-128-cbc",
    "drm": [ 
        "widevine",
        "playready"
    ],
    "key_id": "f1d127a8acfb6fd2dfa34d1af96770dc",
    "key": "3084ed441258c72d59ed45424052c7bc",
    "widevine_pssh": "CAESEPHRJ6is+2/S36NNGvlncNwaDGlua2FlbnR3b3JrcyIKdGVzdC1jaWQtMQ==",
    "playready_pssh": "AAACknBzc2gAAAAAmgTweZhAQoarkuZb4IhflQAAAnJyAgAAAQABAGgCPABXAFIATQBIAEUAQQBEAEUAUgAgAHgAbQBsAG4AcwA9ACIAaAB0AHQAcAA6AC8ALwBzAGMAaABlAG0AYQBzAC4AbQBpAGMAcgBvAHMAbwBmAHQALgBjAG8AbQAvAEQAUgBNAC8AMgAwADAANwAvADAAMwAvAFAAbABhAHkAUgBlAGEAZAB5AEgAZQBhAGQAZQByACIAIAB2AGUAcgBzAGkAbwBuAD0AIgA0AC4AMgAuADAALgAwACIAPgA8AEQAQQBUAEEAPgA8AFAAUgBPAFQARQBDAFQASQBOAEYATwA+ADwASwBJAEQAUwA+ADwASwBJAEQAIABBAEwARwBJAEQAPQAiAEEARQBTAEMAVABSACIAIABDAEgARQBDAEsAUwBVAE0APQAiAGsAdQBxAFkAbwAxAE4ASQBvAG8AOAA9ACIAIABWAEEATABVAEUAPQAiAHEAQwBmAFIAOABmAHUAcwAwAG0ALwBmAG8AMAAwAGEAKwBXAGQAdwAzAEEAPQA9ACIAPgA8AC8ASwBJAEQAPgA8AC8ASwBJAEQAUwA+ADwALwBQAFIATwBUAEUAQwBUAEkATgBGAE8APgA8AEwAQQBfAFUAUgBMAD4AaAB0AHQAcABzADoALwAvAGwAaQBjAGUAbgBzAGUALgBwAGEAbABsAHkAYwBvAG4ALgBjAG8AbQAvAHIAaQAvAGwAaQBjAGUAbgBzAGUATQBhAG4AYQBnAGUAcgAuAGQAbwA8AC8ATABBAF8AVQBSAEwAPgA8AC8ARABBAFQAQQA+ADwALwBXAFIATQBIAEUAQQBEAEUAUgA+AA=="
}

Enter the encryption key related values of the above encryption setting as follows using the XML data of the CPIX API response for PlayReady/Widevine prepared in step 1.

key_id: 32-bit string with - characters removed from the UUID value of <cpix:ContentKey kid parameter
key: <pskc:PlainValue> tag value converted to lower case hexstring (Reference link)
widevine_pssh: The <cpix:ContentProtectionData> tag value of the Widevine systemId(edef8ba9-79d6-4ace-a3c8-27dcd51d21ed) (the same value as the PSSH tag with the header removed)
playready_pssh: The <cpix:PSSH> tag value of PlayReady systemId(9a04f079-9840-4286-ab92-e65be0885f95)

HLS Encryption (FairPlay)

As with DASH packaging encryption, add FairPlay encryption settings to the JSON of your HLS packaging job as follows:

"encryption": {
    "enabled": true,
    "schema": "sample-aes",
    "drm": [
        "fairplay"
    ],
    "key_id": "cfb7a0e1c5c562df6e32dcaebcc8739b",
    "key": "a25c339f5c14f281c2c63598d42ea8c9",
    "iv": "3763726f61686d746863686578347a30",
    "fairplay_uri": "skd://z7eg4cXFYt9uMtyuvMhzmw=="
}

Encryption related setting values are entered as follows using XML data of CPIX API response for FairPlay.

key_id: 32-bit string with - characters removed from the UUID value of <cpix:ContentKey kid parameter
key: <pskc:PlainValue> tag value converted to lower case hexstring (Reference link)
iv: The <cpix:ContentKey explicitIV parameter converted to lower case hexstring
fairplay_uri: Base64 decoded string of the <cpix:URIExtXKey> tag value

Step 3: Performing Hybrik Encoding/Packaging

Use the JSON configuration created in step 2 to perform packaging through the Hybrik web console and REST API. For more information about the Hybrik REST API, please refer to the API guide.

To play DASH/HLS content packaged by Hybrik DRM integration, you need to integration the DRM license issuance. Please refer to the License Integration Guide and Client Integration Guide for the next steps.

Last updated on Nov 11, 2021