PRM-protected playback with PAK

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

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

Handling of 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. A specific Operator Vault (OpVault) that matches customers’ PRM-enabled licence servers is also used.

For SDK 5 to work with PRM, Operator Vaults 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, management of keys, decryption of the encrypted streams and maintains device-specific security checks.

PRM-protected content assets are raw-encrypted HLS streams using the single key scenario (the same key is used for all tracks).

The CONNECT Player needs the decryption keys to decrypt protected content. Licences need to be acquired from the licence server portal to play specific content; once a valid licence for a content item is retrieved, the keys 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 decryption keys. To simplify the integration of CONNECT SDK 5.x in the application, the SDK provides an interface and a default class implementing it, for handling communication with the PRM licence server.

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, underneath 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 is the case for Widevine, a callback class is required to implement (non-silent) communication with the Customer’s licence server. The OTVPRMNonSilentCallback interface expects its implementation to provide the following callback methods:

• executeInitializeRequest() - for initialisating the device against the licence server.
• executeKeyRequest() - for requesting decryption keys for a stream.
• executePredeliveryKeyRequest() - for retrieving decryption keys before actual playback; for example, for offline playback.

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 authorization tokens (used during device initialization) has two modes:

• "SSP AuthZ" for token-based and server-based authorization modes.
• "SDP AuthZ" for callback-based authorization 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 version of 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) is available for testing.