Playback of PRM encrypted content (Software PRM)

To test this feature and view the example code, please see the PRM Example Code Quick Start guide.

The CONNECT Player SDK provides tools to enable playback of NAGRA Persistent Rights Management (PRM) encrypted streams.

Also called Software PRM, this is the most widely-used mechanism used in applications on open devices, where the device has no PRM-specific libraries installed in the Android system. For details of Hardware PRM, see the Playback of PRM encrypted content with NAGRA CONNECT feature.

In versions preceding 5.20.0, when playing PRM-encrypted streams, the CONNECT Player would download each chunk in its entirety, decrypt all of it and then hand it to the device decoder and renderer. This meant slower start-up and seek times, especially with large chunks.
From version 5.20.0 onwards, the Player can start decrypting the chunk as it is being downloaded and immediately feed the decoder with the decrypted (partial) data. This significantly improves Player performance, depending on the nature of the stream. There are no changes to the Player API for this improvement.

The EXT-X-KEY tag in the HLS media playlists specifies in the tag's URI attribute how segments should be decrypted. In the case of multiple DRM clients using the same content key, extra information can be provided to the decoders specifying the key format for the particular tag. Starting with CONNECT Player version 5.23.0, the player can interpret extra PRM information that may be passed on by the encoder in the KEYFORMAT and KEYFORMATVERSION attributes. In the case of CONNECT PRM, the KEYFORMAT attribute value should be PRMNAGRA and the KEYFORMATVERSION value is expected to be 1.

Tag example
#EXT-X-KEY:METHOD =AES-128,URI="http://keylocation?contentID=1234&prm=ewqTY29udGVud...", KEYFORMAT="PRMNAGRA",KEYFORMATVERSION="1"

Handling PRM-encrypted content requires the PRM-enabled version of the CONNECT Player SDK .aar file. In the delivery package, the PRM-enabled libraries contain -prm- in the filename; for example, sdk-prm-integration.aar and sdk-prm-production.aar. These files have all the functionality of the non-PRM versions at the expense of library size and library load time.

A specific Operator Vault (OpVault) that matches your PRM-enabled licence servers is also used and must be configured with the unlockJAVADescramblingForHybridMode flag set to true; see Prerequisites.

The PRM-enabled SDK contains a Player Access Kernel (PAK) library, which handles communication with the licence server, manages keys, decrypts streams, and maintains device-specific security checks.

PRM-protected content assets are raw-encrypted HLS media segments using a single key for all tracks on a stream. The CONNECT Player needs decryption keys to decrypt protected content, and licences must be acquired from the licence server portal to play specific content. Once a valid licence for a content item is retrieved, the key to decrypt the content can be extracted from it. The SDK operates in non-silent mode, where the licence is retrieved separately and passed over to the PAK library for the decryption key.

Enabling playback of encrypted streams typically comprises the following steps, which should be done once during an application’s lifecycle:

PRM Preparation - The PAK library is configured with OpVault and started.
Initialisation - An initialisation request is sent to the PRM server to register the device with the PRM system.
Setting the stream token - Specific for each stream - providing the token for requesting a licence.

The first two stages are typically executed once in the application’s lifecycle, whereas the last step is performed for each stream with its own token.

PRM manager and callback classes

The SDK defines the OTVPRMManager class for all the methods needed to manage PRM.

Although OTVPRMManager may be instantiated multiple times, it controls the PAK library, which is a singleton. To avoid configuration confusion, NAGRA advises you to design your application such that there is only one instance of the class. Because the PAK library is a singleton, playback of multiple PRM-protected streams is not guaranteed. Please contact NAGRA for advice if support is required.

As for Widevine, a callback class is required to implement (non-silent) communication with the PRM licence server. The OTVPRMNonSilentCallback interface expects its implementation to provide the following callback methods:

executeInitializeRequest() initialises the device against the licence server.
executeKeyRequest() requests decryption keys for a stream.
executePredeliveryKeyRequest() retrieves decryption keys before actual playback; for example, for offline playback.
setInitializationClientProtectedPrivateData() sets the data needed to generate an initialisation request payload.
getInitializationClientProtectedPrivateData() gets the data needed to generate an initialisation request payload.
setLicenseRequestClientProtectedPrivateData() sets the data needed to generate a license request payload.
getLicenseRequestClientProtectedPrivateData() gets the data needed to generate a license request payload.

Keys and device identification are cached and then stored in the PAK’s persistent database so that future requests for acquiring the same keys will use the database rather than from the licence server.

The callback class OTVSSPPRMNonSilentCallback is provided in the SDK to implement the OTVPRMNonSilentCallback interface for communication with NAGRA’s Security Services Platform (SSP) licence servers (in non-silent Direct mode).

Passing authorisation tokens (used during device initialisation) has two modes:

"SSP AuthZ" for token-based and server-based authorisation modes.
"SDP AuthZ" for callback-based authorisation mode.

For more information, please refer to your licence server documentation.

The mode can be selected using the "nv-portal-id" HTTP header. For the OTVSSPPRMNonSilentCallback class, the key and provisioning request headers can be configured using setKeyRequestProperty(), clearKeyRequestProperty() and clearAllKeyRequestProperties()Similar to the configurations for Widevine and PlayReady. Alternatively, for other licence servers providing a portal for obtaining licences, you can implement your own OTVPRMNonSilentCallback to communicate with that portal in non-silent Indirect mode. OTVPRMManager notifies the application of events regarding the PAK status via the OTVPAKReadyListener interface; this listener must be implemented to monitor the state of the PAK. An additional listener OTVPRMSessionEventListener can monitor session events.

Prerequisites

The following are required:

The Operator Vault file for working with the licence server is present and configured with the unlockJAVADescramblingForHybridMode flag set to true.
The application is granted with READ_PHONE_STATE permissions.
The SDK with PRM support has been loaded, and the player has been created.
The application has all (or can fetch) the information for the licence server and the encrypted content.
A PRM-protected encrypted stream and an Android device (not a simulator) are available for testing.