DRM Blacklist Management Guide

DoveRunner 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 DoveRunner Console web UI.

sequenceDiagram
    participant A as OTT User
(Client Device)
    participant B as OTT Platform
    participant C as DoveRunner 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

Note

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 DoveRunner Console.

Managing User Blacklist

After logging in to DoveRunner 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.

Note

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

Note

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

DoveRunner 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 DoveRunner account ID",
    "account_seq": "Your DoveRunner 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 DoveRunner service
account_seq	Y	Your DoveRunner 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 DoveRunner 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 DoveRunner 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.