License Cipher SDK Guide

Overview

This guide explains DRM License Cipher SDK, which enhances the security of software-level Widevine L3 DRM.

Widevine L3 DRM, which provides software-level security, has the disadvantage of being vulnerable to hacking compared to Widevine L1, which supports hardware security based on the Trusted Execution Environment (TEE). When playing Widevine DRM content in Android applications, the License Cipher SDK can be applied to encrypt DRM license requests to prevent content key leakage by various hacking tools.

By applying the app security features of AppSealing Service along with License Cipher, you can effectively block hacking attempts on your Android app to enhance content security.

Prerequisites

To use the License Cipher SDK, you’ll need the following:

• Enterprise plan and AppSealing service subscription
  • To use License Cipher, you need to subscribe to PallyCon Enterprise plan. You also need to subscribe to AppSealing service to apply application security.
  • The same conditions apply if you integrate with a third-party player instead of PallyCon Widevine Android SDK.
• Request License Cipher SDK
  • The License Cipher SDK is delivered through our Helpdesk. To request this SDK, please create a ticket on the Helpdesk website.
• Using PallyCon Widevine Android SDK or a compatible third-party player
  • In addition to PallyCon Widevine Android SDK, the License Cipher SDK works with Google ExoPlayer or Bitmovin player.
  • If you need to integrate License Cipher SDK with other player solutions, please contact our Helpdesk.
• Download the key table file
  • You need to download the WhiteBox Crypto (WBC) key table used for encryption of license request data from PallyCon Console. (Multi DRM > DRM Setting > License Cipher)
  • The downloaded key table file should be included in the Android app where you want to apply License Cipher.

Applying License Cipher SDK

PallyCon License Cipher SDK works in the following ways, depending on the integration target. For more information on both integrations, please refer to the sample projects included with the SDK.

Integrating with PallyCon Widevine Android SDK

1. Copy the key table file downloaded from PallyCon Console to the assets folder of your Android application project.
2. Unzip the License Cipher SDK delivered through the Helpdesk.
3. Copy the PallyConLicenseCipher.aar file to the /module/libs/ folder of your project.
4. Add the following settings to build.gradle (app).

dependencies {
  ...
  // If the pallycon widevine sdk is included in the existing 'project/module/libs/', omit it.
  implementation 'com.pallycon:widevine:x.x.x' 

  implementation fileTree(dir: 'libs', include: ['*.aar'])
  ...
}

5. In the DRM configuration of the Widevine Android SDK, add the key table path as follows.

// Enter DRM-related information.
val config = PallyConDrmConfiguration(
 siteId = "site id",
 customData = "content auth data",
 httpHeaders = mutableMapOf(), // custom header
 drmLicenseUrl = "request license server url",
 licenseCipherPath = "key table file path in assets" // ex) plc-kt-test.bin
)

val data = ContentData(
 contentId = "content id",
 url = "content URL",
 localPath = "Download location where content will be stored",
 drmConfig = config,
 cookie = null
)

val wvSDK = PallyConWvSDK.createPallyConWvSDK(
 Context, // Context
 data
)

Integrating with 3rd party player solutions

1. Copy the key table file downloaded from PallyCon Console to the assets folder of your Android application project.
2. Unzip the License Cipher SDK delivered through the Helpdesk.
3. Copy the PallyConLicenseCipher.aar file to the /module/libs/ folder of your project.
4. Add the following settings to build.gradle (app).

dependencies {
  ...
  // If the pallycon widevine sdk is included in the existing 'project/module/libs/', omit it.
  implementation 'com.pallycon:widevine:x.x.x' 

  implementation fileTree(dir: 'libs', include: ['*.aar'])
  ...
}

5. Import License Cipher library.

import com.pallycon.licensecipher.LicenseCipher

6. When requesting a Widevine license, encrypt the request data using License Cipher.

// If you use ExoPlayer, you will need to inherit the 'MediaDrmCallback' and implement your own license request process. 
// licenseData is the widevine request license data and the data type is ByteArray.
val outputData = ByteArray(licenseData.size)
// create license cipher, path = The path to the Asset directory. ex) plc-kt-test.bin
// You can download the table file from the PallyCon console.
val licenseCipher = LicenseCipher.createLicenseCipher(context, tablePath)
// doCipher
if (licenseCipher.doCipher(licenseData, outputData)) {
  // requestData is the data to include in the body when communicating with the server API.
  requestData = outputData
}

Applying License Cipher option to license token

After you apply the License Cipher feature to a client app, enable the encryption flag on the license token used by that app, as shown in the example below.

"security_policy": [
  {
    ...
    "widevine": {
      ...
      "enable_license_cipher": true
    },
    ...
  }
]

Blocking unencrypted requests

After you apply the License Cipher feature to a client app, you need to block unencrypted requests so that only license requests from that app are allowed. Set up blocking in the following ways, depending on your case of adopting the feature.

Adopting License Cipher to a new service

If you’re applying License Cipher to a new service, you can block unencrypted license requests when the client app with License Cipher is registered on the store.

1. Log in to PallyCon Console.
2. Change the Allow or block unencrypted license requests option on Multi-DRM > DRM Setting > License Cipher section to Block.

After the above settings, Widevine license requests from Android apps will only be processed normally if they are encrypted via the License Cipher SDK, and unencrypted requests will be treated as hacking attempts and DRM license issuance will be denied.

Adopting License Cipher to an existing service

If you’re already serving DRM content, to minimize user disruption during the introduction of License Cipher solution, you should allow unencrypted requests from older versions of your app until most users update to the new version of your app.

1. Apply the License Cipher SDK to your client app
2. Set the enable_license_cipher flag in the token specification to true for the new version of the app (default: false)
3. Register the updated app on the store and notify users for the update.
4. Change the Allow or block unencrypted license requests option to Block in PallyCon Console when most users have completed the update.

Integrating with License Proxy Server

If you are integrating DRM licenses through a proxy server operated in your system, you need to set the enable_license_cipher item to true in the license token generated by the proxy, depending on the client environment. (Only for Android apps with License Cipher SDK applied)

The passing of request data and response data between the license server and the client, which is handled by the proxy server, is done in the same way as before, regardless of whether License Cipher is applied or not.