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

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.

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.

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.

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.

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.

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.

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.

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.

• URL: https://service.pallycon.com/api/v2/drm/blacklist/user/{siteId}
• Method: GET
• API Code : UA013001100

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.

• URL: https://service.pallycon.com/api/v2/drm/blacklist/user/{siteId}
• Method: POST
• API Code : UA013001200

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.

• URL: https://service.pallycon.com/api/v2/drm/blacklist/user/{siteId}
• Method: PUT
• API Code : UA013001200

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 to apply (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.

• URL: https://service.pallycon.com/api/v2/drm/blacklist/device/{siteId}
• Method: GET
• API Code : UA013002100

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.

• URL: https://service.pallycon.com/api/v2/drm/blacklist/device/{siteId}
• Method: POST
• API Code : UA013002200

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).

• URL: https://service.pallycon.com/api/v2/drm/blacklist/device/{siteId}
• Method: PUT
• API Code : UA013002200

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.