License Service is the part of Axinom DRM which provides the content key for decryption together with the content rules to authorized users as well.

License Service

The article What is DRM? defines the purpose of a License Service as follows:

A License Service is the part of DRM which provides the content key for decryption to authorized users.

But if we analyze it further, we discover two distinct responsibilities:

  • Authorize the requests based on the user data and decide what the user should be able to do with the content

  • Create a DRM License document (with an embedded Content Key) in accordance with the used DRM technology.

The former is a very project-specific task depending on the project’s business logic and rules. However, the latter allows a generalized and reusable implementation. Hence, Axinom DRM allocates these responsibilities to two different components, respectively Entitlement Service and License Service.

  • License Service is a ready-to-use part of Axinom DRM.

  • Entitlement Service shall be developed specifically for each project by the respective project developer. Axinom provides samples and tools to simplify the task of developing an Entitlement Service.

Axinom Mosaic comes with a customizable open-source Entitlement Service that fulfills the responsibilities of an entitlement service described here and integrates with the other services, such as the Billing Service and Monetization Service, to implement a Content Monetization Solution.

License Service

License Service is a multi-tenant managed service, operated by Axinom. It issues DRM Licenses in response to valid License Requests. License Service provides two APIs:

Graph generation/download error : please click the link to see the error details

Figure 1. License Service exposing two APIs: License Acquisition API and Management API

License Acquisition API

License Acquisition API is the frontend-facing API for the License Requests. Typically, the requests are made by a video player. The license request is generated by a CDM (Content Decryption Module) which is used by a DRM-capable player. The request shall carry a Axinom DRM License Service Message with a valid Entitlement Message inside.

Management API

The Management API allows to control several aspects of the tenant, such as:

  • Communication Key

  • Key Seed

  • FairPlay Data Set

Entitlement Service Communication

Obviously, Entitlement Service and License Service need to communicate. License Service should only grant a DRM License if the Entitlement Service previously authorized the user request. Axinom DRM implements this communication using a concept of an Entitlement Message. Entitlement Message is a tamper-proof data structure which instructs the License Service how to configure a DRM License.

There are two modes (collaboration workflows) between the Player, License Service, and Entitlement Service:

  • Standard Mode

  • Proxy Mode

Standard Mode

In the standard mode, it is the Player (or the user-facing application) which first requests an entitlement from the Entitlement Service. Then it creates a License Request and sends it to the License Service. The Entitlement Message is piggybacked on this request (as a custom http header or URL parameter).

Graph generation/download error : please click the link to see the error details

Figure 2. Standard Mode

Graph generation/download error : please click the link to see the error details

Figure 3. Interactions in the Standard Mode

Proxy Mode

In the proxy mode, the Entitlement Service acts as a License Service Proxy to the Player (hence the name). The player sends a License Request to the Entitlement Service. Having received the request, Entitlement Service first authorizes it. If access can be granted, it generates an Entitlement Message. Then it forwards the License Request, which it received from the client device, together with the Entitlement Message to the License Service. In response it receives the DRM License and forwards it to the requesting Player. In between, Entitlement Service has another chance to deny the request (more on this below).

Graph generation/download error : please click the link to see the error details

Figure 4. Proxy Mode

Graph generation/download error : please click the link to see the error details

Figure 5. Interactions in Proxy Mode

Entitlement Message

Entitlement Message is a JSON data structure designed to instruct the License Service how to configure a DRM License. Entitlement Message is produced by an Entitlement Service and consumed by the License Service.

Entitlement Message Structure

The Entitlement Message has the following structure:

Entitlement Message Data Structure Overview
{
    "type": "entitlement_message",
    "version": 2,
    "license": { // (1)
        "start_datetime": "2020-01-01T00:00:00+03:00",
        "expiration_datetime": "2020-01-03T00:00:00+03:00",
        "duration": 3600,
        "allow_persistence": true,
        ...
    },
    "content_keys_source": { // (2)
        "inline": [
            {
            "id": "11111111-0000-0000-0000-000000000000",
            "usage_policy": "Policy A"
            }
        ]
    },
    "content_key_usage_policies": [   // (3)
        {
            "name": "Policy A",
            ...
        }
    ],
    "license_server": {// (4)
        "return_license_request_info": true,
        "access_control": {
            "allowed_ip_addresses": [
                "10.11.12.13",
                "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
            ],
            "widevine": {
                "allowed_device_ids": [
                    "fbdcdcaf-af84-4bf3-8dbf-3e7c47922c65",
                    "5a0f8872-4c83-4362-a6b5-03228a4547ce"
                ]
            }
            ...
        }
    },
    "session": {
        "user_id": "fbdcdcaf-af84-4bf3-8dbf-3e7c47922c65"   // (5)
    }
}
  1. - General license restrictions, such as start / expiration time, duration, persistence

  2. - Content Keys related information: which Key IDs are approved, how to generate the keys, which usage policies to use for which key

  3. - Usage policies specific to DRM technologies, such as device security level, output protection, etc.

  4. - Client-related restrictions: which IP addresses and Device IDs are allowed to receive a DRM license

  5. - Unique string for each user, in case the billing model "Active Users" is used (see Billing Models)

For the full reference of the Entitlement Message see Entitlement Message.

Content Keys with the Key Seed Model

The main playback scenario using DRM is:

  • Player wants to play a video, but the video is DRM-protected

  • Player requests an Entitlement Message from the Entitlement Service, passing information like Video ID and User ID

  • Entitlement Service verifies the user and their eligibility for the given video. If successful, it finds the ID of the Content Key which was used to encrypt the video (Key ID) and returns an Entitlement Message authorizing this Key ID

  • Player sends a License Request to the License Service passing the Key ID and the Entitlement Message

  • License Service compares the Key ID in the License Request and in the Entitlement Message and creates the DRM License, which contains the Content Key for the specified Key ID.

The Entitlement Service shall add the authorized Key ID to the Entitlement Message. In its simplest form it looks like below:

Minimalistic version of the content_keys_source section
{
    "content_keys_source": {
        "inline": [
            {
            "id": "11111111-0000-0000-0000-000000000000" // (1)
            }
        ]
    }
}
  1. - the authorized Key ID

The section name "inline" means, the Key IDs are directly included in the Entitlement Message (see Allow-All Entitlement Message for an alternative). The element inline is an array, because more than one Key ID can be included in the same Entitlement Message. Such a message approves a License Request for any of the included Key IDs.

The License Service supports the Key Seed Model (see Key Seed Model). In this model the value of the key (Content Key) is derived from a secret Key Seed (known to the License Service) and a public Key ID using a known algorithm. It means, it is enough to include the Key ID in an Entitlement Message to enable the License Service to generate the respective Content Key.

The License Service supports multiple Key Seeds at the same time. To indicate which of them should be used for a specific Key ID, the property seed_id shall be used:

Explicitly specified Key Seed ID
{
    "content_keys_source": {
        "inline": [
            {
            "id": "11111111-0000-0000-0000-000000000000",
            "seed_id": "88888888-0000-0000-0000-000000000000" // (1)
            }
        ]
    }
}
  1. - the ID of the Key Seed to be used

This is optional, however. If the Key Seed ID is not specified, the default Key Seed is used by the License Service.

For FairPlay, it is required to provide the Player the initialization vector (IV) value in addition to the Content Key itself. The IV is a 16-bytes value, encoded as base64. The IV can be specified as a part of an Entitlement Message:

Note
For FairPlay, it is also possible to specify the IV as a part of an asset ID in the FairPlay license request. If the IV is specified both in the asset ID and in the Entitlement Message, the value from the Entitlement Message takes precedence.
Initialization vector specified for FairPlay
{
    "content_keys_source": {
        "inline": [
            {
            "id": "11111111-0000-0000-0000-000000000000",
            "iv": "HYDILKxZnPF0KizuWT0hww==" // (1)
            }
        ]
    }
}
  1. - the Initialization Vector to be used

Content Keys with the Direct Key Model

Instead of the Key Seed Model, you can use the Direct Key Model. In this model the Entitlement Service itself handles the keys database and finds the correct Content Key for a given Key ID. The Content Key is included in the Entitlement Message. To protect against tampering, the Content Key is encrypted. The License Service takes the value for the Content Key directly from the Entitlement Message and includes it to the DRM License.

Usage of the Direct Key Model (element "encrypted_key")
{
    "content_keys_source": {
        "inline": [
            {
            "id": "11111111-0000-0000-0000-000000000000",
            "encrypted_key": "EREREREREREREREREREREQ=="
            }
        ]
    }
}

The Entitlement Service and the License Service possess a shared secret: the Communication Key, which is part of the tenant settings. The Communication Key can be used by the Entitlement Service to encrypt the Content Key with a symmetric algorithm so that the License Service can decrypt it. Use the following settings for encryption:

  • Content Key (the source) shall be exactly 16 bytes

  • Algorithm: AES-CBC

  • Encryption Key: Communication Key

  • Padding: none

  • Initialization vector (IV): Key ID in big-endian byte order (for the Key ID "1E0DE660-B47E-4C79-B5CE-EDBD72BB17B3" use the following IV: "0x1E0DE660B47E4C79B5CEEDBD72BB17B3")

The resulting encrypted value shall be added to the encrypted_key field in base64 encoding.

Allow-All Entitlement Message

It is possible to create an Entitlement Message which grants a DRM License for a License Request for any Key ID. Other type of restrictions still can be used, e.g. based on the Client Device or time. Also the usage policies can be specified.

Creating an Allow-All Entitlement Message
{
    "content_keys_source": {
        "license_request":
            {
                "seed_id": "88888888-0000-0000-0000-000000000000", // (1)
                "usage_policy": "Policy A" // (2)
            }
        }
}
  1. - the ID of the Key Seed to be used

  2. - the Usage Policy to be used (see Usage Rules)

Note
In the case of FairPlay, this feature is allowed only when the key IV is provided in the asset ID of the License Request.
Warning
Usage of this feature presents a security risk as content keys are generated for any media, without any key ID based restrictions. It’s highly recommended to avoid using this feature, unless the risks involved are well understood. Axinom recommends to use this feature only for development and test purpose.

General License Restrictions

Two common restrictions which can be imposed by a DRM License:

  • Defining the timeframe during which playback is possible

  • Defining if a DRM License may be persisted on the client device

These restrictions are specified within the section entitlement_message.license.

  • start_datetime/expiration_datetime - a time interval (absolute) during which the playback is allowed

  • duration - a time interval, in seconds, starting from the moment of generation of the License Request during which the playback is allowed. This parameter is mutually exclusive with start/expiration_datetime.

  • allow_persistence (boolean) - if the client is allowed to store the license persistently and re-use it for further playbacks during the allowed license duration. If the value is false, the client shall request a new DRM License for every playback. If the value is true, the client is allowed to store the license. If the license will actually be stored depends on the DRM technology, client’s capabilities and the specific implementation.

When these parameters are ommitted, the default is: the license is immediately valid, there is no time limitation, but storing the license locally is not allowed.

Usage Rules

Usage Rules (aka Usage Policies) are defined within the section entitlement_message.content_key_usage_policies. It’s an array, i.e. multiple policies can be defined. This is for the case when multiple Content Keys are specified. Each content key can refer to a specific usage rule (content_key_source.inline[i].usage_policy).

Each policy contains DRM technology-specific settings, which are enforced by the local CDM. Examples of such settings (for PlayReady):

  • min_device_security_level

  • analog_video_opl

  • source_id

  • play_enablers

  • analog_video_output_protections

  • digital_audio_output_protections.

For the full list of available settings and their impact see DRM technology specific documentation (e. g. for PlayReady refer to the PlayReady Compliance and Robustness Rules).

Device-Specific Restrictions

It is possible to configure an Entitlement Message to allow the License Requests only from specific IP addresses or specific Device IDs.

To whitelist an IP address (or multiple), provide them in an array entitlement_message.license_server.access_control.allowed_ip_addresses. Both IPv4 and IPv6 are supported.

To whitelist a Device ID (or multiple), provide them in an array entitlement_message.license_server.access_control.<DRM Technology>.allowed_device_ids. As you see, the Device IDs have to be nested under the respective DRM Technology element. This is because the same device will have different Device IDs for each of the DRM Technologies. Taking this into account it is possible to define Device ID-specific rules.

However, there is another catch. It is not easy to discover the Device ID of a specific device. The Device ID is sent within a License Request. But the License Request is encrypted, and there is no easy way to read it. The one who can read the License Request is the License Service. But the code making a decision based on the Device ID has to be in the Entitlement Service.

With the Proxy Mode it is possible to work around this limitation as follows:

  • Generate an Entitlement Message without DeviceID-restrictions

  • Set entitlement_message.license_server.return_license_request.info=true

  • Send the Entitlement Message to the License Service

  • License Service, seeing return_license_request.info=true, will extract certain client device related information and return it to the Entitlements Service as a so-called License Request info Message (in the HTTP Response Header X-AxDRM-Message). This message will contain the Device ID related to the specific DRM technology and some other information (e.g. for Widevine - device_certificate_serial_number and client-token).

  • Now, decide based on the Device ID, if the client should get the DRM License or not.

Graph generation/download error : please click the link to see the error details

Figure 6. Using Proxy Model to apply device-specific restrictions
Note
On some devices and platforms, for example, Google Chrome on desktop devices, Widevine is not able to uniquely identify the device. In such cases, the device_id field is missing in the License Request Info Message, and hence the Entitlement Service cannot make a decision based on the device id.

Entitlement Message Protection and Delivery

An Entitlement Message is delivered to the License Service as a payload of a License Service Message.