Introduction to CPIX

CPIX is an open specification developed by DASH-IF that offers support for all major DRM systems and playout formats. The idea behind CPIX is that it provides an interoperable, XML-based format to exchange content protection configurations between different systems that need to interact within a video streaming setup. USP follows the CPIX 2.3 specification.

Ideally, a DRM provider supplies a CPIX document, which can then be used as input for the Unified Streaming Platform; see Command-line options for specifying CPIX document URLs for the various contexts in which you can use a CPIX document. If your DRM provider does not (yet) supply a CPIX document, it is possible to create one yourself.

Note

The use of CPIX documents in combination with non-CPIX based DRM options in a single server manifest is not supported.

Attention

There is no support for encryption, decryption and signing of CPIX documents or DRM keys as for instance outlined in sections 4.3.2 or 4.3.5 of the CPIX 2.3 specification. HTTPS should be used and if needed basic auth or digest may be added through the use of a proxy.

CPIX document structure

Minimum info necessary

To create a CPIX document, the minimum information necessary is:

  • ContentKey

    • Must have a Key ID (KID) used to identify the content and associate it with a (secret) Content Encryption Key.

    • May have a Content Encryption Key (CEK), which is used to encrypt the content.

  • DRMSystem

    • Must have a System ID which represents a specific DRM system such as Microsoft PlayReady (see DASH-IF DRM system IDs).

    • Must have a Key ID which must refer to an existing Content Key's KID.

    • Optionally has a Protection System Specific Header (PSSH). Depending on the DRM system, contains protection information such as such as licenses, rights, and license acquisition information.

    • Optionally has ContentProtectionData used for signaling DRM in the MPEG-DASH playout manifest.

    • Optionally has HLSSignalingData used for signaling DRM in the Apple HLS Manifest.

    • Optionally has SmoothStreamingProtectionHeaderData used for signaling DRM in the Microsoft Smooth Streaming playout manifest.

    • Optionally has HDSSignalingData used for signaling DRM in the HTTP Dynamic Streaming playout manifest.

Minimal CPIX example

The following example shows a minimal CPIX document:

 1<?xml version='1.0' encoding='UTF-8'?>
 2<CPIX xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:dashif:org:cpix" xsi:schemaLocation="urn:dashif:org:cpix cpix.xsd">
 3  <ContentKeyList>
 4    <ContentKey kid="e82f184c-3aaa-57b4-ace8-606b5e3febad">
 5      <Data>
 6        <pskc:Secret>
 7          <pskc:PlainValue>wvr2bihSzExKdR8KKpQf2w==</pskc:PlainValue>
 8        </pskc:Secret>
 9      </Data>
10    </ContentKey>
11  </ContentKeyList>
12  <DRMSystemList>
13    <!-- Widevine -->
14    <DRMSystem kid="e82f184c-3aaa-57b4-ace8-606b5e3febad" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
15      <PSSH>AAAAMnBzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAABIiCnVzcHd2dGVzdDNI49yVmwY=</PSSH>
16      <ContentProtectionData />
17      <HLSSignalingData />
18    </DRMSystem>
19  </DRMSystemList>
20</CPIX>

  • The document's <ContentKeyList> contains a single <ContentKey> element with key ID e82f184c-3aaa-57b4-ace8-606b5e3febad (line 4).

  • The base64-encoded CEK for this key ID is wvr2bihSzExKdR8KKpQf2w== (line 7).

  • The document's <DRMSystemList> contains a single <DRMSystem> element. It is used for the <ContentKey> element above (e82f184c-3aaa-57b4-ace8-606b5e3febad) in combination with the Widevine (edef8ba9-79d6-4ace-a3c8-27dcd51d21ed) DRM system (line 14).

  • The base64-encoded PSSH DRM information for Widevine is listed in line 15.

  • Both the <ContentProtectionData> and <HLSSignalingData> elements listed in lines 16 and 17 are left empty. This tells USP to generate the required signaling when an MPEG-DASH manifest or HLS playlist is requested. For the full list of supported generated signalings, see Using implicitly generated signaling. Alternatively, the signaling can be explicitly specified in the CPIX document; see Using explicitly specified signaling.

  • This CPIX document does not contain a <ContentKeyUsageRuleList> element, which is used to limit the use of a specific <ContentKey> based on track characteristics (see Using DRM with Multiple Keys), by timespan (see Using DRM with Key Rotation (HLS TS Only)), or both. The absence of any usage rules implies that a query of this document for encryption information will always select the only content key it contains.

Note

  • It is possible to explicitly signal a Key Initialization Vector (IV) by adding an explicitIV attribute to a <ContentKey> element. The primary use of this is to enable the use of DRM systems that associate a single IV with each CEK and whose DRM client implementations are unable to extract the IV from the content, requiring the license server to deliver the IV together with the CEK upon request. Use of this attribute is not recommended except for compatibility with such DRM systems.

  • If you work with pre-encrypted content, it is not necessary to provide a CEK in your CPIX document as the platform only requires a CEK to encrypt content and not for generating the necessary signaling.

Usage rules

As stated above, a CPIX document may contain a <ContentKeyUsageRuleList> that consists of a list of <ContentKeyUsageRule> elements. Usage rules limit the applicability of a particular <ContentKey>, identified by the rule's kid attribute, to a specific track or timespan.

Filter types

Each <ContentKeyUsageRule> element contains a number of filtering elements. There are different types of filtering elements; most filter types (<VideoFilter>, <AudioFilter>, <BitrateFilter>) limit the use a content key to a particular track as described in Using DRM with Multiple Keys. A <KeyPeriodFilter> limits to use of a content key to a particular timespan; see Using DRM with Key Rotation (HLS TS Only) for further details.

Note

The <LabelFilter> element from the CPIX 2.3 specification is not supported.

Attention

Your CPIX document must be unambiguous; be sure to configure your filtering rules such that at most one content key is selected.

CPIX document creation

In order to make the creation of CPIX documents easier we provide two tools to create them:

  • pycpix - a Python library for working with CPIX documents

  • cpix-gen - a CPIX generator tool - a fully installed, dockerised version of pycpix.

Example

To create a simple CPIX document with a single key:

import cpix

full_cpix = cpix.CPIX(
    content_keys=cpix.ContentKeyList(
        cpix.ContentKey(
            kid="0DC3EC4F-7683-548B-81E7-3C64E582E136",
            cek="WADwG2qCqkq5TVml+U5PXw=="
        )
    ),
    drm_systems=cpix.DRMSystemList(
        cpix.DRMSystem(
            kid="0DC3EC4F-7683-548B-81E7-3C64E582E136",
            system_id="EDEF8BA9-79D6-4ACE-A3C8-27DCD51D21ED",
            pssh=("AAAAxnBzc2gBAAAA7e+LqXnWSs6jyCfc1R0h7QAAAAINw+xPdoNUi4HnPGT"
                  "lguE2FEe37S9mVyu9EwbOfPNhDQAAAIISEBRHt+0vZlcrvRMGznzzYQ0SEF"
                  "rGoR6qL17Vv2aMQByBNMoSEG7hNRbI51h7rp9+zT6Zom4SEPnsEqYaJl1Hj"
                  "4MzTjp40scSEA3D7E92g1SLgec8ZOWC4TYaDXdpZGV2aW5lX3Rlc3QiEXVu"
                  "aWZpZWQtc3RyZWFtaW5nSOPclZsG")
        )
    )
)

This can then be printed (or saved to disk) as a formatted XML document:

print(str(full_cpix.pretty_print(xml_declaration=True), "utf-8'"))

<?xml version='1.0' encoding='utf-8'?>
<CPIX xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:dashif:org:cpix" xsi:schemaLocation="urn:dashif:org:cpix cpix.xsd">
  <ContentKeyList>
    <ContentKey kid="0dc3ec4f-7683-548b-81e7-3c64e582e136">
      <Data>
        <pskc:Secret>
          <pskc:PlainValue>WADwG2qCqkq5TVml+U5PXw==</pskc:PlainValue>
        </pskc:Secret>
      </Data>
    </ContentKey>
  </ContentKeyList>
  <DRMSystemList>
    <DRMSystem kid="0dc3ec4f-7683-548b-81e7-3c64e582e136" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
      <PSSH>AAAAxnBzc2gBAAAA7e+LqXnWSs6jyCfc1R0h7QAAAAINw+xPdoNUi4HnPGTlguE2FEe37S9mVyu9EwbOfPNhDQAAAIISEBRHt+0vZlcrvRMGznzzYQ0SEFrGoR6qL17Vv2aMQByBNMoSEG7hNRbI51h7rp9+zT6Zom4SEPnsEqYaJl1Hj4MzTjp40scSEA3D7E92g1SLgec8ZOWC4TYaDXdpZGV2aW5lX3Rlc3QiEXVuaWZpZWQtc3RyZWFtaW5nSOPclZsG</PSSH>
    </DRMSystem>
  </DRMSystemList>
</CPIX>

For installation and further details, please see either Github repository.

Caching dynamically requested CPIX documents

As the Command-line options for specifying CPIX document URLs section outlines at the beginning, it is possible configure Unified Origin to use a URL that refers to a CPIX document and request CPIX documents from a remote DRM server or API.

An example:

#!/bin/bash

mp4split -o example.ism \
  --hls.cpix=https://cpix-origin/contentid/example.cpix \

See also the Third Party DRM Providers with CPIX API examples from Axinom, castLabs DRMtoday, EZDRM, Irdeto and JW Player.

As Unified Origin is stateless, it will request the CPIX document from the remote DRM server for each incoming request.

To optimize this workflow the response from the DRM server can be cached, using the same CPIX document for identical requests, not going upstream each time.

In the case of key rotation 'start' and 'end' query parameters could possibly be used to define a time span (see CPIX origin), this can be cached too as when the time span expires a new will be requested (and cached).

Setting up a local cache with Apache can be done in a similar way as for instance is described in Cloud Storage Reducing Latency under Apache configuration section with the difference that .cpix documents should be cached (and not .ism or .mp4 files as described there).

See Apache's caching and mod_cache documentation for further details.