Multi-DRM 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. Gateway type (refer to License Gateway API Guide)

    • When PallyCon cloud server receives license request from multi-DRM client, it first checks service site's callback page to see if the user has valid permissions.
    • In the case of a request from an authorized user, the service site returns information such as authentication, usage rights (unlimited, fixed period) and various security options to the PallyCon cloud server through the callback gateway web page.
    • PallyCon cloud server receives the response from the callback page and issues the license to the client.
  2. Token type (refer to License Token API Guide)

    • When a multi-DRM client tries to play DRM content, the client requests a token to the service site in order to acquire DRM license. The service site verifies that the user requesting the token has permission to the content, and then issues a token from the PallyCon cloud server to the client.
    • The service site can set usage rights (expiration date or unlimited) and various security options through the token REST API.
    • 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

overview

1) Prepare Playback

  • Client (Player) receives DRM integration data (PallyCon CustomData or token) from the service site to play DRM contents and attempts to play DRM contents.

2) License Request

  • Client sets PallyCon Custom Data or token into license challenge data and sends the data (created by native DRM agent) to PallyCon Multi-DRM Cloud Server.

3) Callback User Authentication

  • In case of gateway type integration, PallyCon Multi-DRM Cloud Server requests user authentication to service site via gateway interface page.
  • In the token-based integation, user authentication is handled at the service site before token issuance, so this process is omitted.

4) Response Usage Right Info

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

5) License Issuance

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

Widevine Modular / PlayReady DRM License Integration

Request

  • Request URI : https://tokyo.pallycon.com/ri/licenseManager.do
  • Request Method : POST
  • There are two ways to send custom data: Custom HTTP Header, URL Parameter. In the case of PlayReady, the customdata field of the PlayReady Challenge is also available (only license token string).
Name Value
pallycon-customdata-v2 Use custom data or token values depending on the user authentication method.
1) base64 encode(PallyCon Custom Data v2 Format)
2) license token string (refer to License Token API)

POST body : License Challenge Data created by platform’s native DRM client

Response

  • Succeess
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
{"eccorCode": "error code","message": "error message"}

FairPlay Streaming DRM License Integration

To apply FPS DRM, 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. Get the package from Apple and send the below three items to INKA
- FPS Certification File ( .der or .cer format )
- FPS Private Key File ( .pem format )
- FPS Application Secret Key (ASK)

1. FPS Certification File download integration spec

To implement FPS, client app should download FPS Certification (.cer) File from PallyCon Server using the below integration spec.

Request

Parameter Value
siteid Service Site ID(4 byte) - from PallyCon Admin site

Response

  • Success
Name Value
status code 200 OK
response body base64 encoding (fps certification cer)
  • Failure
Name Value
status code 200 OK
response body JSON Data {"errorCode": "error code", "message": "error message"}

2. FPS License Integration Spec

Request

Name Value
pallycon-customdata-v2 Use custom data or token values depending on the user authentication method.
1) base64 encode(PallyCon Custom Data v2 Format)
2) license token string (refer to License Token API)
  • 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"}

PallyCon Custom Data v2 Format

JSON Format

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

Custom Data JSON Format

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

Example

PallyCon Customdata v2 string
{
     "drm_type":"Widevine", 
     "site_id":"DEMO",
     "data":"4wvWFelCQ4ynPUaCSWeb1fcNuFUFqFhEH0jivn11OStvVPP/05wUkNhdKCGchNz1"
}

custom data json string
{"user_id":"test", "cid":"test cid"}

“pallycon-customdata-v2” : “eyJkcm1fdHlwZSI6IldpZGV2aW5lIiwgInNpdGVfaWQiOiJERU1PIiwgImRhdGEiOiI0d3ZXRmVs
Q1E0eW5QVWFDU1dlYjFmY051RlVGcUZoRUgwaml2bjExT1N0dlZQUC8wNXdVa05oZEtDR2NoTnox
In0NCg==”

AES256 Encryption

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

AES256 Encryption/Decryption should be processed as below using site authentication key which is created by ‘Service Request’ on PallyCon Admin site. ( The key can be found on PallyCon Admin’s settings page )

Error Code

Error Code Error Message
1002 Trial plan’s license limit or user limit exceeded.
1003 Cannot find the Site ID.
1004 The Site ID's service is stopped.
1005 Trial plan period ended.
1006 Failed to decrypt SITE KEY.
2001 DB connection failed.
2701 Failed to write license issuance record on DB.
2702 Failed to write unsuccessful license record on DB.
7001 Cannot find package info.
7002 Failed to create data for Content Usage Info URL.
7006 Failed to decrypt KEY on license request.
7007 Failed to parse pallycon-customdata.
7008 Failed to decrypt pallycon-customdata.
7009 Failed to parse token.
7010 Cannot find token data.
7011 Token is expired.
7012 Does not match with token's CID.
7013 Invalid JSON data in token.
7016 Invalid token.
7017 Failed to save token use history.
7018 Invalid DRM type in token.
7101 Failed to create Widevine license request data.
7102 Failed to create Widevine license.
7103 Failed to communicate with Widevine license server.
7104 This Site ID does not have Widevine service.
7105 Cannot find Widevine Device ID.
7106 Failed to get Widevine service cert.
7201 Failed to create PlayReady license.
7202 Failed to communicate with PlayReady license server.
7203 Failed to create request data for PlayReady license.
7204 Failed to read request data for PlayReady license.
7205 Failed to parse PlayReady reqeust data.
7206 No PlayReady Customdata in request.
7300 Failed to decrypt FairPlay Streaming service cert.
7301 This Site ID does not have FairPlay Streaming service.
7302 Cannot find private key for FairPlay Streaming.
7303 Invalid FairPlay Streaming key for the Site ID.
7304 Failed to create FairPlay Streaming license.
7305 FairPlay Streaming SPC value is Null.
7306 FairPlay Streaming Device ID is Null.
8002 Custom Error. Contains error code and message returned from callback gateway page for user authentication. (JSON format) {"ERROR":”custom error code", "MESSAGE":"custom error message"}
8004 Invalid nonce value.
8006 Invalid XML data from gateway.
8701 Failed to access Content Usage Info URL.
8705 Invalid URL for Content Usage Info.
8706 Failed to decrypt data from Content Usage Info URL.
8707 Invalid start or end datetime for playback period.
8708 Invalid datetime format for playback period.
8709 Start of playback period should be earlier than end of the period.
8710 Start of playback period has not come yet.
8711 Playback period is over.
8712 Invalid HDCP setting.
8715 Invalid CGMS-A setting.
8716 Invalid APS setting.
9001 Missing request parameter.
9999 Unsupported mode.

Examples

PallyCon Customdata v2 string
{
     "drm_type":"Widevine", 
     "site_id":"DEMO",
     "data":"4wvWFelCQ4ynPUaCSWeb1fcNuFUFqFhEH0jivn11OStvVPP/05wUkNhdKCGchNz1"
}
custom data json string 
{"user_id":"test", "cid":"test cid"}

1) Using Custom HTTP Header

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

2) Using URL parameter

license url = “https://tokyo.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>

PallyCon Custom Data Format (Old version)

DRMType(1) + SiteID(4) + base64 E( aes256 E ( json data ))

Name Value
DRM Type Native DRM Type
"W": Widevine, "P": PlayReady, "F": FairPlay Streaming
SiteID Service Site ID created by PallyCon (4byte)
JSON Data User Authentication data
AES256 encryption and base64 encoding

JSON Data Format

{ "user_id": "user id", "cid": "content id", "oid": "optional id" }

Name Value
user_id Service Site User ID
cid Content ID
oid Optional data (such as order info) which needs to be sent to service site for the integration.

Example

- DRM: Widevine Modular,
- Site ID: DEMO,
- JSON: {"user_id": "test_user", "cid":"DEMOCID1", "oid":""}

“pallycon-customdata” : “WDEMOeGNlZWRzIHRoZSBzaG9ydCm5hbCBwbGVhc3VyZS4=”

1) Using Custom HTTP Header

setRequestHeader(“pallycon-customdata”, “WDEMO4wvWFelCQ4ynPUaCSWeb1fcNuFUFqFhEH0jivn11OStvVPP/05wUkNhdKCGchNz1”);

2) Using URL parameter

license url = “https://tokyo.pallycon.com/ri/licenseManager.do?pallycon-customdata=WDEMO4wvWFelCQ4ynPUaCSWeb1fcNuFUFqFhEH0jivn11OStvVPP/05wUkNhdKCGchNz1”

results matching ""

    No results matching ""