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.
We do not recommend the use of CPIX documents unless required for advanced use cases such as different DRMs / KID:CEKs per playout format, multiple keys and key rotation. Not all use cases supported by our non-CPIX DRM options can be represented in a CPIX document. The use of CPIX documents in combination with non-CPIX based DRM options in a single server manifest is not supported.
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.1 specification. HTTPS should be used and if needed basic auth or digest may be added through the use of a proxy.
Minimum info necessary¶
To create a CPIX document, the minimum information necessary is:
- Must have a Key ID (KID) used to identify the content and associate it with a the (secret) Content Encryption Key.
- Must have a Content Encryption Key (CEK) used to encrypt the content with.
- 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
ContentProtectionDataused for signaling DRM in the MPEG-DASH playout manifest.
- Optionally has
HLSSignalingDataused for signaling DRM in the Apple HLS Manifest.
- Optionally has
SmoothStreamingProtectionHeaderDataused for signaling DRM in the Microsoft Smooth Streaming playout manifest.
- Optionally has
HDSSignalingDataused for signaling DRM in the HTTP Dynamic Streaming playout manifest.
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 19 20
<?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> <ContentProtectionData>PCEtLSBXaWRldmluZSAtLT4KPENvbnRlbnRQcm90ZWN0aW9uCiAgeG1sbnM9InVybjptcGVnOmRhc2g6c2NoZW1hOm1wZDoyMDExIgogIHNjaGVtZUlkVXJpPSJ1cm46dXVpZDpFREVGOEJBOS03OUQ2LTRBQ0UtQTNDOC0yN0RDRDUxRDIxRUQiPgo8L0NvbnRlbnRQcm90ZWN0aW9uPg==</ContentProtectionData> <HLSSignalingData></HLSSignalingData> </DRMSystem> </DRMSystemList> </CPIX>
- The document's
<ContentKeyList>contains a single
<ContentKey>element with key ID
- The base64-encoded CEK for this key ID is
- 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.
- The base64-encoded
<ContentProtectionData>which will be used for signaling the DRM in the DASH manifest is listed on line 16.
- If the signaling for a specific playout format is not known, it is possible to request USP to generate it. To request generation, the signaling element must be present and empty, listed on line 17. For the full support list of generating signalings, see CPIX Signaling Behaviour
- 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.
- It is possible to explicitly signal a Key Initialization Vector (IV) by
explicitIVattribute 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.
<HLSSignalingData> sub-element of the
can be used to signal the DRM specific information that must be included in the
HLS playlist. There can be up to two
<HLSSignalingData> sub-elements, with
one targeting the HLS variant playlist, and the other for the HLS master
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 in the HLS variant playlist:
For the HLS master playlist:
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> <HLSSignalingData playlist="master">I0VYVC1YLVNFU1NJT04tS0VZOk1FVEhPRD1TQU1QTEUtQUVTLFVSST0iZGF0YTp0ZXh0L3BsYWluO2Jhc2U2NCxBQUFBUFhCemMyZ0FBQUFBN2UrTHFYbldTczZqeUNmYzFSMGg3UUFBQUIwYURYZHBaR1YyYVc1bFgzUmxjM1FpREhSbGMzUWdZMjl1ZEdWdWRBPT0iLEtFWUZPUk1BVD0idXJuOnV1aWQ6ZWRlZjhiYTktNzlkNi00YWNlLWEzYzgtMjdkY2Q1MWQyMWVkIixLRVlGT1JNQVRWRVJTSU9OUz0iMSI=</HLSSignalingData> </DRMSystem>
Note how on line 6 the attribute
playlist="master" indicates the signaling
to be placed in the HLS master playlist.
As stated above, a CPIX document may contain a
that consists of a list of
<ContentKeyUsageRule> elements. Usage rules
limit the applicability of a particular
<ContentKey>, identified by the
kid attribute, to a specific track or timespan.
<ContentKeyUsageRule> element contains a number of filtering
elements. There are different types of filtering elements; most filter
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
<LabelFilter> element from the CPIX 2.1 specification is not
Your CPIX document must be unambiguous; be sure to configure your filtering rules such that at most one content key is selected.
There are some known issues in our current CPIX implementation: