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 <mp4 URL>  build CPIX evaluator and evaluate tracks
  evaluate-tracks-for-timespan <mp4 URL> <start> <end>
                             build CPIX evaluator and evaluate tracks
                             for timespan
  print-cpix                 print internal CPIX structure
  select-kid <KID>           build CPIX evaluator and select key id

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 select-kid command

cpix_verify <cpix URL> select-kid <KID>

The select-kid command loads a CPIX document from <cpix URL>, builds an evaluator from it, and prints the data used to generate signaling or apply content encryption if the encryption key identified by <KID> were selected.

The evaluate-tracks command

cpix_verify [--allow-unencrypted] <cpix URL> evaluate-tracks <mp4 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 <mp4 URL> [2]. 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 <mp4 URL> <start> <end>

The evaluate-tracks-for-timespan command loads 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 <mp4 URL> [2], limited to the time range denoted by <start> and <end> command-line arguments (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.
[2](1, 2) cpix_verify does not accept .ism files as input, but it does accept .ismv files. See Program Usage for how to generate an .ismv file from an .ism file using the mp4split command.