Harmonic

Axinom Key Service supports direct integration with the Harmonic encoder that provides support for the H.264 and H.265 video codecs.

The integration endpoint is /Harmonic/v2 of the Key Acquisition API.

note

The previous version of this endpoint, /Harmonic still exists for backward compatibility. It used a different keyID derivation algorithm, hence the new node is not backward compatible, i.e. even the same content encoded again using the new endpoint will receive different keys. But for all new scenarios it is recommended to use the v2. Other limitations of the previous version:

• Missing Multi-key and Key-rotation support
• The attribute commonEncryptionScheme of the element cpix:ContentKey is not supported (see Encryption Schemes below).

Functionality

The Client requests one or more content keys. The Key Service generates the necessary keys using the Key Seed model and returns the keys with additional DRM-specific metadata where needed.

Authorization

This endpoint requires an authorization header - the same as described under the Key Service Management API.

Request/Response Format

Request

The Client creates a CPIX document in the format which it desires to get, just without the values for the keys, and sends this document to the Key Service. The Key Service generates the specified keys, adds this information to the document, and returns the CPIX document to the Client.

Example of a Harmonic Request (CPIX)

<?xml version="1.0" ?>
<cpix:CPIX contentId="channel_01" xmlns:cpix="urn:dashif:org:cpix">
	<cpix:ContentKeyList>
		<cpix:ContentKey kid="af1ed63c-5784-460b-9e51-309dd47b7d9c"/>
	</cpix:ContentKeyList>
	<cpix:DRMSystemList>
		<cpix:DRMSystem kid="af1ed63c-5784-460b-9e51-309dd47b7d9c" systemId="94ce86fb-07ff-4f43-adb8-93d2fa968ca2"/>
		<cpix:DRMSystem kid="af1ed63c-5784-460b-9e51-309dd47b7d9c" systemId="9a04f079-9840-4286-ab92-e65be0885f95"/>
		<cpix:DRMSystem kid="af1ed63c-5784-460b-9e51-309dd47b7d9c" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed"/>
	</cpix:DRMSystemList>
	<cpix:ContentKeyPeriodList>
		<cpix:ContentKeyPeriod start="2023-04-17T00:00:00Z" end="2024-02-17T16:55:00Z" id="keyperiod_1608224040"/>
	</cpix:ContentKeyPeriodList>
	<cpix:ContentKeyUsageRuleList>
		<cpix:ContentKeyUsageRule intendedTrackType="audio" kid="af1ed63c-5784-460b-9e51-309dd47b7d9c">
			<cpix:KeyPeriodFilter periodId="keyperiod_1608224040"/>
			<cpix:AudioFilter/>
		</cpix:ContentKeyUsageRule>
	</cpix:ContentKeyUsageRuleList>
</cpix:CPIX>

The table below explains some important elements of the request XML.

Element	Purpose
ContentKeyList	The list of the Key IDs for which the Keys shall be generated. Each key ID is a GUID.
DRMSystemList	Requested DRM types, for which the PSSH boxes will be delivered. The IDs are as defined by DASH-IF. Axinom Key Service supports FairPlay, PlayReady, and Widevine (listed in the example above in this order).
ContentKeyPeriodList	List of ContentKeyPeriod elements.
ContentKeyUsageRuleList	Content key usage rules for each key. It’s a pass-through that will only be returned to the Client.

Response

The response is a CPIX document.

Example CPIX document returned by the '/Harmonic' endpoint

<?xml version="1.0" encoding="utf-8"?>
<cpix:CPIX contentId="channel_01" xmlns:cpix="urn:dashif:org:cpix">
    <cpix:ContentKeyList>
        <cpix:ContentKey kid="8b5a0f76-1725-92b3-07d4-f563ca483b0d" explicitIV="50X3FbzWRUZNwBKVnH7EIQ==">
            <cpix:Data>
                <Secret xmlns="urn:ietf:params:xml:ns:keyprov:pskc">
                    <PlainValue>kusV8szSsx5HfjjT3Jt+Ew==</PlainValue>
                </Secret>
            </cpix:Data>
        </cpix:ContentKey>
    </cpix:ContentKeyList>
    <cpix:DRMSystemList>
        <cpix:DRMSystem systemId="9a04f079-9840-4286-ab92-e65be0885f95" kid="8b5a0f76-1725-92b3-07d4-f563ca483b0d">
            <cpix:HLSsignallingData playlist="master">I0VYVC1YLVNFU1NJT04tS0VZOk1FVEhPRD1TQU1QTEUtQUVTLFVSST0ic2tkOi8vOGI1YTBmNzYtMTcyNS05MmIzLTA3ZDQtZjU2M2NhNDgzYjBkOkU3NDVGNzE1QkNENjQ1NDY0REMwMTI5NTlDN0VDNDIxIixLRVlGT1JNQVQ9ImNvbS5hcHBsZS5zdHJlYW1pbmdrZXlkZWxpdmVyeSIsS0VZRk9STUFUVkVSU0lPTlM9IjEi</cpix:HLSsignallingData>
            <cpix:HLSsignallingData playlist="media">I0VYVC1YLUtFWTpNRVRIT0Q9U0FNUExFLUFFUyxVUkk9InNrZDovLzhiNWEwZjc2LTE3MjUtOTJiMy0wN2Q0LWY1NjNjYTQ4M2IwZDpFNzQ1RjcxNUJDRDY0NTQ2NERDMDEyOTU5QzdFQzQyMSIsS0VZRk9STUFUPSJjb20uYXBwbGUuc3RyZWFtaW5na2V5ZGVsaXZlcnkiLEtFWUZPUk1BVFZFUlNJT05TPSIxIg==</cpix:HLSsignallingData>
        </cpix:DRMSystem>
    </cpix:DRMSystemList>
    <cpix:ContentKeyPeriodList>
        <cpix:ContentKeyPeriod end="2024-02-17T16:55:00Z" id="keyperiod_1608224040" start="2023-02-17T16:54:00Z" />
    </cpix:ContentKeyPeriodList>
    <cpix:ContentKeyUsageRuleList>
        <cpix:ContentKeyUsageRule kid="8b5a0f76-1725-92b3-07d4-f563ca483b0d" intendedTrackType="audio">
            <cpix:KeyPeriodFilter periodId="keyperiod_1608224040" />
            <cpix:AudioFilter />
        </cpix:ContentKeyUsageRule>
    </cpix:ContentKeyUsageRuleList>
</cpix:CPIX>

The table below explains the key elements of the response XML.

Element	Description
ContentKeyList	A generated Key and an initialization vector (IV) for each Key ID
DRMSystemList	Additional protection data for each requested DRM system and each key
ContentKeyPeriodList	List of ContentKeyPeriod elements.
ContentKeyUsageRuleList	Content key usage rules, the same as in the request.

note

For configuring a PlayReady Header "LA_URL" in the returned signalling data, please refer to this guide

Encryption Schemes

With the /Harmonic/v2 endpoint, the License Service supports an optional attribute commonEncryptionScheme for each requested key.

Values supported for 'commonEncryptionScheme' and each of the DRM technologies. Value in brackets is the default for a given technology.

Scheme	Widevine	PlayReady	FairPlay
cenc	(X)	(X)
cbcs	X	X	(X)
cens	X
cbc1	X

Caution

If you need FairPlay together with Widevine/PlayReady, you have to set commonEncryptionScheme explicitly to cbcs. Otherwise, different encryption schemes will be selected by default, breaking the keyID-override algorithm.

note

For the v1 endpoint, /Harmonic, the value of this attribute was not considered and the encryption scheme was always set to the defaults in the table above. The keyID-override algorithm didn’t take the encryption scheme into account, so the limitation above did not exist.

KeyID Override

The keyID (attribute keyID) from the request CPIX is not used.

...
<cpix:ContentKey kid="af1ed63c-5784-460b-9e51-309dd47b7d9c"/>
...

Instead, the Key Service generates another keyID using a deterministic algorithm based on the provided contentID.

More details about the keyID derivation algorithm will be published later.

Caution

The keyID derivation algorithm used by the endpoints /Harmonic and /Harmonic/v2 is different and will produce different values.