Secure Session Management

The Secure Session Manager (SSM) service integrates with the SSP license server and limits simultaneous encrypted playback. When the client device starts an encrypted playback, the CONNECT Player SDK requests a session token from the SSM server. The session token is used as part of the license request, and the SDK keeps a heartbeat with the SSM server to maintain the SSM session. The SDK tears down the SSM session when the playback stops. If the request for a session token fails (potentially due to too many existing playback sessions), the license request will fail, and playback can not continue.

Example code

As with standard encrypted playback with SSP, an OTVSSPLicenseDelegate is created to handle the requests with SSP with the SSM service.

The OTVSSPLicenseDelegate initialiser takes two optional parameters that configure the SSM functionality:

OTVSSPLiceseDelegate.init(certificateURL:licenseURL:ssmServerURL:syncSSMSetupTeardown:)
- ssmServerURL is the URL to the SSM service
- syncSSMSetupTeardown specifies whether network requests to set up and teardown the SSM session are made synchronously or not. Setting syncSSMSetupTeardown to true blocks the main thread while the network requests are being made.

If the OTVSSPLicenseDelegate is initialised with ssmServerURL, every playback will have an SSM session. When the playback stops, the player will release the session when OTVAVPlayerItem is de-initialised.

FPS Airplay support

A protocol OTVSSPTokenCallback implements and passes the instance of this class to SDK using setToken() API introduced in OTVSSPLicenseDelegate. The setToken() API of OTVSSPLicenseDelegate takes the instance of OTVSSPTokenCallback class as a parameter:

OTVSSPLiceseDelegate.setToken(sspTokenCallback: OTVSSPTokenCallback)

When SSM encrypted content playback switches from the Device (iOS/iPad) to Airplay or vice versa, the Apple framework triggers a new license request inside the player SDK. The Player SDK requests a new token using the token() method of class implementing OTVSSPTokenCallback.

func token() -> String?

Error handling

When SSM errors occur, the player posts the following notifications:

OTVSSMSetupErrorNotification
OTVSSMTeardownErrorNotification
OTVSSMHeartbeatErrorNotification

The player should not continue playback once any of these notifications are received. The notification userInfo contains information on any HTTP error codes and SSM error messages.

SSM Errors

JS

NotificationCenter.default.addObserver(self, selector: #selector(didReceiveSSMError(_:)), name: .OTVSSMSetupErrorNotification, object: nil)
NotificationCenter.default.addObserver(self, selector: #selector(didReceiveSSMError(_:)), name: .OTVSSMHeartbeatErrorNotification, object: nil)
NotificationCenter.default.addObserver(self, selector: #selector(didReceiveSSMError(_:)), name: .OTVSSMTeardownErrorNotification, object: nil)

@objc func didReceiveSSMError(_ notification: NSNotification) {
    let userInfo = notification.userInfo
	// SSM Error code relating the to the reasoning of the error.
    let ssmError = userInfo?["errorCode"] as? Int
	// HTTP status code of the error e.g 404
    let code = userInfo?["code"] as? Int
	// Message describing the reason of the error.
    let message = userInfo?["message"] as? String
    NSLog("SSM Service Error happened: Error \(String(describing: ssmError)) HTTP status code \(String(describing: code)) and message \(String(describing: message))")
    let error = ssmError ?? NSError(domain: "SSM Service Error", code: ssmError, userInfo: [NSLocalizedDescriptionKey: message as Any])
	
	
  }

Background SSM behaviour

When the application goes to the background, the SSM service will behave in the following ways:

Normal background mode
Playback can resume when the application returns to the foreground if no error notification is received.
If an OTVSSMHeartbeatErrorNotification is received, the application should stop playback and attempt to zap to the same stream to resume playback securely.
Picture-in-picture mode
When PIP is enabled, and the application goes to the background, the SSM service works as normal.