DoveRunner DRM Key Import API Guide

DoveRunner DRM Key Import API can be used to import existing content encryption key data to DoveRunner key database. To create a DRM license using DoveRunner License Server, you need to import DRM key data in advance or set the key of the content to the license token when requesting a license (external key integration).

There are two use cases of the API.

Migrating from other DRM service provider
- If you were using other DRM service and want to migrate to DoveRunner, you can import the key data for your existing DRM contents using this API.
- For large size key data importing, please ask for a separate bulk import process via Helpdesk.
Using two DRM service providers at the same time
- If you want to use DoveRunner and other DRM service at the same time for availability, you can use this API to import any new key used for content packaging with the other DRM vendor.

Prerequisites

To use the key import API, you need to have an account on DoveRunner and get your site key, access key, and KMS token via DoveRunner Console or Helpdesk. Then you may follow the API specification below.

API Request

Request URL and method

URL: https://drm-kms.doverunner.com/v2/importKey/{kmsToken}

For the {kmsToken} part, you need to replace it with your KMS token provided via Helpdesk or DoveRunner Console.

Method: POST (for insert) / PUT (for update)

Request body

When you call the API request URL, set the request body as the JSON data described below:

{
    "data": "<encrypted `content list JSON` data>",
    "timestamp": "<timestamp>",
    "hash": "<hash data>"
}

Name	Value Type	Descriptions
`data`	String	Base64 encoded string of AES encrypted `content list JSON`
`timestamp`	String	Time of the request data generation in `yyyy-mm-ddThh:mm:ssZ` format (GMT timezone)
`hash`	String	SHA256 hash value for combined string of `access key`, `data`, and `timestamp` values

Example of request body

{
  "data" : "gU/IyXPvB58D0LxvJblM980lUG7is1RtW4uDO1n+PBD5j942YEZTQEvtYWemITBuXwZsrh/y6XLdRnqt7zGKcSu6IgpEZiXkjfGN6QkejtGKw9tNfX34P9p2HOjioTyaGxKS9UyxgkxWdT5TUvTsBAZMyTXfKz7pyYtH8Db5WtSC6+Ve6i1U+uSVwJ383/ukZ1uIsfIxqW8Sd2hjBHcFlJwDgereHb0e79",
  "timestamp" : "2023-04-14T23:59:59Z",
  "hash" : "XokH+97vUFgrtNthJQnRn1xQ2LXrwTm+UYqhWZT06CE="
}

Please check the rest of this guide to learn how to create the values in the JSON specification.

Content list JSON

Create the content list JSON including the content ID and encryption key values.

{
    "content_list": [
        {
            "content_id": "<unique ID of the content>",
            "content_key_list": [
                {
                    "track_type": "<track type for the key value>",
                    "key_id": "<16 byte hex string of the key ID>",
                    "key": "<16 byte hex string of the content encryption key",
                    "iv": "<16 byte hex string of the IV>"
                }
            ]
        }
    ]
}

Name	Value Type	Descriptions
`content_list`	JSON array	List of contents for the key importing. Max number of contents in a request is 100.
`content_id`	String	Unique ID of the content (CID). Max 200 bytes alphanumeric and `-`(hyphen), `_`(underscore) characters
`content_key_list`	JSON array	List of encryption key data used for the content. There can be multiple key data for a content if the content is packaged with multiple encryption keys.
`track_type`	String	Defines the track to which the key data are applied. - Value: `ALL`, `VIDEO`, `AUDIO`, `SD`, `HD`, `UHD1`, `UHD2`
`key_id`	String	ID of the encryption key as 16 byte hex string
`key`	String	The encryption key as 16 byte hex string
`iv`	String	The IV as 16 byte hex string

Examples of content list JSON

Sending key data for two contents with single-key packaging

For single-key content encrypted with a single key, you can set the key data as follows, depending on whether the audio track is encrypted or not.

{
    "content_list": [
        {
            "content_id": "content-id-0001",
            "content_key_list": [
                {
                    "track_type": "ALL",    // Both video and audio are encrypted with a single key
                    "key_id": "43FB9B380AD674A3543125012C3ADC81",
                    "key": "01DF8CCCA8BC6CE330DDDC3A425AABA6",
                    "iv": "A43343F998724B1C335C44356D2E5A54"
                }
            ]
        },
        {
            "content_id": "content-id-0002",
            "content_key_list": [
                {
                    "track_type": "VIDEO",  // The video track(s) is encrypted with a single key (skipping audio encryption)
                    "key_id": "A08A04D48DD356B02C3E609876740475",
                    "key": "864355D6D5B4A1AD6106A93ED096C2CB",
                    "iv": "CCEB68525D22467EE488307B248D3A3C"
                }
            ]
        }
    ]
}

Sending key data for a content with multi-key packaging

For multi-key content where different encryption keys are used for different video/audio tracks within a single piece of content, you can set track-specific encryption keys as follows. If you use track types such as SD, HD, UHD1, etc. for video tracks, you can set different keys for each resolution track.

{
    "content_list": [
        {
            "content_id": "multi-key-content-0001",
            "content_key_list": [
                {
                    "track_type": "VIDEO",
                    "key_id": "43FB9B380AD674A3543125012C3ADC81",
                    "key": "01DF8CCCA8BC6CE330DDDC3A425AABA6",
                    "iv": "A43343F998724B1C335C44356D2E5A54"
                },
                {
                    "track_type": "AUDIO",
                    "key_id": "A08A04D48DD356B02C3E609876740475",
                    "key": "864355D6D5B4A1AD6106A93ED096C2CB",
                    "iv": "CCEB68525D22467EE488307B248D3A3C"
                }
            ]
        }
    ]
}

AES256 encryption and base64 encoding

After creating the content list json, you need to encrypt the JSON string using the information below:

AES256 Encryption

mode: CBC

key: 32 byte (site key generated for your DoveRunner account)

iv: 16 byte (0123456789abcdef)

padding: pkcs7

The encryption result needs to be encoded by base64 algorithm. Please refer to the following example code for the encryption and encoding implementation. The final result (base64 encoded string of AES encryption) should be set as data value in the request body JSON.

const crypto = require("crypto");

const cipher = crypto.createCipheriv("aes-256-cbc", siteKey, aesIv);
let encryptedJsonData = cipher.update(
  JSON.stringify(contentListJson),
  "utf-8",
  "base64"
);
encryptedJsonData += cipher.final("base64");

The above is not complete working code. You need to implement the encryption and encoding code using the development language you use.

Creating hash value

The last part of the request body JSON data is the hash value. The hash is used to verify the integrity of the entire request JSON value and should be generated as follows:

base64(sha256(<access key> + <data string> + <timestamp>))

access key: Access key value generated for your DoveRunner account
data string: The base64 string of AES encrypted content list JSON (the same value as set to data)
timestamp: Current time of the request data generation in yyyy-mm-ddThh:mm:ssZ format (the same value as set to timestamp)

Example of hash input string

You may refer to the example code below for the timestamp and hash creation.

const timestamp = new Date().toISOString().replace(/\.\d{3}/gi, '');

let accessKey = "LT2FVJDp2Xr018zf4Di6lzvNOv3DKP20";
let data = "gU/IyXPvB58D0LxvJblM980lUG7is1RtW4uDO1n+PBD5j942YEZTQEvtYWemITBuXwZsrh/y6XLdRnqt7zGKcSu6IgpEZiXkjfGN6QkejtGKw9tNfX34P9p2HOjioTyaGxKS9UyxgkxWdT5TUvTsBAZMyTXfKz7pyYtH8Db5WtSC6+Ve6i1U+uSVwJ383/ukZ1uIsfIxqW8Sd2hjBHcFlJwDgereHb0e79";

const hashInput = accessKey + data + timestamp;

let hashString = crypto
  .createHash("sha256")
  .update(hashInput)
  .digest("base64");

The above is not complete working code. You need to implement the hash creation code using the development language you use.

API Response

Response format

When calling the API URL with the request body JSON data, you will receive the response data as below:

{
  "error_code": "<error code>",
  "message": "<error message>"
}

Error codes

Code	Message	Description
0000	Success	The key data is imported to DoveRunner KMS successfully.
2509	Failed to insert the key list	Something went wrong in DoveRunner API server. Please report it to our Helpdesk.
2510	Failed to decrypt the required value	The decryption of `data` value failed. Please check your API request implementation regarding the value.
2511	Content ID already exists	Cannot insert the key data for the same content ID which is already registered in our system. Try `PUT` method instead of `POST` if you want to update the data.
2512	The number of contents exceed 100	You cannot input more than 100 content IDs in a single API request.
2513	Hash verification failed	Something’s wrong in your hash string generation. Please check your implementation again.
2514	Failed to update the key list	Something went wrong in DoveRunner API server. Please report it to our Helpdesk.