Playback of PRM encrypted content (Software PRM)
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.
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.
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.
The PRM versions of the integration.aar and production.aar files can do everything the non-PRM versions can, at the expense of library size and library load time.
A specific Operational 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.
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 is the case 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 initialization request payload.
getInitializationClientProtectedPrivateData()gets the data needed to generate an initialization 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 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
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.
The following are required:
- The Operational Vault file for working with the licence server is present and configured with the
unlockJAVADescramblingForHybridModeflag set to
- The application is granted with
- 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.