Secure Session Management

The SDK supports NAGRA’s Secure Session Manager (SSM), enabling monitoring and limiting the number of sessions in parallel, chiefly to protect against account sharing. Security is enhanced as the session manager is linked to the license manager, with the licence regularly renewed during playback.

When the player acquires or renews a licence for playback, it also needs to obtain a session token. The licence server provides the session tokens (per content or account), counts the number of active sessions, and limits the number of permitted concurrent sessions.

An SSM session is set up when a user starts playback of a content item and is torn down when playback stops. SSM also uses Widevine’s periodic licence renewal as a heartbeat; if the SSM server does not receive a heartbeat at regular intervals, it deems the session expired, the licence is not renewed, and the session count drops by one. This ensures that even if no teardown message is sent by the player (for example, a device lost network connection), the session expires anyway.

The SDK provides an implementation of OTVMediaDrmCallback dedicated to handling licence key requests with a licence server supporting SSM - OTVSSMHttpMediaDrmCallback.

Example code

To implement Widevine with SSM, include the following methods to fetch the relevant data for the stream, licence server and SSM server. Ensure you have or implement methods to fetch the data relevant to the stream you want to play, the licence server you work with, and the SSM server.

Instantiate OTVSSMHttpMediaDrmCallback with the Licence Server URI.

JAVA

OTVSSMHttpMediaDrmCallback drmCallback = new OTVSSMHttpMediaDrmCallback(DRM_URI, SSM_URI);

Configure the DRM handler using the setKeyRequestProperty() method. The values below are for illustration purposes only as they are specific to the type of licence server, the account and the content. The nv-authorizations key-value pair is mandatory for working with SSM.

JAVA

    drmCallback.setKeyRequestProperty("Accept",            "application/octet-stream");
    drmCallback.setKeyRequestProperty("Content-Type",      "application/octet-stream");
    drmCallback.setKeyRequestProperty("nv-tenant-id",      TENANT_ID_STR);
    drmCallback.setKeyRequestProperty("nv-authorizations", STREAM_TOKEN);

Assign the OTVHttpMediaDrmCallback instance to your OTVVideoView.

JAVA

otvVideoView.setMediaDrmCallback(drmCallback);

Playback is started by assigning the path to the OTVVideoView instance.

JAVA

otvVideoView.setVideoPath(STREAM_URI);

Stopping playback (stopPlayback() in OTVVideoView) will tear down the SSM session for this content.

Error reporting for SSM

The setOnErrorListener() method in OTVVideoView enables you to register for errors in general and SSM errors in particular. The application has to instantiate a class that implements the OnErrorListener interface. This interface requires the implementation of one error callback:

JAVA

boolean onError(MediaPlayer mp, int what, int extra)

The first parameter passed to the callback is the object referencing the OTVMediaPlayer from which the error is reported. The two other parameters contain information about the nature of the error. For example, the main application can register an onError() callback.

JAVA

  ...
  mOTVVideoView.setOnErrorListener((mp, what, extra) -> {
    OTVLog.i(TAG, "onError - Enter - what: " + what + ", extra: " + extra);
    return true;
  });
  ...

In the context of SSM errors, the following values may be assigned with the what parameter.

JAVA

  /** SSM setup session request get failure. */
  public static final int MEDIA_ERROR_OPY_SSM_SETUP_FAILURE = -1352;
  /** SSM session renewal request get failure. */
  public static final int MEDIA_ERROR_OPY_SSM_RENEWAL_FAILURE = -1353;
  /** SSM session teardown request get failure. */
  public static final int MEDIA_ERROR_OPY_SSM_TEARDOWN_FAILURE = -1354;

The extra parameter is an integer containing the errors as defined in the SSM API.

See SSM error codes for the list of errors

An operator has the option to kill an existing session (for example, if the QuickMark tool detects a re-streaming breach). In this case, the player will get a Widevine license renewal failure. The error reported by the license server (see Secure Session Manager (SSM)) will be 3002 (Unknown session):

{
“code” : 404,
"errorCode": 3002,
"message": "Not Found"
}

The playback will stop, and the player will report error what=-1353 (renewal failure) or what=-1354 (teardown failure), and extra=3002 (Unknow session, as reported by server).