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. These standard interfaces are not possible in some system architectures, for example, where an API gateway is used. The customer-ssm mode facilitates secure session management in such systems.

The client application handles session management, licence acquisition, and renewal when using the SDK in customer-ssm mode. The SDK prompts the client application when these operations are required, using a pair of callbacks provided in the license delegate.

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:

CODE

let fairplayCertificate = getFairplayCertificate(certificateURL: fairplayCertificateURL) 
let customerSSMDelegate = OTVCustomerSSMDelegate(certificate: fairplayCertificate)

let customerCallback = CustomerCallback(licenseURL: licenseURL, ssmServerURL: ssmServerURL) 
customerSSMDelegate.setCallback(customerCallback)

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

CODE

@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: "license-request" (inital) or "license-renew" (subsequent periodic renewal)
   - Returns: tuple containing the licence data and the heartbeat period.
   */

  func license(keySystem: String, payload: Data, licenseType: OTVLicenseRequestType) -> 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.

CODE

open func license(keySystem: String, payload: Data, licenseType: OTVLicenseRequestType) -> 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. Set using the OTVLicenseRequestType enumeration

OTVLicenseRequestType eum

CODE

///License request type

@objc(OTVLicenseRequestType)
public enum OTVLicenseRequestType: Int {
  case request
  case renewal
}

Key System	Identifier
FairPlay	94CE86FB-07FF-4F43-ADB8-93D2FA968CA2

License return value

The license callback will return a instance of OTVSSMLicenseResponse.

CODE

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 is enforced by a short duration licence which requires periodic renewal. For other systems, the application uses the heartbeat API on the SSM server. The heartbeat callback prompts the application to use this API, and has no parameters or return values. If the callback fails, the application must take any necessary actions

OTVSSMLicenseResponse

The OTVSSMLicenseResponse is a container class used to hold the full license response (license/ckc data, the heartbeat period and the renewal type)

CODE

  /// OTVSSMLicenseResponse may take the values of the license data and the heartbeat period during initialisation.
    /// - Parameters:
    ///   - license: the license/ckc data
    ///   - heartbeat: the heartbeat period in seconds
    ///   - renewType: OTVLicenseRenewType.heartbeat or OTVLicenseRenewType.enforced. How the session is maintained across heartbeat periods, defualt value is OTVLicenseRenewType.enforced
  public init(license: Data? = nil, heartbeat: Int = 0, renewType: OTVLicenseRenewType = OTVLicenseRenewType.enforced) {