Checking CPIX documents with cpix_verify

Introduction

The cpix_verify command-line tool can be used to verify CPIX documents and check the results of content key [1] selection (see Content key selection algorithm) for a particular presentation. On success, it will print a human-readable representation of the results and return a zero exit status. Otherwise, it will print an error message and return a non-zero exit status.

Note

The human-readable representation of the results that is printed by cpix_verify is not part of its documented interface and subject to change without notice.

Getting help

Typing cpix_verify --help on the command-line will print a brief summary of its commands and options:

usage: cpix_verify [<option> ...] <cpix URL> <command>
options are:
  --allow-unencrypted        allow (partially) unencrypted playout
commands are:
  build-evaluator            build CPIX evaluator
  evaluate-tracks <input URL> ...
                             build CPIX evaluator and evaluate tracks
  evaluate-tracks-for-timespan <start> <end> <input URL> ...
                             build CPIX evaluator and evaluate tracks
                               for timespan
  print-cpix                 print internal CPIX structure

The print-cpix command

cpix_verify <cpix URL> print-cpix

The print-cpix command loads a CPIX document from <cpix URL> and attempts to parse it. This is useful for checking for basic errors in the CPIX document, such as syntax errors, forbidden elements and attributes, etc.

The build-evaluator command

cpix_verify <cpix URL> build-evaluator

The build-evaluator command loads a CPIX document from <cpix URL> and attempts to parse it and build a track evaluator. The checking performed by build-evaluator is more extensive and includes some referential integrity constraints.

The evaluate-tracks command

cpix_verify [--allow-unencrypted] <cpix URL> evaluate-tracks <input URL> ...

The evaluate-tracks command loads a CPIX document from <cpix URL>, builds an evaluator from it, and applies the Content key selection algorithm to the audio and video tracks found in its <input URL> arguments. For each track, it prints the content keys and signaling data found.

The --allow-unencrypted option controls whether unencrypted content is allowed. If it is not, a track for which no content key is found will result in an error.

The evaluate-tracks-for-timespan command

cpix_verify [--allow-unencrypted] <cpix URL> evaluate-tracks-for-timespan <start> <end> <input URL> ...

The evaluate-tracks-for-timespan command loads a CPIX document from <cpix URL>, builds an evaluator from it, and applies the Content key selection algorithm to the audio and video tracks found in its <input URL> arguments, limited to the timespan denoted by <start> and <end> (both in ISO8601 format). This is useful for testing key rotation scenarios. For each track, it prints a series of zero or more timespans with the corresponding content keys and signaling data.

Please note that the CPIX origin server may be instructed to limit the CPIX's document time range by adding the start= and end= query parameters to the <cpix URL>; see CPIX origin.

The --allow-unencrypted option controls whether unencrypted content is allowed. If it is not, a track for which no content key is found for (part of) the specified time range, will result in an error.

Footnotes

[1]	A content key in a CPIX document is identified by a Key ID (KID) and usually contains a content encryption key (CEK). In some cases, a Key IV is also specified as part of the content key.