Customer SSM

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

In nagra-ssp DRM mode, the CONNECT Player SDK supports Secure Session Management using the standard SSP API to perform session setup and management, and licence acquisition and renewal as necessary. In some system architectures, for example where an API gateway is used, use of these standard interfaces is not possible. The customer-ssm mode facilitates secure session management in such systems.

When using the SDK in customer-ssm mode, all session management, licence acquisition and renewal is handled by the client application. The SDK prompts the client application when these operations are required, using a pair of callbacks provided in the player configuration.

Configuring the player for customer SSM

Configuration of the player is described in the Browsers and Connected TV SDK 5 Integration Guide. For SSP with customer-ssm, configure the DRM as follows:

otvtoolkit: {
    drm: {
        system: "customer-ssm",
        config: {
            customerSsmCallback: {
                getLicence: applicationLicenceAcquisitionFunction,
                heartbeat: applicationHeartbeatRenewalFunction
            },
            // Optional: If the widevineServerCertificate is not set then two callbacks will be made for every widevine licence request
            widevineServerCertificate: "base64 string containing the certificate"
        }
    }
}

getLicence callback

The SDK will call the getLicence callback when a licence is first required, and periodically when it is required to be renewed. It will be necessary to perform a secure session setup before acquiring the licence for the first time.

function getLicence(keySystem, payload, requestType)

getLicence parameters

• keySystem will be identified using the DASH ContentProtection Scheme identifier as shown in the table below.

• payload as passed from the browser CDM, and will be required for the licence acquisition.

• requestType will indicate whether this is the first request for a licence, or whether the request is to renew an existing licence. It will have the value "license-request" or "license-renewal".

getLicence Return Value

The getLicence callback will return a promise.

• If the licence acquisition/renewal is unsuccessful, the promise should reject with an error message.

• If successful the promise should resolve with the following parameter:

   {
       licence: licenceReturnedFromSsp
       heartbeat: sessionRenewalPeriodInSeconds
   }

Licence Format

PlayReady
The licence should be passed to the SDK (via the resolved promise) in the same format in which it is acquired from SSP, i.e. a text or XML string.

Widevine
The licence should be passed back to the SDK in binary format as a Uint8Array. If the Application/JSON API is used to renew the licence, it must be packaged as follows:

try {
    var responseJSON = JSON.parse(xhr.response);

    // Convert the licence to a Uint8Array to return to the SDK
    var string = atob(responseJSON.license);
    var buffer = new ArrayBuffer(string.length);
    var array = new Uint8Array(buffer);
    for (var i = 0, strLen = string.length; i < strLen; i++) {
        array[i] = string.charCodeAt(i);
    }
    resolve(array);
} catch () {
    reject("Unable to parse returned JSON licence");
}

Heartbeat callback

In systems where it is supported, the secure session will be enforced by a short duration licence which will require periodic renewal. For other systems, the application will need to use the heartbeat API on the SSM server. This callback will prompt the application to use this API. This callback has no parameters and no return value. If the callback fails then the application must take any necessary actions.