DRM Blacklist Management Guide

Overview

PallyCon Multi-DRM service provides DRM Blacklist Management feature that allows OTT platforms to block issuance of DRM licenses to users or client devices suspected of piracy or unauthorized content use. Customers can register, view, and update the IDs of users or devices to be blocked via HTTP API or the Blacklist Management section of the PallyCon Console web UI.

sequenceDiagram
    participant A as OTT User<br>(Client Device)
    participant B as OTT Platform
    participant C as PallyCon Server
    A ->> C: Request DRM License (Non-blacklisted)
    C ->> C: Verify License Token
    C ->> A: Issue DRM License
    A ->> A: Play Content
    opt Blocking via Blacklist
    B ->> C: Register illegal user or device ID
    C ->> C: Store the ID in Blacklist DB
    A ->> C: Request DRM License (Blacklisted)
    C ->> C: Verify Token and Check Blacklist
    C -->> A: Deny License Issuance
    A -->> A: Cannot Play Content
    end

The definitions of user ID and device ID used in the DRM blacklist feature are as follows

  • User ID: The value of user_id in the token data used for DRM license acquisition. If you do not enter this value when creating a token, or enter a random value that is not related to the end user, you cannot apply the blacklist for the user ID.
  • Device ID: The Device ID value included in the DRM license response data. It can be found on the Multi-DRM > Licenses > Active Licenses screen. The ID may not be unique depending on the client environment, such as browsers.

The device ID is related to the type of DRM supported by the device. If a device supports multiple DRMs, each type of DRM will have a different device ID.

Blacklist Management via Console

You can register, view, and change the status of a blocked user ID or device ID on the Blacklist Management screen of PallyCon Console.

Managing User Blacklist

After logging in to PallyCon Console, go to Multi DRM > Blacklist Management > User Blacklist menu, and you can manage the blacklist for user ID on the following screen.

User Blacklist Management
User Blacklist Management

Looking up blocked users

On the User Blacklist screen, you can apply various search criteria to view the user IDs and current status of blacklisted users.

Registering user IDs to be blocked

Click the Register button on the User Blacklist screen to go to the Register User ID screen as shown below.

Register User ID
Register User ID

If you are entering multiple IDs, you can add entries with the + button above the Register button, and reduce entries by clicking the trash can button to the right of each entry.

Changing block status

You can change the status (blocked or unblocked) for each blacklisted user ID. By checking the checkbox to the left of the corresponding entry in the list, the Change Status button will switch to Block or Unblock depending on the current status, and clicking it will change the block status of the selected target.

For user IDs that are switched to Unblocked, DRM license issuance will continue as normal as before they were blacklisted.

Managing Device Blacklist

After logging in to PallyCon Console, go to Multi DRM > Blacklist Management > Device Blacklist menu and you can manage the blacklist for device ID on the following screen.

Device Blacklist Management
Device Blacklist Management

Looking up blocked devices

On the Device Blacklist screen, you can apply various search criteria to view the device ID, DRM type, and current status of blacklisted devices.

Registering device IDs to be blocked

Click the Register button on the Device Blacklist screen to go to the Device ID Registration screen as shown below.

Register Device ID
Register Device ID

For each item you want to register, select the DRM type that corresponds to the device ID and enter the value of the device ID you want to block. If you enter multiple IDs, you can add entries with the + button above the Register button, and reduce entries by clicking the trash can button to the right of each entry.

Changing block status

You can change the status (blocked or unblocked) for each blacklisted device ID. By checking the checkbox to the left of the corresponding entry in the list, the Change Status button will switch to Block or Unblock depending on the current status, and clicking it will change the block status of the selected target.

For device IDs that are switched to Unblocked, DRM license issuance will continue as normal as before they were blacklisted.

Blacklist Management via API

In addition to the Console UI, the DRM Blacklist feature can also be managed via HTTP API. If you need an automated integration with your system, please refer to the guide below to implement an API-based integration.

API Basics

PallyCon Service API uses JSON Web Token(JWT) for secure transmission of information.

You can create and test the token using an online JWT tool or a server-side programming language.

Service API JWT Specification
Service API JWT Specification

The token should be signed using an account-specific secret key with HMAC SHA256(HS256) algorithm. Please create a ticket on Helpdesk to get your Service API Key and the account seq value used in the token payload.

JWT Structure

As shown on the above image, an encoded JWT token has the following format:

base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + HS256 signature value

Payload Specification

The token uses json payload data as below example:

{
    "sub" : "PallyConAPI",
    "aud" : "INKA",
    "iss" : "PallyCon",
    "account_id" : "Your PallyCon account ID",
    "account_seq": "Your PallyCon account SEQ",
    "exp": 1583191411
}
Key Required Value
sub Y Fixed value as PallyConAPI
aud Y Fixed value as INKA
iss Y Fixed value as PallyCon
account_id Y Your account ID of PallyCon service
account_seq Y Your PallyCon account’s SEQ (can be requested via Helpdesk ticket)
exp N Expiration date of the token (type: date number)

SEQ is a key value used to index key data in PallyCon service API.

Common Request Specification

Blacklist APIs commonly require the following request data.

Name Type Description
Authorization Header / String JWT token for API authentication. Added to HTTP headers.
api_code URL Param / String Code to separate APIs by functionality. Added as a URL parameter.

Common Response Specification

When calling the PallyCon Service API, you’ll get one of the HTTP status codes listed below.

HTTP Status Code Description
401 JWT Token specification is incorrect or the user information cannot be found
403 Do not have permission for the called API
200 HTTP communication success

When the HTTP status code is 200 (HTTP communication success), you’ll get the below response data in JSON format.

Key Type Value
error_code String 0000: Success / other numbers: failure
error_message String Shows the error message on failed request
data JSON Result of the successful API request

Get User ID List

This API retrieves a list of blacklisted user IDs.

Request Data Spec

Parameter Format Required Description
user_id String N Specific user ID to retrieve the data
status_code String N Status code (BL000: Blocked, BL001: Unblocked) Default: all
from String N Start date of lookup period (format: YYYY-MM-DD) By date of registration (GMT)
to String N End date of lookup period (format: YYYY-MM-DD) By date of registration (GMT)
time_zone String N Set the time zone used for search (format: +/-hh:mm) default: +00:00
page_unit Int N Number of search result (default:25, max: 1000)
page_index Int N Index of result page when the results are more than page_unit
  • Example Request
GET /api/v2/drm/blacklist/user/{siteId}?api_code=UA013001100&user_id=testUser&from=2024-04-15&to=2024-04-17&page_index=1&page_unit=10&site_id=DEMO&status_code=BL000&time_zone=%2B09%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: service.pallycon.com

Response Data Spec

Name Type Description
black_list Json Array List of user IDs
user_id String User ID registered in the blacklist
status_code String Status code (BL000: Blocked, BL001: Unblocked)
reg_date String Registration date (GMT)
update_date String Updated date (GMT)
  • Example Response
{
  "black_list" : [
	{
		"user_id" : "test",
		"status_code" : "BL000",
		"reg_date" : "20240214000000",
		"update_date" : "20240214000000"
	},
	{
		"user_id" : "test",
		"status_code" : "BL000",
		"reg_date" : "20240214000000",
		"update_date" : "20240214000000"
	},
  ],
  total_count : 2,
  error_code: "0000",
  error_message: "Success."
}

Register User ID in Blacklist

This API registers a user ID in the Blacklist.

Request Data Body

{
	"user_id_list" : [
		"test", "test2"
	]
}
Parameter Format Required Description
user_id_list String Array Y List of user ID to register in Blacklist

Response Data Format

{
	"error_code" : "0000",
	"error_message" : "Success"
}

Change Status of User ID

This API changes the block/unblock status of a blacklisted user ID.

Request Data Body

{
	"user_id_list" : [
		"test", "test2"
	],
	"status_code" : "BL000"
}
Parameter Format Required Description
user_id_list String Array Y List of user ID to update status
status_code String Y Status code (BL000: Blocked, BL001: Unblocked)

Response Data Format

{
	"error_code" : "0000",
	"error_message" : "Success"
}

Get Device ID List

This API retrieves a list of blacklisted device IDs.

Request Data Spec

Parameter Format Required Description
device_id String N Device ID to retrieve
status_code String N Status code (BL000: Blocked, BL001: Unblocked) Default: all
from String N Start date of lookup period (format: YYYY-MM-DD) By date of registration (GMT)
to String N End date of lookup period (format: YYYY-MM-DD) By date of registration (GMT)
time_zone String N Set the time zone used for search (format: +/-hh:mm) default: +00:00
page_unit Int N Number of search result (default:25, max: 1000)
page_index Int N Index of result page when the results are more than page_unit
  • Example Request
GET /api/v2/drm/blacklist/device/{siteId}?api_code=UA013002100&device_id=device1&from=2024-04-15&to=2024-04-17&page_index=1&page_unit=10&site_id=DEMO&status_code=BL000&time_zone=%2B09%3A00&dr HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: service.pallycon.com

Response Data Spec

Name Format Description
black_list Json Array List of retrieved devices
device_id String Device ID registered in blacklist
drm_type String DRM type of the device (widevine / playready / fairplay / ncg)
status_code String Status code (BL000: Blocked, BL001: Unblocked)
reg_date String Registration date (GMT)
update_date String Updated date (GMT)
  • Example Response
{
  "black_list" : [
	{
		"device_id" : "59fe7cf3e07c42e8a5de64fefb1356bd",
		"drm_type" : "widevine",
		"status_code" : "BL000",
		"reg_date" : "20240214000000",
		"update_date" : "20240214000000"
	},
	{
		"device_id" : "59fe7cf3e07c42e8a5de64fefb1356bd",
		"drm_type" : "widevine"
		"status_code" : "BL000",
		"reg_date" : "20240214000000",
		"update_date" : "20240214000000"
	},
  ],
  total_count : 2,
  error_code: "0000",
  error_message: "Success."
}

Register Device ID in Blacklist

This API registers device ID(s) in the blacklist.

Request Data Body

{
  "device_id_list": [
    {
      "device_id": "59fe7cf3e07c42e8a5de64fefb1356bd",
      "drm_type": "widevine"
    },
    {
      "device_id": "59fe7cf3e07c42e8a5de6",
      "drm_type": "playready"
    }
  ]
}
Parameter Format Required Description
device_id String Y Device ID to register in Blacklist
drm_type String Y DRM type of the device (playready / widevine / fairplay / ncg)

Response Data Format

{
	"error_code" : "0000",
	"error_message" : "Success"
}

Update Status of Device ID

This API changes the block/unblock status of blacklisted device ID(s).

Request Data Body

{
  "device_id_list": [
    {
      "device_id": "59fe7cf3e07c42e8a5de64fefb1356bd",
      "drm_type": "widevine"
    },
    {
      "device_id": "59fe7cf3e07c42e8a5de6",
      "drm_type": "playready"
    }
  ],
  "status_code": "BL000"
}
Parameter Format Required Description
device_id_list Json Array Y List of device ID to update status
device_id String Y Device ID to change status
drm_type String Y DRM type of the device (playready / widevine / fairplay / ncg)
status_code String Y Status to apply (BL000: Blocked, BL001: Unblocked)

Response Data Format

{
	"error_code" : "0000",
	"error_message" : "Success"
}

Error Codes

Error Code Message
A9048 Fail to Insert User IDs In Black List.
A9049 Request Spec About Black List API Is Invalid.
A9050 User ID Already Exists In Black List.
A9051 Fail to Get User IDs From Black List.
A9052 Fail to Delete User IDs In Black List.
A9053 Fail to Insert Device IDs In Black List.
A9054 Device ID Already Exists In Black List.
A9055 Fail to Get Device IDs From Black List.
A9056 Fail to Delete Device IDs In Black List.
Previous
Next