Multi-DRM Native Client Integration Guide

Overview

PallyCon Multi-DRM Cloud Server provides DRM license issuance for Google Widevine Modular, Apple FairPlay Streaming and Microsoft PlayReady.

There are two types of methods for issuing multi-DRM (FPS, Widevine, PlayReady, NCG) licenses from PallyCon cloud server.

  1. Callback type

    • When PallyCon cloud server receives license request from multi-DRM client, it sends the user authentication data (Auth Data) to the callback page in the customer’s backend to see if the user has valid rights on the content.
    • After the user is authenticated and authorized, the service site’s callback page responds content usage rights (e.g. unlimited or fixed period) and various security options to the PallyCon cloud server.
    • PallyCon cloud server receives the response from the callback page and issues the license to the client.

  2. Token type (refer to License Token Guide)

    • When a multi-DRM client tries to play DRM content, the service site can create license token with pre-defined specification and send the token to the client.
    • The service site can set usage rights (expiration date or unlimited) and various security options through the token data.
    • When a client requests a license with a token, the PallyCon cloud server validates the token and issues a license.

This document guides how to acquire DRM license from PallyCon Multi-DRM Cloud Server to playback content on various multi-drm client platforms without using PallyCon client SDKs.

Multi-DRM License Issuance

  1. Prepare Playback

    • A client player receives DRM custom data (auth data or license token) from the service site’s backend to play DRM contents.

  2. License Request

    • The client sets the custom data into license challenge data (created by native DRM agent) and sends it to PallyCon Multi-DRM Cloud Server.

  3. Callback User Authentication

    • In case of callback type integration, PallyCon Multi-DRM Cloud Server requests user authentication to service site via license callback page.
    • In the token-based integration, user authentication is handled between the service site’s backend and client player before generating a token. So this process is not applicable for token integration.

  4. Response Usage Right Info

    • After user authentication, service site returns content usage right info to PallyCon server via callback interface page.

  5. License Issuance

    • PallyCon Multi-DRM Cloud Server creates and returns license data by DRM type, using usage right info received from callback page or token request.

Widevine Modular / PlayReady DRM License Integration

Request

  • Request URI : https://license-global.pallycon.com/ri/licenseManager.do

  • Request Method : POST

  • DRM custom data can be sent to license server via various ways such as custom HTTP header or URL Parameter. In the case of PlayReady, the customdata field of the PlayReady Challenge is also available (for license token only).

Name Value
pallycon-customdata-v2 Input the user auth data or license token depending on the DRM integration type.
1) base64 encode(PallyCon Auth Data Format)
2) license token string (refer to License Token Guide)

In the POST body, enter the license challenge data generated by the native DRM client module.

Response

  • Success
Name Value
status code 200 OK
response body native DRM license data
- Widevine Modular: binary data
- PlayReady DRM : base64 encoding string
  • Failure
Name Value
status code 200 OK
response body JSON Data {“errorCode”: “error code”,“message”: “error message”}

FairPlay Streaming DRM License Integration

To apply FPS DRM, content service site should follow the below steps before starting integration.

  1. Enroll in Apple developer program ( https://developer.apple.com/support/enrollment/ )
  2. Request FPS Deployment Package to Apple ( https://developer.apple.com/streaming/fps/ )
  3. Using the deployment package, create the below four items and register them on Integration Settings page of PallyCon Console site.
- FPS certificate file (.der or .cer)
- Private key file (.pem)
- Password for the private key (string)
- Application secret key (ASK) string

Please refer to the FairPlay Cert Registration Tutorial for details on the above registration process.

1. FPS Certification download specification

To integrate FPS DRM, client app should download FPS Certificate data from PallyCon Server using the below API.

Request

Parameter Value
siteId Service Site ID(4 bytes) - from PallyCon Console site

Response

  • Success
Name Value
status code 200 OK
response body base64 encoding (fps certificate data)
  • Failure
Name Value
status code 200 OK
response body JSON Data {“errorCode”: “error code”, “message”: “error message”}

The FPS Cert URL is provided for your convenience. If needed, a cert file (.cer or .der) may be hosted on your own server and its URL may be used instead of the above specification.

2. FPS License Integration Spec

Request

Name Value
pallycon-customdata-v2 Use callback auth data or license token depending on the license integration type.
1) base64 encode(Auth data for callback)
2) license token string (refer to License Token Guide)
  • POST body : spc=‘base64 encoding(spc data)’
Parameter Value
spc base64 encoding ( SPC data created by native drm client )

Response

  • Success
Name Value
status code 200 OK
response body base64 encoding (CKC data from FPS KSM)
  • Failure
Name Value
response body JSON Data {“errorCode”: “error code”, “message”: “error message”}

Auth Data Format for Callback Integration

{
    "drm_type": "<drm type>",
    "site_id": "<site id>",
    "data": "<base64 encoding(aes256 encryption(auth info json string))>"
}
Name Value
drm_type DRM type (“NCG”, “Widevine”, “PlayReady”, “FairPlay”)
site_id Service site ID issued by PallyCon Cloud Service (4byte)
data User authentication info (auth info json string) -> aes256 encryption -> base64 encoding

Auth Info JSON Format

{
    "user_id": "user id",
    "cid": "content id",
    "oid": "optional id"
}
Name Value
user_id ID of service site’s end user
cid Unique ID of content
oid Optional data (such as order info) which needs to be sent to service site for the integration.

AES256 Encryption

AES256 Encryption
- mode : CBC
- key : 32 byte (Site key from PallyCon Console site)
- iv : 16 byte (0123456789abcdef)
- padding : pkcs7

AES256 Encryption/Decryption should be processed as below using site key which is shown on PallyCon Console site. ( The key can be found on PallyCon Console’s settings page )

Examples

Auth info json string 
{"user_id":"test", "cid":"test cid"}

Auth data before base64 encoding
{
     "drm_type":"Widevine",
     "site_id":"DEMO",
     "data":"4wvWFelCQ4ynPUaCSWeb1fcNuFUFqFhEH0jivn11OStvVPP/05wUkNhdKCGchNz1"
}

1) Using Custom HTTP Header

setRequestHeader("pallycon-customdata-v2", "eyJkcm1fdHlwZSI6IldpZGV2aW5lIiwgInNpdGVfaWQiOiJERU1PIiwgImRhdGEiOiI0d3ZXRmVs
Q1E0eW5QVWFDU1dlYjFmY051RlVGcUZoRUgwaml2bjExT1N0dlZQUC8wNXdVa05oZEtDR2NoTnox
In0NCg==");

2) Using URL parameter

license url = "https://license-global.pallycon.com/ri/licenseManager.do?pallycon-customdata-v2=eyJkcm1fdHlwZSI6IldpZGV2aW5lIiwgInNpdGVfaWQiOiJERU1PIiwgImRhdGEiOiI0d3ZXRmVs
Q1E0eW5QVWFDU1dlYjFmY051RlVGcUZoRUgwaml2bjExT1N0dlZQUC8wNXdVa05oZEtDR2NoTnox
In0NCg=="

3) Using PlayReady customdata ( only license token string )

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>AcquireLicense
    xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols">
<challenge>
...

<ClientInfo> ... </ClientInfo>
<CustomData>eyJ0b2tlbiI6IlRhXC9SdkJBZ1U4ZDdwSExqeXVyK2MxTU05N1pXUm1pSmdXYzJcL1U5MnBPbWJhOXNtXC9ybHdmc0lNM2ZValhzSTUiLCJzaXRlX2lkIjoiREVNTyIsImRybV90eXBlIjoiUGxheVJlYWR5IiwiY2lkIjoidHJheSJ9</CustomData>
Previous
Next

Last updated on Aug 17, 2021