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 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 Operational Vault (OpVault) that matches customers' PRM-enabled licence servers is also used.
For SDK 5 to work with PRM, Operational 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, managing keys, decrypting streams and maintaining 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.
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 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.
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 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.
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) is available for testing.