Customer SSM

To test this feature and view the example code, please see the  Apple (FPS) 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  Apple (FPS) SDK 5 Integration Guide.

For SSP with customer-ssm, configure the DRM as follows:

let fairplayCertificate = getFairplayCertificate(certificateURL: fairplayCertificateURL) 
let customerSSMDelegate = OTVCustomerSSMDelegate(certificate: fairplayCertificate)
let customerCallback = CustomerCallback(licenseURL: licenseURL, ssmServerURL: ssmServerURL) 
customerSSMDelegate.setCallback(customerCallback)
customerCallback.setupSSM(with token: ssmToken)
OTVDRMManager.shared.setLicenseDelegate(customerSSMDelegate)

You need to implement the getFairplayCertificate function to return the certificate as Data type. Implement CustomerCallback under the protocol OTVCustomerCalback.

OTVCustomerCallback protocol

@objc public protocol OTVCustomerSSMCallback: NSObjectProtocol {

  /**
   Returns the licence containing Content Key Context (CKC) message, and heartbeat period.
   
   - Parameter keySystem: String corresponding to the desired key system (Fairplay for iOS)
   - Parameter payload: token for licence retrieval
   - Parameter licenseType: request (inital) or renew (subsequent)
   - Returns: tuple containing the licence data and the heartbeat period.
   */

  func license(keySystem: String, payload: Data, licenseType: String) -> OTVSSMLicenseResponse
  
  /**
   Calls the application supplied heartbeat function
   */
  func heartbeat()
}

License callback

The SDK will call the license() 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.

open func license(keySystem: String, payload: Data, licenseType: String) -> OTVSSMLicenseResponse 

License parameters

• keySystem will be identified using the DASH ContentProtection Scheme identifier as shown in the table below.
• payload as passed from the ckcMessage() as spc data, and will be required for the licence acquisition.
• licenseType indicates 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".

License return value

The license callback will return a instance of OTVSSMLicenseResponse.

class OTVSSMLicenseResponse: NSObject {
	var licence: Data?
	var heartbeat: Int=0
}

Licence format

The license in instance OTVSSMLicenseResponse returned from license() callback is the ckc message should pass to ckcMessage() as return value.

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.