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 DRM Introduction 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.

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:

Management APILicense Acquisition APILicense ServiceSeparate endpoint for each DRM technology
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. It is DRM technology specific and which technology gets used depends on the end user device, i. e. a request originating from a Chrome browser will have to use the Widevine DRM compatible endpoint, a request originating from a Safari browser will have to use the FairPlay compatible endpoint.

The HTTP POST request’s body shall contain a license request generated by a CDM (Content Decryption Module) which is used by a DRM-capable player. The license request data structure is encrypted and can only be understood by the License Service. The player application merely plays the role of a messenger between the CDM and the License Service. The player cannot read or tamper with the contents of license requests or responses. The DRM License returned by the License Service can only be used on the same device from which the License Request was initiated. Even if the details about the license request data structure are not published by the vendors of the DRM technologies, it is known that the license request contains:

  • Key ID - the ID of the Content Key needed to decrypt the video (the player knows the Key ID from the video meta-data)

  • Device Identification - Device ID and other information (DRM technology-specific)

  • IP Address - the IP Address of the client device

However, for the License Service to grant the license, the license request shall carry an Axinom DRM License Service Message with a valid Entitlement Message inside. It can be added to the license request either as a custom HTTP header X-AxDRM-Message or as a query string parameter AxDrmMessage.

Management API

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

  • Communication Key

  • Key Seed

  • FairPlay Data Set

Entitlement Service

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

PlayerEntitlement_ServiceLicense_Service(1) Entitlement Request(2) Entitlement Message[JWT](3) License Request[Key ID,Entitlement Message](4) DRM License[Content Key,Usage rules]
Figure 2. Standard Mode
PlayerEntitlement_ServiceLicense_ServiceEntitlement Request [Key ID]Verify eligibilityPrepare Entitlement Message as JWTSign JWT using Communication KeyJWTLicense Request [Key ID, JWT]Validate JWTProcess License requestDRM License [Content Key, Usage rules]
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).

PlayerEntitlement_ServiceLicense_Service(1) License Request[Key ID](4) DRM License[Content Key,Usage rules](2) License Request[Key ID,Entitlement Message](3) DRM License[Content Key,Usage rules]
Figure 4. Proxy Mode
PlayerEntitlement_ServiceLicense_ServiceLicense Request [Key ID]Verify eligibilityPrepare Entitlement Message as JWTSign JWT using Communication KeyLicense Request [Key ID, JWT]Validate JWTProcess License requestDRM License [Content Key, Usage rules,optional added information]opt[Additional checks]Validate based on additional informationDRM License [Content Key,Usage rules]
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.

Note
The current version of the Entitlement Message schema is "2". The legacy schema version "1" is still supported, but it is highly recommended to use the current version "2". For more information about version "1" please read link:/mosaic/documentation/drm/Entitlement-Message/v1.0.

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.

PlayerPlayerEntitlement_ServiceEntitlement_ServiceLicense_ServiceLicense_ServiceLicense Request [Key ID]Set return_license_request_info = trueLicense Request [Key ID, Entitlement Message]Extract DeviceIDfrom License RequestDRM License,License Request Info Message [Device ID]alt[DeviceID is eligible]DRM License[DeviceID is not eligible]Error
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 a case, 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 instructs the License Service about all the details of issuing a DRM License to the Client. At the same time, the Entitlement Service provides this message directly to the Client (unless in Proxy Mode). It means, the Entitlement Message shall be protected against any manipulation. For this purpose Axinom uses digitally signed JSON Web Tokens (JWT) to encapsulate the Entitlement Message.

The JWT structure encapsulating an Entitlement Message looks like this:

{
    "version" : 1,
    "begin_date": "2015-08-18T15:22:40+03:00",
    "expiration_date": "2015-08-18T15:22:40+03:00",
    "com_key_id" : "cc36e85d-2fdf-462c-b395-030907447afc",
    "message" : {ENTITLEMENT MESSAGE}
}

This structure is signed by the Entitlement Service using the Communication Key, which is a shared secret between the Entitlement Service and the License Service. The signing algorithm is HMAC-SHA256. The ID of the Communication Key used for signing shall be included in the token itself (com_key_id).

Finally, the token is encoded with base64.

The so created JWT token shall be submitted to the License Service though one of these ways:

  • HTTP Header X-AxDRM-Message

  • Query string parameter AxDrmMessage

  • [PlayReady only] Custom Data part of the PlayReady License Request.

All popular video players in use today allow to use one of the three options above. If your project-specific situation does not allow any of the above options, consider using the Proxy Mode.

The fields begin/expiration_date define the validity timeframe of the JWT token.

Note
Don’t confuse the validity timeframe of the JWT token (= of the Entitlement Message) and the validity timeframd of the generated DRM License. The former means: the License Service will only issue a DRM License when JWT token is valid according to its begin/expiration_date. The latter means: the player can only use the DRM License for content decryption during DRM License’s validity (start/expiration_datetime).
Tip
Axinom recommends using short-lived JWT tokens (minutes) unless the system architecture requires longer-lived tokens (e.g. due to disconnected scenario, very high load or alike).