Irdeto Control API

The following script shows how to use the Irdeto Control API to register content and get HLS or PlayReady keys. The API is a REST API using HTTP GET and POST. XML Soap messages may be posted to Control in certain calls.

There are the following possibilities:

Format DRM Description
HLS AES-128 (Pantos) Standard AES-128 encryption
HLS SKE Irdeto defined HLS encryption
HLS PlayReady Irdeto Active Cloak
Smooth PlayReady Standard PlayReady (using the Irdeto license server)

Below only options two and three are described. For option one and four you do need to call into Control (as described below to get HLS or PlayReady keys), but the commandline to use then is the same as with HTTP Live Streaming (HLS) with Transport Streams or PlayReady DRM.

Irdeto SKE for HLS

New in version 1.7.1.

In order to get an HLS key from the Irdeto Control API two API calls need to be made:

  • GetHLSSettings
  • GenerateHLSKeys

GetHLSSettings

Returns the license acquisition URL to use when encrypting streams with either Pantos HLS, SKE HLS or SKE PlayReady.

The SOAP message is the following:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <LiveDrmServiceHeader m_sUsername="YOUR_USERNAME" m_sPassword="YOUR_PASSWD" xmlns="http://man.entriq.net/livedrmservice/" />
  </soap:Header>
  <soap:Body>
    <GetHLSSettings xmlns="http://man.entriq.net/livedrmservice/">
      <sAccountID>YOUR_ACCOUNT_ID</sAccountID>
    </GetHLSSettings>
  </soap:Body>
</soap:Envelope>

Download as file: irdeto/get-hls-settings.xml

The curl call to the Control server looks like this:

curl --silent -X POST \
  -H "Host: iis7test.entriq.net" \
  -H "content-type:text/xml;charset=utf-8" \
  -H "SoapAction: http://man.entriq.net/livedrmservice/GetHLSSettings" \
  -d @get-hls-settings.xml \
  "http://iis7test.entriq.net/LiveDrmservice/LiveDrmservice.asmx"

The response body contains an SOAP response where the text string inside the GetHLSSettingsResult element should itself be interpreted as XML. Ie.: after parsing this embedded XML, the LA URL is the value of root node attribute LicenseURL.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetHLSSettingsResponse xmlns="http://man.entriq.net/livedrmservice/">
      <GetHLSSettingsResult>&lt;HLSSettings LicenseURL="https://iis7test.entriq.net/HLS/GetKey.aspx?CrmId=YOUR_ACCOUNT_ID" EKFURL="..." /&gt;</GetHLSSettingsResult>
    </GetHLSSettingsResponse>
  </soap:Body>
</soap:Envelope>

For instance, below python script could be used to extract license acquisition URL from above payload:

#!/usr/bin/env python

import sys, xml.etree.ElementTree as et

tree = et.parse(sys.stdin)
text = tree.find(".//{http://man.entriq.net/livedrmservice/}GetHLSSettingsResult").text
embedded_tree = et.ElementTree(et.fromstring(text))
la_url = embedded_tree.getroot().attrib["LicenseURL"]

print la_url

Download the full script: irdeto/get-hls-settings.sh

The LA URL returned from the GetHLSSettings call needs additional query parameters obtained from the GenerateHLSKeys call - the final LA URL is shown below. It consists of the following parts:

Part Description
Url The actual URL part
AccountId Your account id
ContentId The content id under which the content key and key id are made
KeyId The key id for the content key
SubContentType  
EKF  

Example:

http://URL?CrmId=""&AccountId=""&ContentId=""&KeyId=""&SubContentType=""&EKF=""

GenerateHLSKeys

Generates a new HLS encryption key for live events.

The SOAP message is the following:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <LiveDrmServiceHeader m_sUsername="YOUR_USERNAME" m_sPassword="YOUR_PASSWD" xmlns="http://man.entriq.net/livedrmservice/" />
  </soap:Header>
  <soap:Body>
    <GenerateHLSKeys xmlns="http://man.entriq.net/livedrmservice/">
      <sAccountID>YOUR_ACCOUNTID</sAccountID>
      <sContentId>YOUR_CONTENTID</sContentId>
    </GenerateHLSKeys>
  </soap:Body>
</soap:Envelope>

Download as file: irdeto/generate-hls-keys.xml.

The curl call to the Control server looks like this:

curl --silent -X POST \
  -H "Host: iis7test.entriq.net" \
  -H "content-type:text/xml;charset=utf-8" \
  -H "SoapAction: http://man.entriq.net/livedrmservice/GenerateHLSKeys" \
  -d @generate-hls-keys.xml \
  "http://iis7test.entriq.net/LiveDrmservice/LiveDrmservice.asmx"

(After which you need to parse the key id, content encryption key and other parameters like the EKF from the response body - this is outlined in downloadable generate-hls-keys script).

Download the full script: irdeto/generate-hls-keys.sh.

The get-hls-settings and generate-hls-keys scripts can be combined as follows to get the parameters mp4split needs:

#!/bin/bash

url=$(./get-hls-settings)
IFS=' ' read args cek kid <<< $(./generate-hls-keys)

# the API returns a GUID, so convert it to UUID
kid16=`echo -n $kid | python -c 'import base64,uuid,sys; kid="".join(sys.stdin.readlines()); print base64.b16encode(uuid.UUID(bytes_le=uuid.UUID(kid).bytes).bytes)'`

# convert the base64 CEK to hex
cek16=`echo -n $cek | python -c 'import base64,uuid,sys; cek="".join(sys.stdin.readlines()); print base64.b16encode(base64.b64decode(cek))'`

iv=08090a0b0c0d0e0f0001020304050607
la_url="$url$args"

MP4SPLIT_OPTIONS=
MP4SPLIT_OPTIONS+=--irdeto.key=${kid16}:${cek}
MP4SPLIT_OPTIONS+=--irdeto.key_iv=${iv}
MP4SPLIT_OPTIONS+=--irdeto.license_server_url=${la_url}

mp4split -o $1 $MP4SPLIT_OPTIONS $2

Irdeto PlayReady for HLS

New in version 1.7.4.

For PlayReady the same GetSettings - GenerateKeys-sequence applies:

  • GetPlayreadySettings
  • GeneratePlayreadyKeys

You can download both calls as scripts and corresponding XML below:

To use HLS playout with Irdeto’s PlayReady signaling (Irdeto Active Cloak), pass the irdeto_playready option (rather than irdeto or hls). This will add the necessary #X-IRDETO-* attributes to playlists.

The get-pr-settings and generate-pr-keys scripts can be combined as follows to get the parameters mp4split needs:

#!/bin/bash

url=$(./get-pr-settings.sh)
IFS=' ' read args cek kid <<< $(./generate-pr-keys.sh)

# the API returns a GUID, so convert it to UUID
kid16=`echo -n $kid | python -c 'import base64,uuid,sys; kid="".join(sys.stdin.readlines()); print base64.b16encode(uuid.UUID(bytes_le=uuid.UUID(kid).bytes).bytes)'`

# convert the base64 CEK to hex
cek16=`echo -n $cek | python -c 'import base64,uuid,sys; cek="".join(sys.stdin.readlines()); print base64.b16encode(base64.b64decode(cek))'`

iv=08090a0b0c0d0e0f0001020304050607
la_url="$url$args"

MP4SPLIT_OPTIONS=
MP4SPLIT_OPTIONS+=--irdeto_playready.key=${kid16}:${cek16}
MP4SPLIT_OPTIONS+=--irdeto_playready.key_iv=${iv}
MP4SPLIT_OPTIONS+=--irdeto_playready.license_server_url=${la_url}

mp4split -o $1 $MP4SPLIT_OPTIONS $2

Irdeto PlayReady Scalable License for HLS

New in version 1.9.0.

Options for PlayReady Scalable License DRM

The options for enabling encryption are stored in the server manifest file. For this DRM system a content encryption key (CEK) and key id (KID) are required. You need to provide the following options:

–iss.key

The KID and CEK are passed with the --iss.key option where KID and CEK are separated by a colon, e.g. --iss.key=KID:CEK

Both KID and CEK must be coded in hex (base16).

–iss.drm_specific_data

The --iss.drm_specific_data option requires a “pssh” box version 1 box as defined by the “ISO/IEC 23001-7 Common encryption in ISO base media file format files”. Can either be a Base64 string or a file with the decoded Base64 data. The file name must include a ‘.’

The “pssh” box must contain a KID which references the KID passed in by the --iss.key option.

The “pssh” data is a PlayReady Object, as defined by “Microsoft PlayReady Header Specification”.

The PlayReady Object must contain a Header record, which will be signaled in the master HLS playlist. Additionally it must contain an Embedded License Store record which will be signaled in the media HLS playlist.

Example usage:

#!/bin/bash

KID=000102030405060708090a0b0c0d0e0f
CEK=000102030405060708090a0b0c0d0e0f
PSSH=BASE64_OR_FILE_PATH

MP4SPLIT_OPTIONS=
MP4SPLIT_OPTIONS+=--iss.key=${KID}:${CEK}
MP4SPLIT_OPTIONS+=--iss.drm_specific_data=${PSSH}
MP4SPLIT_OPTIONS+=--hls.playout=irdeto_playready

mp4split -o out.ism ${MP4SPLIT_OPTIONS} video1.ismv video2.ismv audio1.ismv