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.1 specification.

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

Note

While all DRM use cases supported by the Unified Streaming Platform that you can configure with a command-line option can also be configured with a CPIX document, we do not recommend the use of CPIX documents unless required for advanced use cases such as multiple keys and key rotation.

CPIX document structure

Minimum info necessary

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

  • Key ID (KID)
    • A 128 bit key used to identify the content and associate it with a specific (secret) Content Encryption Key (CEK). In the CPIX document it is used to associate a CEK with content protection information for a DRM system (this information is represented in a PSSH, see below).
  • Content Encryption Key (CEK)
    • A 128 bit key used to encrypt the content with, which is associated with a specific KID. In the CPIX document it is stored inside a Portable Symmetric Key Container (PSKC, i.e., RFC 6030). Unified Origin only supports ‘plain’ signaling of a CEK, which means that, following the PSKC specification, it must be stored as a base64 encoded binary in the PSKC.
  • DRM system ID
    • A unique identifier (UUID) for a specific DRM system like Microsoft PlayReady (see DASH-IF DRM system IDs). In the CPIX document it is used to specify the DRM system that a PSSH is associated with.
  • Protection System Specific Header (PSSH)
    • Each PSSH contains the protection information for a specific DRM system, such as licenses, rights, and license acquisition information. Each PSSH specified in a CPIX document is associated with a KID and a system ID.

Minimal CPIX example

The following example shows a minimal CPIX document:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<?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="e82f184c-3aaa-57b4-ace8-606b5e3febad">
      <Data>
        <pskc:Secret>
          <pskc:PlainValue>wvr2bihSzExKdR8KKpQf2w==</pskc:PlainValue>
        </pskc:Secret>
      </Data>
    </ContentKey>
  </ContentKeyList>
  <DRMSystemList>
    <!-- Widevine -->
    <DRMSystem kid="e82f184c-3aaa-57b4-ace8-606b5e3febad" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
      <PSSH>AAAAMnBzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAABIiCnVzcHd2dGVzdDNI49yVmwY=</PSSH>
    </DRMSystem>
  </DRMSystemList>
</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 value for this <ContentKey> and <DRMSystem> combination is listed in line 15.
  • This 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 Unified Origin only requires a CEK to encrypt content and not for generating the necessary signaling.

Play-out format specific signaling

A <DRMSystem> element can contain sub-elements for playout format specific signaling:

  • <ContentProtectionData>>: specific signaling for MPEG-DASH
  • <HLSSignalingData>: specific signaling for Apple HLS
  • <SmoothStreamingProtectionHeaderData>: specific signaling for Microsoft Smooth Streaming

Note

Currently, only the specific signaling data for HLS should be provided (if you want to make use of HLS as an output format). For the other playout formats, Origin will disregard the format-specific signaling and generate the necessary signaling from the specified PSSH.

Content that is associated with a content key (see:ref:selection-algorithm) will always be encrypted, regardless of the presence or absence of format-specific signaling.

The <HLSSignalingData> element

The optional <HLSSignalingData> sub-element of the <DRMSystem> element can be used to signal the DRM specific information that must be included in the HLS playlist. Origin uses the provided information as is and does not check it for consistency or correctness. This provides a lot of flexibility, but does not allow for any errors.

The information should include the #EXT-X-KEY tag and must be in base64 encoded binary format. It may contain multiple lines, allowing for extra lines with proprietary tags and values.

For example, fMP4 HLS with Widevine requires information as shown below:

#EXT-X-KEY:METHOD=SAMPLE-AES,KEYID=0x10000000100010001000100000000001,URI="data:text/plain;base64,AAAAPXBzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAAB0aDXdpZGV2aW5lX3Rlc3QiDHRlc3QgY29udGVudA==",KEYFORMAT="urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed",KEYFORMATVERSIONS="1"

In CPIX, this must be stored as base64 encoded binary and signaled as:

    <DRMSystem
      systemId="EDEF8BA9-79D6-4ACE-A3C8-27DCD51D21ED"
      kid="10000000-1000-1000-1000-100000000001">
      <PSSH>AAAAUXBzc2gBAAAA7e+LqXnWSs6jyCfc1R0h7QAAAAEQAAAAEAAQABAAEAAAAAABAAAAHRoNd2lkZXZpbmVfdGVzdCIMdGVzdCBjb250ZW50</PSSH>
      <HLSSignalingData>I0VYVC1YLUtFWTpNRVRIT0Q9U0FNUExFLUFFUyxLRVlJRD0weDEwMDAwMDAwMTAwMDEwMDAxMDAwMTAwMDAwMDAwMDAxLFVSST0iZGF0YTp0ZXh0L3BsYWluO2Jhc2U2NCxBQUFBUFhCemMyZ0FBQUFBN2UrTHFYbldTczZqeUNmYzFSMGg3UUFBQUIwYURYZHBaR1YyYVc1bFgzUmxjM1FpREhSbGMzUWdZMjl1ZEdWdWRBPT0iLEtFWUZPUk1BVD0idXJuOnV1aWQ6ZWRlZjhiYTktNzlkNi00YWNlLWEzYzgtMjdkY2Q1MWQyMWVkIixLRVlGT1JNQVRWRVJTSU9OUz0iMSI=</HLSSignalingData>
    </DRMSystem>

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.1 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.