Skip to main content

Entitlement Message

Entitlement Message is a JSON data structure designed to instruct the Axinom DRM License Service how to configure a License. Entitlement Message is designed to be as DRM-agnostic as possible. In addition, DRM-specific license configuration is possible. An Entitlement Message shall be encapsulated in an Axinom DRM License Service message and delivered to the Axinom DRM License Service along with a License Request. See Axinom DRM License Service Message for additional details.

tip

You can experiment with various configurations of the Entitlement Message using the Entitlement Message Generator tool.

Root Structure​

The root structure of Entitlement Message is defined below. Refer to the sections License Configuration, Content Keys Source, and Content Key Usage Policies for definitions of these sections.

entitlement_message
{
  "type": "entitlement_message",

  "version": 2,

  "license": {},

  "content_keys_source": {},

  "content_key_usage_policies": [],

  "license_server": {},

  "session": {}
}

Sample Entitlement Message​

The following full Entitlement Message example combines above illustrated best practices:

{
  "version": 1,
  "id": "a7659f89-d153-4620-1aa0-1dc8a93f202e",
  "expiration_date": "2025-04-28T12:23:40+01:00",
  "com_key_id": "12196546-a312-4a4e-ab65-c19bccce1adf",
  "message": {
    "version": 2,
    "type": "entitlement_message",
    "license_server": {
      "access_control": {
        "prevent_drm_message_reuse": "true",
        "allowed_ip_addresses": [
          "80.237.132.164",
          "2a01:488:42:1000:50ed:84a4:43:1f85"
        ],
        "widevine": {
          "min_vmp_level": "PLATFORM_SOFTWARE_VERIFIED",
          "allow_tampered_platforms": false
        },
        "playready": {
          "allowed_device_ids":
          [
            "ed85e2bc-63d8-4a26-8ad0-18c382c12dd9",
            "0d268a04-ca6e-4e9e-8412-e05344817cf5"
          ]
        }
      }
    },
    "content_keys_source": {
      "inline": [
        {
          "id": "c9a0d00c-cd2b-4509-aaa8-95b5d68a7382",
          "usage_policy": "SD"
        },
        {
          "id": "bda0d55c-ad24-2211-faa2-25a5d6d8144a",
          "usage_policy": "HD"
        }
      ]
    },
    "content_key_usage_policies": [
      {
        "name": "SD",
        "fairplay": {
          "hdcp": "TYPE1",
          "allow_airplay": true,
          "allow_av_adapter": true
        },
        "widevine": {
          "cgms-a": "never"
        },
        "playready": {
          "analog_video_opl": 200,
          "compressed_digital_audio_opl": 300,
          "uncompressed_digital_audio_opl": 300,
          "compressed_digital_video_opl": 400,
          "uncompressed_digital_video_opl": 270
       }
      },
      {
        "name": "HD",
        "fairplay": {
          "hdcp": "TYPE1_STRICT",
          "allow_airplay": false,
          "allow_av_adapter": false
        },
        "widevine": {
          "device_security_level": "HW_SECURE_ALL",
          "cgms-a": "never",
          "hdcp": "NO_DIGITAL_OUTPUT"
        },
        "playready": {
          "min_device_security_level": "3000",
          "analog_video_opl": 200,
          "compressed_digital_audio_opl": 300,
          "uncompressed_digital_audio_opl": 300,
          "compressed_digital_video_opl": 500,
          "uncompressed_digital_video_opl": 300
       }
      }
    ],
    "license_server": {
      "return_license_request_info": true
    },
    "session": {
      "user_id": "dd265c4d02fc91edbc6aa61baB7d8bff"
    }
  }
}

License Configuration​

Allows to configure the license usage policy under the license section of the entitlement message. Root-level features are applied in case of all DRM technologies. DRM-specific sections apply to the respective DRMs only. If not specified, the default license configuration is used. Refer to license configuration document to read more about each configuration.

Content Keys Source​

Allows to specify a content keys source under the content_keys_source section of the entitlement message. These sources provide alternative ways of providing or generating content keys. Note: exactly one content keys source must be specified at a time. Refer to content key source document to read more about each configuration.

Content Key Usage Policies​

Allows to specify a list of content key usage policies or the rules that can be applied individually to each content key. You can set the rules under the content_key_usage_policies section of the entitlment service. A content key usage policy with matching name must be provided for all content keys that reference a specific policy. Unreferenced policies are ignored. Refer to content key usage policies document to read more about each configuration.

License Service Configuration​

The License Service Configuration(license_server) section of Entitlement Message allows default behavior that is not related to generating a License to be overridden.
Refer to license service configuration document to read more about each configuration.

Session​

Allows to specify data related to a particular session.

The structure of a Session object is defined as follows.

entitlement_message.session
{
  "id": "session_0001|content_0001",
  "user_id": "user_0001"
}
DefaultSettings in this section have their default behaviour.
Supported valuesAny valid Session object (see below).

id​

Allows to specify a custom ID for the playback session the current licenses request is associated with.

This is mandatory when using Concurrent Stream Limiting in session-based modes. Exception is when using CSL only with DRMs that support native session IDs and the relevant use_native_session_ids settings are enabled.

Note: in cases providing a secure custom session ID is not feasible, providing the content ID may suffice.

See the CSL guide for more information.

RequiredMandatory in certain CSL workflows
DefaultCustom session IDs are not used
Supported valuesAny non-empty string that does not consist solely of whitespace.
AvailabilityAxinom DRM FairPlay API 6.23.0+, Widevine API 6.28.0+, PlayReady API 6.22.0+

user_id​

Allows to specify the user ID associated with an end user. This value is logged for each license request.

This value shall be filled with a unique value for each end-user if Axinom DRM is used with the subscription-based billing model.

DefaultUser-ID logging and mechanisms based on it are disabled.
Supported valuesAny non-empty string that does not consist solely of whitespace.

Comparison to Entitlement Message v1​

Entitlement Message v2 was designed and implemented to meet the new requirements of the movie studios. Movie studios require that separate tracks - SD, HD, AUDIO etc. - are encrypted with different Content Keys. Furthermore, in many cases, it is required that Content Keys associated with different tracks have different robustness configurations. For example, it is a common policy that a Content Key for an HD track shall have stronger security restrictions than a Content Key for an SD track.

Entitlement Message v1 offers the ability to use different Content Keys for separate tracks. However, robustness configuration in Entitlement Message v1 is the same for all Content Keys and fine-grained tuning cannot be performed. This restriction leaves only two choices. The first option is to use a global robustness configuration meant for SD tracks. However, this conflicts with movie studios' policies as it is not allowed to use such a robustness configuration for HD tracks. The second option is to do the same but use a robustness configuration meant for HD tracks. From movie studios' point of view, this would be fine as no security is sacrificed. However, it would cause undesired side effects, such as some less secure devices not being able to play even SD tracks because the level of security restrictions is too strict. Neither of the two are good choices.

Entitlement Message v2 solves the problems that one might encounter with Entitlement Message v1 in complex scenarios. Entitlement Message v2 allows defining any number of robustness configurations and associating them with specific Content Keys. This results in an ideal solution where mild and strong security policies are assigned to Content Keys for lower and higher quality levels, respectively, while compliant with the movie studios' requirements and not making sacrifices in terms of device compatibility.

If you are an existing customer and you do not need the added flexibility in Entitlement Message v2, you may continue to use Entitlement Message v1. However, it is always recommended to upgrade to what is latest. It is a strong recommendation that all new customers use Entitlement Message v2.

Revision History​

The table below outlines the document versions and any changes between them.

Version

Date

Description

4.0

April 29, 2019

Added the License Service Configuration to root structure of Entitlement Message along with its parameter return_license_request_info.

5.0

October 25, 2019

Added the FairPlay playback_duration license configuration option.

6.0

October 31, 2019

Updated document styling.

7.0

November 28, 2019

Added the Access Control option sub-section to License Server Configuration and updated document styling.

8.0

December 2, 2019

Added the Session section to the root structure of Entitlement Message.

9.0

February 4, 2020

Clarified requirements for the user_id field in the Session section.

10.0

September 1, 2020
  • Added the allowed_device_certificate_serial_numbers Widevine access control option.
  • Deprecated allowed_device_ids for Widevine access control.

11.0

October 14, 2020

Changed the allowed_device_certificate_serial_numbers to a GUID value from a base64 string.

11.1

March 23, 2021

Updated the "play_enablers" GUID values.

12.0

April 20, 2021

Added frequently used values for PlayReady usage rules according to PlayReady Compliance Rules.

13.0

November 1, 2021

Added include_all_entitled_keys license configuration option for Widevine.

14.0

Devember 27, 2021
  • Added FairPlay hdcp content key usage policy option.
  • Added "feature availability" information to recent new features. This will be added also for all subsequent features.

15.0

July 28, 2022

Added FairPlay ignore_keys_in_license_request license configuration option.

16.0

September 01, 2023
  • Added Widevine renewal settings: allow_renewal, renewal_delay, renewal_recovery, renew_with_usage, renewal_url, renewal_retry_interval.
  • Added Widevine Verified Media Platform (VMP) settings: min_vmp_level, allow_tampered_platforms, allow_non_vmp_platforms.

17.0

September 20, 2023

Added Widevine 2.3 HDCP setting.

18.0

December 15, 2023
  • Added new Widevine settings: allow_playback,real_time_duration_expiration, real_time_playback_expiration,Widevine-specific duration override, Widevine-specific allow_persistence override.
  • Styling and wording adjustments, and some changes to examples.

19.0

April 02, 2024
  • Added new FairPlay settings: allow_airplay, allow_av_adapter
  • Added new PlayReady-specific overrides: duration, allow_persistence
  • Added new FairPlay-specific overrides: duration, allow_persistence

20.0

April 21, 2025
  • Added the prevent_drm_message_reuse setting

21.0

May 13, 2025
  • Documented the stored content keys source

22.0

June 10, 2025

Added Concurrent Stream Limiting related settings: concurrency_limit, concurrency_mode, concurrency_interval, concurrency_grace_period, session.id, use_native_session_ids.