CPIX Document Requirements

Introduction

As explained in Command-line options for specifying CPIX document URLs, USP has options for specifying the URL of the CPIX document it should use for generating signaling data or encrypting content. The CPIX document may either be served statically, or, for the key rotation use case, be dynamically generated by a CPIX origin server, as explained in Using DRM with Key Rotation (HLS TS Only).

Here, we specify USP's requirements on these documents. See [1] for a formal description of the CPIX standard.

General overview

The following top-level XML elements are important:

<ContentKeyList>

The <ContentKeyList> contains a list of <ContentKey> elements. Each <ContentKey> element is identified by its kid attribute. It may contain encryption parameters, such as an encryption key or an initialization vector.

<DRMSystemList>

The <DRMSystemList> contains a list of <DRMSystem> elements. A <DRMSystem> element describes DRM-system specific data for a single <ContentKey>. Each <DRMSystem> element is identified by the combination of its systemId and kid attributes.

<ContentKeyPeriodList>

The <ContentKeyPeriodList> contains a list of <ContentKeyPeriod> elements. A <ContentKeyPeriod> describes a timespan, which is used by a <KeyPeriodFilter> in a <ContentKeyUsageRule>; please see below. Each <ContentKeyPeriod> is identified by its id attribute; its timespan is described by its start and end attributes.

<ContentKeyUsageRuleList>

The <ContentKeyUsageRuleList> contains a list of <ContentKeyUsageRule> elements. Each <ContentKeyUsageRule> applies to the <ContentKey> that it identifies by its kid attribute, and specifies the applicability of that <ContentKey> by the filter elements it contains. <VideoFilter>, <AudioFilter> and <BitrateFilter> limit the applicability of the <ContentKey> by track characteristics. The <KeyPeriodFilter> element is used for key rotation: it limits the applicability of the <ContentKey> to a specific <ContentKeyPeriod>.

Example: CPIX document with multiple keys selected by track type

 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>...</pskc:PlainValue>
 8        </pskc:Secret>
 9      </Data>
10    </ContentKey>
11    <ContentKey kid="087bcfc6-f7a5-5716-b840-6aa6eba3369e">
12      <Data>
13        <pskc:Secret>
14          <pskc:PlainValue>...</pskc:PlainValue>
15        </pskc:Secret>
16      </Data>
17    </ContentKey>
18    <ContentKey kid="0d6b4023-8da1-5e75-af68-75c514c59b63">
19      <Data>
20        <pskc:Secret>
21          <pskc:PlainValue>...</pskc:PlainValue>
22        </pskc:Secret>
23      </Data>
24    </ContentKey>
25  </ContentKeyList>
26  <DRMSystemList>
27    <!-- Widevine -->
28    <DRMSystem kid="e82f184c-3aaa-57b4-ace8-606b5e3febad" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
29      <PSSH>...</PSSH>
30      <ContentProtectionData />
31    </DRMSystem>
32    <!-- PlayReady -->
33    <DRMSystem kid="e82f184c-3aaa-57b4-ace8-606b5e3febad" systemId="9a04f079-9840-4286-ab92-e65be0885f95">
34      <PSSH>...</PSSH>
35      <ContentProtectionData />
36    </DRMSystem>
37    <!-- Widevine -->
38    <DRMSystem kid="087bcfc6-f7a5-5716-b840-6aa6eba3369e" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
39      <PSSH>...</PSSH>
40      <ContentProtectionData />
41    </DRMSystem>
42    <!-- PlayReady -->
43    <DRMSystem kid="087bcfc6-f7a5-5716-b840-6aa6eba3369e" systemId="9a04f079-9840-4286-ab92-e65be0885f95">
44      <PSSH>...</PSSH>
45      <ContentProtectionData />
46    </DRMSystem>
47    <!-- Widevine -->
48    <DRMSystem kid="0d6b4023-8da1-5e75-af68-75c514c59b63" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
49      <PSSH>...</PSSH>
50      <ContentProtectionData />
51    </DRMSystem>
52    <!-- PlayReady -->
53    <DRMSystem kid="0d6b4023-8da1-5e75-af68-75c514c59b63" systemId="9a04f079-9840-4286-ab92-e65be0885f95">
54      <PSSH>...</PSSH>
55      <ContentProtectionData />
56    </DRMSystem>
57  </DRMSystemList>
58  <ContentKeyUsageRuleList>
59    <ContentKeyUsageRule kid="e82f184c-3aaa-57b4-ace8-606b5e3febad">
60      <VideoFilter maxPixels="589824"/>
61    </ContentKeyUsageRule>
62    <ContentKeyUsageRule kid="087bcfc6-f7a5-5716-b840-6aa6eba3369e">
63      <VideoFilter minPixels="589825" maxPixels="2073600"/>
64    </ContentKeyUsageRule>
65    <ContentKeyUsageRule kid="0d6b4023-8da1-5e75-af68-75c514c59b63">
66      <AudioFilter/>
67    </ContentKeyUsageRule>
68  </ContentKeyUsageRuleList>
69</CPIX>

Example: CPIX document with key rotation

 1<?xml version="1.0" encoding="utf-8"?>
 2<CPIX xmlns="urn:dashif:org:cpix"
 3  xsi:schemaLocation="urn:dashif:org:cpix cpix.xsd"
 4  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 5  xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc">
 6  <ContentKeyList>
 7    <ContentKey
 8      kid="00000000-0000-0000-0000-000000000001">
 9      <Data>
10        <pskc:Secret>
11          <pskc:PlainValue>...</pskc:PlainValue>
12        </pskc:Secret>
13      </Data>
14    </ContentKey>
15    <ContentKey
16      kid="00000000-0000-0000-0000-000000000002">
17      <Data>
18        <pskc:Secret>
19          <pskc:PlainValue>...</pskc:PlainValue>
20        </pskc:Secret>
21      </Data>
22    </ContentKey>
23  </ContentKeyList>
24  <DRMSystemList>
25    <DRMSystem
26      systemId="81376844-F976-481E-A84E-CC25D39B0B33"
27      kid="00000000-0000-0000-0000-000000000001">
28      <PSSH>...</PSSH>
29      <HLSSignalingData>...</HLSSignalingData>
30    </DRMSystem>
31    <DRMSystem
32      systemId="81376844-F976-481E-A84E-CC25D39B0B33"
33      kid="00000000-0000-0000-0000-000000000002">
34      <PSSH>...</PSSH>
35      <HLSSignalingData>...</HLSSignalingData>
36    </DRMSystem>
37  </DRMSystemList>
38  <ContentKeyPeriodList>
39    <ContentKeyPeriod
40      id="KeyPeriod_1"
41      start="1970-01-01T00:00:00Z"
42      end="1970-01-01T00:01:00Z"/>
43    <ContentKeyPeriod
44      id="KeyPeriod_2"
45      start="1970-01-01T00:01:00Z"
46      end="1970-01-01T00:02:00Z"/>
47    </ContentKeyPeriodList>
48  <ContentKeyUsageRuleList>
49    <ContentKeyUsageRule
50      kid="00000000-0000-0000-0000-000000000001">
51      <KeyPeriodFilter
52        periodId="keyPeriod_1"/>
53    </ContentKeyUsageRule>
54    <ContentKeyUsageRule
55      kid="00000000-0000-0000-0000-000000000002">
56      <KeyPeriodFilter
57        periodId="keyPeriod_2"/>
58    </ContentKeyUsageRule>
59  </ContentKeyUsageRuleList>
60</CPIX>

Requirements for the <ContentKey> element

  • The kid attribute (a 128-bit value in UUID format) MUST be specified and uniquely identify a single <ContentKey> element in the scope of the CPIX document.

  • The explicitIV attribute MAY be present; if present, it MUST contain a base64-encoded 16-byte initialization vector.

  • The commonEncryptionScheme attribute MAY be present. If present, it MUST have a value of "cenc", "cbc1", "cens" or "cbcs", which specifies the Common Encryption scheme type for HLS-fmp4 and DASH playout. By default, the Common Encryption scheme type defaults to "cbcs" for HLS-fmp4, and "cenc" for DASH.

  • A <Data> subelement MAY be present, which MAY contain a nested <pskc:Secret> element, which MAY contain a nested <pskc:PlainValue> element with a base64-encoded 16-byte content encryption key as its character data.

Requirements for the <DRMSystem> element

  • The systemId attribute (a 128-bit value in UUID format) MUST be specified as one of the protection system-specific identifiers listed by the DASH industry forum [2].

  • The kid attribute MUST be specified and identify one of the <ContentKey> elements in the scope of the CPIX document's <ContentKeyList>.

  • The combination of the systemId and kid attributes MUST uniquely identify a single <DRMSystem> element in the scope of the CPIX document.

  • A name attribute MAY be present; if set, it is copied to the value attribute in the corresponding <ContentProtection> element when a DASH manifest is generated.

  • A single <PSSH> subelement MAY be present; if so, it MUST contain a base64-encoded PSSH box as specified in the ISO base media file format [3] as its character data. The system id found in the PSSH box MUST match the value of the systemId attribute in the enclosing <DRMSystem> element. Furthermore, if the PSSH box contains any key IDs, one of them MUST match the value of the kid attribute in the enclosing <DRMSystem> element.

  • A single <ContentProtectionData> subelement MAY be present; it contains, as its character data, the base64-encoded well-formed XML fragment added to the DASH manifest under the corresponding <ContentProtection> element.

  • A single <HLSSignalingData> subelement with a playlist attribute set to "media" (or, if there is no other <HLSSignalingData> subelement, no playlist attribute) MAY be present. This subelement contains, as its character data, the base64-encoded DRM signaling data for the HLS media playlist as specified in [4]. Lines tagged with #EXT-X-KEY: may be re-interpreted by the platform. If the #EXT-X-KEY line contains an IV attribute, it overrides any initialization vector specified in the explicitIV attribute of the <ContentKey> element.

  • A single <HLSSignalingData> subelement with a playlist attribute set to "master" MAY be present; it contains, as its character data, the base64-encoded DRM signaling data for the HLS master playlist as specified in [4].

  • A single <SmoothStreamingProtectionHeaderData> subelement MAY be present; this is the inner text of the <ProtectionHeader> XML element to be added to the Smooth Streaming manifest.

  • A single <HDSSignalingData> subelement MAY be present; this is the base64-encoded full <drmAdditionalHeader> element to be added to the HDS playlist.

Alternatively, as a USP-specific extension, if a <ContentProtectionData>, <HLSSignalingData> <SmoothStreamingProtectionHeaderData> or <HDSSignalingData> subelement is present but left empty, the platform will attempt to generate the corresponding signaling data; see Using implicitly generated signaling.

Requirements for the <ContentKeyPeriod> element

  • The id (a non-empty string) attribute MUST be specified and uniquely identify a single <ContentKeyPeriod> element in the scope of the CPIX document.

  • The start attribute (a UTC timestamp as specified in [5]) MUST be present. For on-demand streaming, it specifies the start of the key period from the beginning of the presentation; for live streaming, it specifies the start of the the key period in wall clock time.

  • The end attribute (a UTC timestamp as specified in [5]) MUST be present. For on-demand streaming, it specifies the end of the key period from the start of the presentation; for live streaming, it specifies the end of the period in wall clock time. The range described by the content key period does not include the end timepoint: the time range is [start, end>. The end of the key period MUST be greater than or equal to the start of the key period.

  • The index attribute as described in [1] is not supported by USP and MUST NOT be present.

Requirements for the <ContentKeyUsageRule> element

  • The kid attribute (a 128-bit value in UUID format) MUST be specified and identify one of the <ContentKey> elements in the document's <ContentKeyList>.

  • A <ContentKeyUsageRule> contains a list of zero or more filtering sub-elements of type <VideoFilter>, <AudioFilter>`, ``<BitrateFilter> or <KeyPeriodFilter>. The <LabelFilter> element type specified in [1] is not supported by USP and MUST NOT be present.

Requirements for the <VideoFilter> element

A <VideoFilter> element, even without attributes, only matches video tracks.

  • The minPixels attribute (an integer) MAY be present. If so, the filter only matches tracks with a width x height of at least the value of this attribute.

  • The maxPixels attribute (an integer) MAY be present. If so, the filter does not match tracks with a width x height that is greater than the value of this attribute.

  • The minFps attribute (an integer) MAY be present. If so, the filter only matches tracks with a nominal number of frames per second that is greater than the value of this attribute.

  • The maxFps attribute (an integer) MAY be present. If so, the filter does not match tracks with a nominal number of frames per second that is greater than the value of this attribute.

  • The hdr and wcg attributes as described in [1] are not supported by USP and MUST NOT be present.

Requirements for the <AudioFilter> element

An <AudioFilter> element, even without attributes, only matches audio tracks.

  • The minChannels attribute (an integer) MAY be present. If so, the filter only matches tracks with with a number of channels of at least the value of this attribute.

  • The maxChannels attribute (an integer) MAY be present. If so, the filter does not match tracks with a number of channels that is greater than the value of this attribute.

Requirements for the <BitrateFilter> element

  • The minBitrate attribute (an integer) MAY be present. If so, the filter only matches tracks with a nominal bitrate (in Mb/s) of at least the value of this attribute.

  • The maxBitrate attribute (an integer) MAY be present. If so, the filter does not match tracks with a nominal bitrate (in Mb/s) that is greater than the value of this attribute.

  • At least one of the minBitrate or maxBitrate attributes MUST be present.

Requirements for the <KeyPeriodFilter> element

  • The periodId MUST be specified and identify one of the <ContentKeyPeriod> elements in the scope of the CPIX document's <ContentKeyPeriodList>. A <KeyPeriodFilter> limits the match to segments that start in the <ContentKeyPeriod> it refers to.

Content key selection algorithm

To determine the encryption keys and signaling data used for a particular video or audio track [6], the platform will query the CPIX document for matching <ContentKey> elements. For a pre-encrypted track, at most one <ContentKey> element is found by matching its kid attribute to the key ID stored in the track. If the track is not pre-encrypted, a <ContentKey> element matches a track when:

  • There is no <ContentKeyUsageRule> element referring to it, or

  • It is referrred to by at least one <ContentKeyUsageRule> element matching the track.

A <ContentKeyUsageRule> element matches a track if it:

  • Has no <VideoFilter> elements, or at least one <VideoFilter> element that matches the track (see above), and

  • Has no <AudioFilter> elements, or at least one <AudioFilter> element that matches the track (see above), and

  • Has no <BitrateFilter> elements, or at least one <BitrateFilter> element that matches the track (see above).

The presence of one or more <KeyPeriodFilter> elements in a <ContentKeyUsageRule> limits the track's match of that <ContentKeyUsageRule> to the timespans in the corresponding <ContentKeyPeriod> elements.

If a <ContentKey> has no <ContentKeyUsageRule> referring to it, or if a matching <ContentKeyUsageRule> has no <KeyPeriodFilter> elements, the tracks's match applies to the entire timespan [7] covered by the CPIX document.

In all cases, the search algorithm results in a set of zero or more <ContentKey> elements matching the track.

  • If no content key was found, this will usually [8] result in an error.

  • If a single content key was found, it must usually [8] apply to the entire timespan [7] covered by the CPIX document.

  • If multiple content keys were found, then their sets of matching timespans MUST NOT overlap. Holes in the timespan covered by the CPIX document [7] (that is, periods for which no content key applies) are usually [8] not allowed.

Footnotes