PallyCon Multi-DRM License Token API

Overview

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

  1. Gateway type

    • 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

    • 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 describes the second method, the API of license token. Please refer to License Callback Gateway API Guide if you need gateway type integration.

License Issuance Workflow

license workflow

(1) Request token to service site

  • Client requests service site for a token to playback DRM content.

(1-1) Request token to PallyCon cloud server (refer to spec)

  • The service site checks the request received from the client and requests the token to the PallyCon cloud server if the user has permission to use the content.
  • The service site sends token request with Content ID, token expiry time and DRM license rule.

(1-2) Issue license token

  • PallyCon cloud server issues a token with requested data and response it after storing in database.

(2) Forward license token to client

  • The service site forwards the token received from the PallyCon cloud server to the client.

(3) Request license

  • The client uses the token to request a license to the PallyCon cloud server.

(4) Issue license

  • PallyCon cloud server validates the token and issues a license according to the established rules.

License Token API (JSON type)

Request Data Format

Key Value
Authorization HTTP Basic Auth (Site ID : Access Key)
  • Site ID : Service Site ID which is issued by PallyCon cloud service (4byte)
  • Access Key : Access Key of the service site which is issued by PallyCon cloud service (can be found in settings page of PallyCon Admin site)

Body

Key Value
data base64 Encoding ( aes256 Encrypt ( JSON Data string ) )

* Refer to AES256 encryption

JSON Data Format

{
    "drm_type": "<drm type string>",
    "cid":"<content id string>", 
    "token_expiry_date":"<token expiry GMT yyyy-mm-ddThh:mm:ssZ>", 
    "nonce":"<random string>", 
    "playback_policy": {
        "limit": <true|false>,
        "persistent": <true|false>,
        "duration" : <int(seconds)>,
        "expire_date": "<playback expiry GMT yyyy-mm-ddThh:mm:ssZ>"
    },
    "security_policy": {
        "hardware_drm": <true|false>,
        "output_protect": {
            "allow_external_display" : <true|false>,
            "control_hdcp": <0|1|2>
        },
        "allow_mobile_abnormal_device" : <true|false>,
        "playready_security_level": <150|2000>
    },
    "external_key": {
        "mpeg_cenc": {
        "key_id" : "<hex-string>",
            "key" : "<hex-string>",
            "iv" : "<hex-string>" ,
        },
        "hls_aes" : {
            "key" : "<hex-string>”,
            "iv" : "<hex-string>”
        },
        "ncg":{
            "cek":"<hex-string>"
        }
    }
}
Name Value Required Description
cid string Yes Unique ID of the content
token_expiry_date string Yes Token expiration time (GMT) 'yyyy-mm-ddThh:mm:ssZ'
nonce string Yes One time Random String. Should be the same string as in the request data. (max 32byes)
playback_policy json Yes license rules related with playback (refer to spec)
security_policy json No license rules related with security (refer to spec)
external_key json No Uses external content key to generate license. (refer to spec)

playback_policy

Name Value Required Description
limit boolean No whether playback period is limited (default: false)
true : limited playback period, false : unlimited
persistent boolean No whether the license is persistent. (default: false)
true : keep license, false : remove license after play(for streaming)
duration number Select duration of playback (unit: second). 'expire_date' is ignored if 'duration' is set.
'limit' should be true to apply this setting.
expire_date string Select date of license expiration, GMT Time 'yyyy-mm-ddThh:mm:ssZ' 'limit' should be true to apply this setting. This setting cannot be used with 'duration'.

security_policy (optional)

Name Value Required Description
hardware_drm boolean No Whether hardware DRM is required.(default: false) valid for CENC (Widevine Modular) contents only
output_protect json No settings for external display (refer to spec)
allow_mobile_abnormal_device boolean No whether rooted device is allowed (default: false)
playready_security_level number No Security level of PlayReady DRM, 150,2000 (default: 150)

security_policy.output_protect

Name Value Required Description
allow_external_display boolean No Whether external display is allowed. (default: false) valid for NCG DRM only
control_hdcp number No Setting for applying HDCP. (default: 0)
0 : No HDCP, 1 : HDCP 1.4, 2 : HDCP 2.2

external_key (optional)

Name Value Required Description
mpeg_cenc json No CENC external key setting for PlayReady/Widevine (refer to spec)
hls_aes json No HLS AES external key setting for FairPlay Streaming (refer to spec)
ncg json No NCG DRM external key setting (refer to spec)

external_key.mpeg_cenc

Name Value Required Description
key_id hex-string No Key ID for DASH CENC packaging(PlayReady/Widevine). 16byte hex string
key hex-string No Key for DASH CENC packaging. 16byte hex string
iv hex-string No IV for DASH CENC packaging. 16byte hex string

external_key.hls_aes

Name Value Required Description
key hex-string No Key for HLS Sample AES packaging(FairPlay Streaming). 16byte hex string
iv hex-string No IV for HLS Sample AES packaing. 16byte hex string

external_key.ncg

Name Value Required Description
cek hex-string No CEK for NCG packaing. 32byte hex string

Response Data Format

  • body : base64 Encoding ( JSON Data string )
HTTP Status Code Description Body
200 OK Success base64enc(JSON Data String)
400 Invalid parameter or parameter not exist
401 Failed to authenticate
404 Invalid URL
406 Cannot use token type integration for the site
5xx Server-side error .

JSON Data Format

{
    "drm_type": "<multi-drm type>", 
    "site_id": "<site id>",
    "cid": "<contents id>",
    "token": “<base64 encode(aes256 encrypt(token json string))>”
}
Name Value Required Description
drm_type string Yes Type of multi-DRM ("NCG", "Widevine", "PlayReady", "FairPlay")
site_id string Yes Service site ID issued by PallyCon cloud (4 byte)
cid string No Unique ID of the content
token string Yes base64 encoding(aes256 encrypt(token json string))

token json string

Name Value Required Description
token_serial string Yes token serial string

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 )

Example

Request Data

{
    "drm_type": "Widevine",  
    "cid": "content-id",
    "token_expiry_date": "2017-04-10T23:59:59Z",
    "playback_policy": {
        "limit": true,
        "persistent": true,
        "duration" : 3600
    },
    "security_policy": {
        "hardware_drm": false,
        "output_protect": {
            "allow_external_display" : true,
            "control_hdcp": 1
        },
        "allow_mobile_abnormal_device" : false,
        "playready_security_level" : 150
    },
    "external_key": {
        "mpeg_cenc": {
            "key_id" : "0011223344556677889900112233445566",
            "key" : "0011223344556677889900112233445566",
            "iv" : "0011223344556677889900112233445566"
        },
        "hls_aes" : {
            "key" : "0011223344556677889900112233445566",
            "iv" : "0011223344556677889900112233445566"
        },
        "ncg":{
            "cek":"hex-string"
        }
    }
}

results matching ""

    No results matching ""