Entitlement Message Version 2

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.

Root Structure

The root structure of Entitlement Message v2 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":
    {

    }
}

License Configuration

Allows to configure the license usage policy under the license section of the entielment 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.

The structure of a License Configuration object is defined as follows.

entitlement_message.license

"license":
{
    "start_datetime": "2017-01-01T00:00:00+03:00",
    "expiration_datetime": "2019-01-01T00:00:00+03:00",
    "duration": 3600,

    "allow_persistence": false,

    "fairplay":
    {
        "real_time_expiration": false,
        "playback_duration": 3600,
        "ignore_keys_in_license_request": false,

        "duration": 3600,
        "allow_persistence": "false"
    },

    "playready":
    {
        "real_time_expiration": false,
        "playback_duration": 3600,
        "custom_data": "Custom Data.",

        "duration": 3600,
        "allow_persistence": "false"
    },

    "widevine":
    {
        "playback_duration": 3600,
        "real_time_duration_expiration": true,
        "real_time_playback_expiration": true,

        "allow_playback": true,
        "allow_renewal": false,

        "renewal_delay": 300,
        "renewal_recovery": 60,
        "renewal_retry_interval": 10,
        "renew_with_usage": false,
        "renewal_url": "https://example.com",

        "include_all_entitled_keys": false,

        "duration": 3600,
        "allow_persistence": false
    }
}

Default	All settings in this section have their default behaviour.
Data type	License Configuration object.
Supported values	Any valid License Configuration object (see below).

The License Configuration object consists of the following properties:

start_datetime

The license start date-time is the time when the license becomes active. The playback only works when the license is active. If not specified, the license becomes active right after it is generated. In the case of FairPlay, this value isn’t applied, as FairPlay licenses always become active right after generation.

Default	License star time is not limited.
Supported values	Any string that represents the combined date and time value in the ISO 8601 format, for example: "2023-08-18T15:22:40+03:00". Time zones are supported as well. Allowed range: 21st century: 2000-01-01T00:00:00.0000000 +00:00 - 2100-01-01T00:00:00.0000000+00:00.

expiration_datetime

The license expiration date-time is the time after which the license becomes inactive. If not specified, the license never expires, unless other features are used to limit it. Expiration date-time may not be used together with license duration. When the license expires, it depends on the DRM system and other policies whether the playback stops in real-time or the current playback session is allowed to continue:

• FairPlay: playback doesn’t stop in real-time, unless real-time expiration is specified. Note: this feature is supported only on iOS 9+; in other cases, it is not applied.
• PlayReady: playback doesn’t stop in real-time, unless real-time expiration is specified.
• Widevine: playback stops in real-time.

Default	License expiration is not limited by this setting.
Supported values	Any string that represents the combined date and time value in the ISO 8601 format, for example: "2023-08-18T16:22:40+03:00". Time zones are supported as well. Allowed range: 21st century: 2000-01-01T00:00:00.0000000 +00:00 - 2100-01-01T00:00:00.0000000+00:00.

duration

The license duration is the span of time in seconds during which the license is active, counted from the time the license request is created. If not specified, the license never expires, unless other features are used to limit it. License duration may not be specified together with either license start or expiration date-time. When the duration is exceeded, the license becomes inactive. However, depending on the DRM system and other policies, current playback session may be allowed to continue (non-real-time expiration):

• FairPlay: playback doesn’t stop in real-time, unless real-time expiration is specified. Note: this feature is supported only on iOS 9 onwards; in other cases, it is ignored.
• PlayReady: playback doesn’t stop in real-time, unless real-time expiration is specified.
• Widevine: playback stops in real-time by default.

Default	License expiration is not limited by this setting.
Supported values	Any integer in the range 1 to 4294967295.

allow_persistence

Allows to specify whether the license can be persisted on the playback device. If false, the playback client cannot store the license. If true, it depends on the DRM system and the client application whether the license is persisted:

• FairPlay: license may or may not be persisted, depending on the playback application implementation.
• PlayReady: playback application is guaranteed to store the license on the playback device.
• Widevine: license may or may not be persisted, depending on the playback application implementation.

Also, PlayReady has the following limitation:

• PlayReady 2 and older clients do not support multiple keys in case persistence is not allowed. Therefore, to ensure compatibility, only one key should be present in the entitlement message. In practice, however, PlayReady clients only request a single key per license request, in which case only a single key is in the license, even if more are specified in the entitlement message.

Also, FairPlay has the following limitations:

• Persistent licenses are supported only on iOS 10+. On other devices it is treated as a default in-memory license that ignores expiration date and license duration settings and is active until playback is stopped.
• Persistent licenses don’t support and ignore real-time expiration setting.

Default

false

Supported values

false - the license is non-persistent. An in-memory license that is never stored on the device and is discarded as soon as the playback session ends. Internet connection is required for each playback. true - the license is persistent. It is stored on the client device, in a local license store. Internet connection is not required for playback once the license has been stored. Expired licenses are not usually automatically cleaned up - this needs to be performed by player logic.

FairPlay

Allows to specify FairPlay DRM specific license configuration features.

Default	All settings in this section have their default behaviour.
Supported values	Omitted, or any valid FairPlay License Configuration object (see below).

The FairPlay License Configuration object consists of the following properties:

duration

Same as the global duration, except it only affects FairPlay and overrides the global duration when both are set. Can be used in special cases where there is a need to specify a different license duration for different DRMs.

Default	This setting is ignored.
Supported values	Any integer in the range 1 to 4294967295.
Availability	Axinom DRM FairPlay API v6.20.0+

allow_persistence

Same as the global allow_persistence, except it only affects FairPlay and overrides the global setting. Can be used in special cases where there is a need to have different settings for different DRMs in a single Entitlement Message.

Default	false
Supported values	true, false
Availability	Axinom DRM FairPlay API v6.20.0+

real_time_expiration

Allows to specify whether the license must expire in real time, during the playback. Note that this feature is only supported on iOS 9+; in other cases, it is ignored. Also, it has no effect in case of persistent licenses.

Default	false
Supported values	false - the playback continues after the license expires. true - the playback stops right after the license expires.

playback_duration

Allows to specify the amount of seconds that a persistent license is valid for after playback has been started for the first time. If license duration is shorter than playback duration, then license duration takes precedence.

Note: this feature has effect only on iOS 11+. This feature can only be used if persistence is allowed.

Default	Playback duration is not limited.
Supported values	Any integer in the range 1 - 4294967295.

ignore_keys_in_license_request

Background: for FairPlay there is no standardized "PSSH box" to signal the keys requested with specific content. The keys are references instead by the Asset ID (in HLS manifest it is the URI attribute value of EXT-X-KEY tags), which is in custom format for every DRM service provider. Due to this, when switching the DRM service provider, the new provider can’t read the format to determine the keys.

When the option ignore_keys_in_license_request is set, the content key information in the Asset ID field of the license request (SPC) is ignored. The Asset ID won’t be parsed and the content key for the license will be obtained only based on the information in the Entitlement Message. If there are many keys, only the first is used; if there are no keys, license request will fail.

This is intended to be used as a workaround in scenarios where it’s not possible to provide an Axinom-compatible Asset ID in the license request. Using this feature generally is not recommended, as it makes it impossible for the license service to cross-reference if the returned key is actually the one the client needs to use based on the information e.g. in the media manifest.

This feature is not compatible with the "license_request" content keys source.

Default	false
Supported values	false - default workflow. Requires a valid Axinom-compatible Asset ID in the license request. true - Asset ID in the license request is ignored. Content keys are obtained based on the Entitlement Message only.
Availability	Axinom DRM FairPlay API v6.18.0+

PlayReady

Allows to specify PlayReady DRM specific license configuration features.

Default	All settings in this section have their default behaviour.
Supported values	Omitted, or any valid PlayReady License Configuration object (see below).

The PlayReady License Configuration object consists of the following properties:

duration

Same as the global duration, except it only affects PlayReady and overrides the global duration when both are set. Can be used in special cases where there is a need to specify a different license duration for different DRMs.

Default	This setting is ignored.
Supported values	Any integer in the range 1 to 4294967295.
Availability	Axinom DRM PlayReady API v6.20.0+

allow_persistence

Same as the global allow_persistence, except it only affects PlayReady and overrides the global setting. Can be used in special cases where there is a need to have different settings for different DRMs in a single Entitlement Message.

Default	false
Supported values	true, false
Availability	Axinom DRM PlayReady API v6.20.0+

real_time_expiration

Allows to specify whether the license must expire in real time, during the playback. Note: PlayReady 2 and older clients do not support this feature; if real_time_expiration is specified for such clients, the license is denied.

Default	false.
Supported values	false - current playback session is allowed to be finished after the license expires. true - playback stops right after the license expires.

playback_duration

Allows to specify, in seconds, for how long the playback is allowed after it has been started for the first time. If the playback duration is exceeded, the playback stops. If not specified, the license never expires after it has been started for the first time, unless there are other policies that limit its duration.

Default	Playback duration is not limited.
Supported values	Any integer in the range 1 to 4294967295.

custom_data

Allows to specify the custom data of the license response.

Default	No custom data is added to the license.
Supported values	Any string, for example: "My custom data."

Widevine

Allows to specify Widevine DRM specific license configuration features.

Default	All settings in this section have their default behaviour.
Supported values	Omitted, or any valid Widevine License Configuration object (see below).

The Widevine License Configuration object consists of the following properties:

duration

Same as the global duration, except it only affects Widevine and overrides the global duration when both are set. Can be used in special cases where there is a need to specify a different license duration for different DRMs.

A more common use-case is "license renewals", where Widevine renewal window is mainly dictated by renewal_delay + renewal_recovery and duration dictates the overall playback window and can be long, while for other DRMs duration dictates the extendable renewal window and should be short.

Default	This setting is ignored.
Supported values	Any integer in the range 1 to 4294967295.
Availability	Axinom DRM Widevine API v6.22.0+

playback_duration

Allows to specify, in seconds, for how long the playback is allowed after it has been started for the first time. If the playback duration is exceeded, the playback stops. If not specified, the license never expires after it has been started for the first time, unless there are other policies that limit its duration.

note

A significant difference between duration and playback_duration is that the first starts counting down from the time the license is acquired, while the second is counted from the time of the first playback (first license use). This is usually not important for "streaming" or online scenarios (as license acquisiton and use happen shortly after each other), but can enable advanced offline playback scenarios when using persistent licenses.

Default	Playback duration is not limited.
Supported values	Any integer in the range 1 - 4294967295.

real_time_duration_expiration

Specifies whether the duration setting is enforced in real-time (is "hard-enforced").

When true, playback is stopped immediately when the duration expires, and, in case of persistent licenses, expiration is checked on each license load. In Widevine terms, it is also called "hard(-enforced) rental duration". This is the default behaviour.

When false, the expiry of duration is only checked on first use (loading) of the license. This can be used to limit the time within which a user must start (first) playback. In Widevine terms it is also known as "soft(-enforced) rental duration". This is a more advanced scenario and it is usually recommended to omit the value or set it to true (the default).

Default	true
Supported values	true, false
Availability	Axinom DRM Widevine API v6.22.0+

real_time_playback_expiration

Specifies whether the playback_duration setting is enforced in real-time (is "hard-enforced").

When true, playback is stopped immediately when the playback_duration expires and no subsequent uses of the license are possible. In Widevine terms, this is also known as "hard(-enforced) playback duration." This is the default behaviour.

When false, the existing playback session is allowed to be finished once the duration expires, but no subsequent license uses are permitted. The latter aspect is only relevant when license persistence is allowed.

Default	true
Supported values	true, false
Availability	Axinom DRM Widevine API v6.22.0+

allow_persistence

Same as the global allow_persistence, except it only affects Widevine and overrides the global setting. Can be used in special cases where there is a need to have different settings for different DRMs in a single Entitlement Message.

Default	false
Supported values	true, false
Availability	Axinom DRM Widevine API v6.22.0+

allow_playback

Specifies whether the generated license should allow playback or deactivate an existing license.

Note: This is an advanced setting that usually should be left at its default value.

Default	true
Supported values	true, false
Availability	Axinom DRM Widevine API v6.23.0+

allow_renewal

Specifies whether the license can be renewed. If set to true, then the Widevine CDM on the client device will automatically attempt to renew the license, taking into account the other renewal-related settings.

License renewal can be used to trigger and enforce regular "heart-beat" requests which a proxy or the license service can use to, for example, periodically re-check whether a user is still authorized to view the content or to enforce concurrent playback limits. If renewals are blocked (either maliciously by a "hacker" or legitimately by the license service), then the playback will be limited to the renewal window of renewal_delay + renewal_recovery seconds.

Default	false
Supported values	true, false
Availability	Axinom DRM Widevine API v6.21.0+

renewal_delay

Specifies the delay, in seconds, after which renewal requests are made. This is also known as the renewal interval. The delay is counted from the time the license request (either new or renewal) was generated on the client. Added together with renewal_recovery this setting limits the window where playback possible, until extended by a successful license renewal. If the window expires, playback will stop in real-time. Setting this is only allowed when allow_renewal is true.

note

• If set to 0, then periodic renewals will be disabled. However, a renewal can still be triggered on first license use by setting renew_with_usage to true.
• The minimum allowed renewal delay is 180 seconds, to help prevent unnecessary load on license services. If you require a shorter interval, please contact us.
• The specified delay is subject to slight randomization in order to help prevent request spikes. The randomization algorithm randomly subtracts 0 - 10% from the original value. Example: if the specified renewal delay is 300 seconds, then the delay randomly becomes a value between 270 - 300 seconds. The randomized value will never be greater than the specified value.

Default	300
Supported values	0, 180 - 9223372036854775807
Availability	Axinom DRM Widevine API v6.21.0+

renewal_recovery

Specifies the duration, in seconds, for how long the playback can continue after a renewal has been requested, but no successful response is received (for example due to user being blocked or hitting concurrent playback limits). Once the recovery duration expires, playback will stop in real-time.

Setting this is only allowed when allow_renewal is true. This setting, together with renewal_delay, determines the overall renewal window when the playback is possible, unless extended by a succesful renewal.

tip

• A value of 0 means an unlimited recovery duration. In this case playback will not stop when renewals fail, unless limited by other settings.
• It is not recommended to use low recovery durations (e.g. less than 10 seconds), unless there is a specific requirement for this, as usually there is no benefit in doing so, and it is better to be robust against network latency issues.
• Make sure to set a value that would accommodate the desired amount of retries, taking into account the specified renewal_retry_interval, in case of network errors.

Default	60
Supported values	0 - 9223372036854775807
Availability	Axinom DRM Widevine API v6.21.0+

renewal_retry_interval

Specifies the interval, in seconds, at which renewal is retried, when there is no succesful renewal response. Retries will continue until the existing license expires or renewal_recovery runs out. Setting this is only allowed when allow_renewal is true.

Default	10
Supported values	0, 3 - 9223372036854775807
Availability	Axinom DRM Widevine API v6.21.0+

renew_with_usage

Indicates whether a license renewal request should be made as soon as the license is first used (first playback starts). Setting this is only allowed when allow_renewal is true.

note

Periodic renewals will also additionally take place, if renewal_delay is set to a value greater that 1 second.

Default	false
Supported values	true, false
Availability	Axinom DRM Widevine API v6.21.0+

renewal_url

Specifies the URL where the client should send license renewal requests.

note

• Use this feature only if it’s found to be necessary for some player to support the renewal process. In case of Axinom DRM the same license services handle all types of requests, and usually also players send both new and renewal requests to the same service, unless explicitly configured otherwise.
• It should be noted that this URL is not in any way automatically utilized by the Widevine CDM. The CDM just exposes it to the player code via the relevant APIs. It is the player code that needs query and use this URL.
• Browser-based DRM APIs (EME) do not expose the renewal URL. Therefore, according to our knowledge, it is not possible to take advantage of this feature in browser-based player. However, for example, Android native player application can query this URL via the framework APIs.

Default	Renewal URL is not set.
Supported values	Any string that represents a valid absolute URL with a scheme. For example: "https://example.com/AcquireLicense".
Availability	Axinom DRM Widevine API v6.21.0+

include_all_entitled_keys

Allows to specify whether all the content keys referenced in the Entitlement Message shall be included in the license, instead of only those that are explicitly requested by a playback client in the license request. This has effect only when the inline Content Keys Source is used.

Some players may be able to take advantage of receiving additional (or all) content keys for specific content in a single license, either as a performance optimization or to enable additional workflows. One such example is enabling the persistence of multi-key content using ExoPlayer (for more details, see here).

Another common example is when using multi-key content with Widevine where keys have different security level requirements. When Axinom DRM receives a request for a key where its security level requirement is higher than that of the client device security level, the general behavior would be to fail the request. Instead, the service could return e.g. Audio and SD keys in the same license, which results in a successful license request, but just with one less key delivered. In this case, the players are usually happy and continue to play the SD track instead.

Default	false
Supported values	false - only the entitled keys that are also referenced in the license request are included in the license. true - all keys referenced in the Entitlement Message are included in the license.
Availability	Axinom DRM Widevine API v6.16.0+

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.

The structure of a Content Keys Source object is defined as follows.

entitlement_message.content_keys_source

"content_keys_source":
{
    "inline":
    [
        {
            "id": "11111111-0000-0000-0000-000000000000",
            "encrypted_key": "EREREREREREREREREREREQ==",
            "iv": "EREREREREREREREREREREQ==",
            "seed_id": "88888888-0000-0000-0000-000000000000",
            "usage_policy": "Policy A"
        }
    ],

    "license_request":
    {
        "seed_id": "88888888-0000-0000-0000-000000000000",
        "usage_policy": "Policy A"
    }
}

Required	YES
Supported values	Any valid Content Keys Source object (see below).

The Content Keys Source object consists of the following properties:

Inline

Allows to specify the content keys that can be included in the license. Whether the content key is included into the license response or not, depends on key IDs in the license request. Only the content keys the IDs of which are also present in the license request are included. If, however, the license request contains any key ID not specified here, the license is denied.

Required	One of the content key sources must be specified.
Default	No content keys are entitled (only useful for testing)
Supported values	Any array of valid Content Key objects (see below).

The Content Key object consists of the following properties:

id

Specifies the ID of the content key (also known as "key ID" or "KID"). It can be any valid GUID in the 00000000-0000-0000-0000-000000000000 format.

Required	Yes
Supported values	Any valid GUID string in the "00000000-0000-0000-0000-000000000000" format.

seed_id

Specifies the ID of a key seed that is used to generate the content key. If not specified, the default key seed of the tenant is used. Note: the "seed_id" and "encrypted_key" properties are mutually exclusive.

Default	The default key seed will be utilized.
Supported values	Any valid GUID string in the "00000000-0000-0000-0000-000000000000" format.

encrypted_key

Allows to provide the content key itself, in encrypted form, encoded using the Base64 encoding (RFC 4846). The key (exactly 16 bytes) must be encrypted using the AES-CBC algorithm, without padding, where the encryption key is the tenant’s communication key and the initialization vector (IV) is the content key ID in big-endian byte order. For example, when using the following key ID, "1E0DE660-B47E-4C79-B5CE-EDBD72BB17B3", as the IV for encryption, its byte representation must be "0x1E0DE660B47E4C79B5CEEDBD72BB17B3". If not specified, a content key is generated based on the key ID and the default key seed of the tenant. Note: the "encrypted_key" and "seed_id" properties are mutually exclusive.

Default	Content key is generated based on a key seed.
Supported values	Any string representing Base64-encoded 16-byte binary data, for example: "HYDILKxZnPF0KizuWT0hww==".

iv

Initialization vector (IV; exactly 16 bytes) is a randomizer that has an impact on generating the random content key. When regenerating the content Key, along with the content Key ID, Iv is needed. The IV is encoded as Base64 using a hex to Base64 converter tool, shall be used for the decryption of media together with the provided or generated content key. Only used by FairPlay DRM; ignored otherwise.

Required	Depends*.
Default	The IV is loaded from another source.
Supported values	Any string representing Base64-encoded 16-byte binary data, for example: "6oDIr6xZnPF0KizuWT0s1g==".

*It is required to specify the IV here when it is not provided as part of the asset ID in the FairPlay license request passed by the player CDM. In case it’s provided both here and in the license request, the IV specified here takes precedence.

If the passed IV is different than the IV that is used in encryption, there will be playback errors.

usage_policy

Specifies the name of the content key usage policy that is applied to this content key (see Content Key Usage Policies). If not specified, the default server-side content key usage policy is applied to this key. The default content key usage policy is the one with all its properties set to their default values.

Default	The default usage policy is applied to this key.
Supported values	Any non-empty string, for example: "Policy A".

License Request

Allows to specify that content keys are generated and included into the license only based on the key IDs present in the license request. This can be set under the license_request section of the Entitlement service. In the case of FairPlay, this feature is allowed only when the key IV is provided in the asset ID of the license request. Usage of this content keys source is mutually exclusive with other sources. If not specified, another content keys source must be used.

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

Required	One of the content key sources must be specified.
Supported values	Any valid License Request Content Keys Source object (see below).

The License Request Content Keys Source object consists of the following properties:

seed_id

The ID of the key seed that shall be used for generating content keys. If the key seed ID is specified, it must reference an existing key seed, otherwise the license is denied. If not specified, the default key seed of the tenant is used for key generation.

Default	The default key seed is utilized.
Supported values	Any string that represents a valid GUID string in the "00000000-0000-0000-0000-000000000000" format.

usage_policy

The name of the content key usage policy that is associated with the generated content key(s) (see Content Key Usage Policies). If not specified, the default server-side content key usage policy is associated with the content keys.

Default	The default usage policy is applied to this key.
Supported values	Any non-empty string, for example: "Policy A".

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.

note

In case a content key usage policy is not supported by a specific playback client, then the associated keys are not included in the license; if this results in all keys being ineligible, the license is denied.

The structure of a Content Key Usage Policies object is defined as follows.

entitlement_message.content_key_usage_policies example (note that the GUIDs shown below are random example values)

"content_key_usage_policies":
[
    {
        "name": "Policy A",

        "fairplay":
        {
            "hdcp": "TYPE0",
            "allow_airplay": true,
            "allow_av_adapter": true
        },

        "widevine":
        {
            "device_security_level": "SW_SECURE_DECODE",
            "cgms-a": "once",
            "hdcp": "2.0"
        },

        "playready":
        {
            "min_device_security_level": 2000,

            "analog_video_opl": 100,

            "compressed_digital_audio_opl": 200,
            "uncompressed_digital_audio_opl": 300,
            "compressed_digital_video_opl": 400,
            "uncompressed_digital_video_opl": 500,

            "source_id": "<value>",

            "play_enablers":
            [
                "<value1>",
                "<value2>"
            ],

            "analog_video_output_protections":
            [
                {
                    "id": "<value>",
                    "config_data": "6BA/7HbTQB6r/IEvWN8Zog=="
                }
            ],

            "digital_video_output_protections":
            [
                {
                    "id": "<value>",
                    "config_data": "b3J+qoMeT5mcgykqXzBeIQ=="
                }
            ],

            "digital_audio_output_protections":
            [
                {
                    "id": "<value>",
                    "config_data": "cgmHUW9WSbawcgKzXLpq6Q=="
                }
            ]
        }
    }
]

Default	No custom usage policies are defined.
Supported values	Any array of valid Content Key Usage policy objects (see below).

The Content Key Usage Policy object consists of the following properties:

name

The name of the content key usage policy. This policy is associated with all content keys that have a matching name in their "usage_policy" property. Multiple policies with the same name are not allowed.

Required	Yes
Supported values	Any non-empty string, for example: "Policy A".

FairPlay

Allows to specify a list of FairPlay-specific content key usage policies. These policies only have an effect if FairPlay DRM is used.

Default	Settings in this section will have their default behaviour.
Supported values	Any array of valid FairPlay Content Key Usage Policy objects (see below).

hdcp

Allows to specify the HDCP rule clients enforce when playing back protected media. If the client can’t enforce a particular rule then the video stream to the uncompliant output will be blocked.

Note that some FairPlay clients (likely limited to older clients) do not support HDCP rule configuration and always enforce HDCP Type 0, which is the default for all FairPlay clients. In case of such clients, if a more restrictive HDCP rule than Type 0 is strictly required, license service can be instructed to deny the license (see the "_STRICT" option below).

Default	"TYPE0"
Supported values	"NONE" - HDCP is not enforced. If a client doesn’t support the HDCP configuration feature, it falls back to enforcing HDCP Type 0. "TYPE0" - HDCP Type 0 (HDCP v1.x, v2.x) is enforced. This is the default behaviour of FairPlay clients and it is supported by all clients. "TYPE1" - HDCP Type 1 (HDCP v2.2+) is enforced. If a client doesn’t support the HDCP configuration feature, it falls back to enforcing HDCP Type 0. "TYPE1_STRICT" - HDCP Type 1 is enforced. If a client doesn’t support the HDCP configuration feature, then the license will be denied.
Availability	Axinom DRM FairPlay API v6.16.0+

allow_airplay

Specifies whether to allow license acquisition when the client has engaged AirPlay streaming. If AirPlay is not allowed and the client switches to AirPlay mode, triggering a new license request, the license will be denied.

Default	true
Supported values	true - streaming content via AirPlay is allowed. false - license acquisition will be denied when AirPlay is active.
Availability	Axinom DRM FairPlay API v6.21.0+

allow_av_adapter

Specifies whether to allow license acquisition when the client is streaming content over an Apple AV Adapter. If using AV Adapter is not allowed and the client switches to using one, the license will be denied.

Default	true
Supported values	true - streaming content via an Apple AV Adapter is allowed. false - license acquisition will be denied when an Apple AV Adapter is used.
Availability	Axinom DRM FairPlay API v6.21.0+

PlayReady

Allows to specify a list of PlayReady-specific content key usage policies. These policies only have an effect if the PlayReady DRM is used.

tip

For the full list of available PlayReady-settings and their impact see PlayReady Compliance Rules.

Default	Settings in this section will have their default behaviour.
Supported values	Any array of valid PlayReady Content Key Usage Policy objects (see below).

The PlayReady Content Key Usage Policy object consists of the following properties:

min_device_security_level

Allows to specify the minimum security level that the playback client must have to use the license. If the minimum security level specified for a content key is higher than what is supported by the client, then this key is not included in the license. Note: the maximum security level for PlayReady 2 and older clients is 2000. You can find a list of security level mappings here.

Default	2000
Supported values	150 - software-based security, which is the least secure and is intended for testing purposes only. 2000 - software-based security, which is secure and is intended for production purposes. 3000 - hardware-based security, which is the most secure and is intended for production purposes.

analog_video_opl

Allows to specify the output protection level for analog video content. The client must have protection technology equal to or greater than the specified level to play the content.

Default	0
Supported values	0 - 65535. See the PlayReady Compliance Rules for the list of valid values and their meaning.

compressed_digital_audio_opl

Allows to specify the output protection level for compressed digital audio content. The client must have protection technology equal to or greater than the specified level to play the content.

Default	0
Supported values	0 - 65535. See the PlayReady Compliance Rules for the list of valid values and their meaning.

uncompressed_digital_audio_opl

Allows to specify the output protection level for uncompressed digital audio content. The client must have protection technology equal to or greater than the specified level to play the content.

Default	0
Supported values	0 to 65535. See the PlayReady Compliance Rules for the list of valid values and their meaning.

compressed_digital_video_opl

Allows to specify the output protection level for compressed digital video content. The client must have protection technology equal to or greater than the specified level to play the content.

Default	0
Supported values	0 - 65535. See the PlayReady Compliance Rules for the list of valid values and their meaning.

uncompressed_digital_video_opl

Allows to specify the output protection level for uncompressed digital video content. The client must have protection technology equal to or greater than the specified level to play the content.

Default	0
Supported values	0 - 65535. See the PlayReady Compliance Rules for the list of valid values and their meaning.

source_id

Allows to specify the identifier of the source content protection system. Some protection systems (for example: CGMS-A, DTCP, etc.) require the source ID to be present in the license.

Default	0 (meaning that the source ID isn’t added to the license).
Supported values	0 - 65535. See the PlayReady Compliance Rules for the list of valid values and their meaning.

Some frequently used values:

Name	Value
Macrovision	1
CGMS-A	2
OpenCable Unidirectional Receiver (OCUR)	4
CPRM, CPPM	257
DTCP	258
OMA/CMLA	259
AACS (pre-recorded)	262
AACS (recordable)	263
DTCP at no greater than 520,000 pixels per frame	265
ISDB	266
UltraViolet™ Download	267
UltraViolet™ Streaming	268

play_enablers

Allows to set a list of GUID IDs of the technologies to which protected content is allowed to flow. For example: AirPlay, DTCP, etc.

Default	No play enablers are added to the license.
Supported values	Any array of strings that represent valid GUIDs in the "00000000-0000-0000-0000-000000000000" format. See the PlayReady Compliance Rules for valid values and their meaning. For example: [ "7d9ae684-bd6a-4234-b1d5-910d1b4bed62", "81b6f874-7614-47b5-b79d-8193630ce358" ]

Some frequently used values:

Name	Value
Helix	002F9772-38A0-43E5-9F79-0F6361DCC62A
HDCP / WiVu	1B4542E3-B5CF-4C99-B3BA-829AF46C92F8
HDCP / Miracast	A340C256-0941-4D4C-AD1D-0B6735C0CB24
AirPlay	5ABF0F0D-DC29-4B82-9982-FD8E57525BFC
DTCP	D685030B-0F4F-43A6-BBAD-356F1EA0049A

note

In case the playback output is unknown (e.g. if the playback is attempted in a virtual machine), a play enabler may have to be added to avoid problems. Playback to unknown outputs can be enabled by adding the "786627D8-C2A6-44BE-8F88-08AE255B01A7" play enabler. See the PlayReady Compliance Rules (section 3.9.1) for details.

analog_video_output_protections

Allows to specify output protections that are allowed to play protected analog video content. For example, CGMS-A.

Default	No analog video output protections are added to the license.
Supported values	An array of Output Protection objects (see the example for details), which contain: "id" - any valid GUID in the 00000000-0000-0000-0000-000000000000 format, which represents the ID of the output protection technology. "config_data" - any binary data encoded using base64 encoding, which conforms to RFC 4846. See the PlayReady Compliance Rules for valid values and their meaning.

Some frequently used values:

Name	Value	Binary Configuration
AGC and Color Stripe	C3FD11C6-F8B7-4D20-B008-1DB17D61F2DA	0,1,2,3
Explicit Analog Television Output Restriction	2098DE8D-7DDD-4BAB-96C6-32EBB6FABEA3	0,1,2,3
Best Effort Explicit Analog Television Output Restriction	225CD36F-F132-49EF-BA8C-C91EA28E4369	0,1,2,3
Image constraint for Analog Component Video Output	811C5110-46C8-4C6E-8163-C0482A15D47E	520000
Image constraint for Analog Computer Monitor Output	D783A191-E083-4BAF-B2DA-E69F910B3772	520000
Digital Video Only Content	760AE755-682A-41E0-B1B3-DCDF836A7306	0

digital_video_output_protections

Allows to specify output protections that are allowed to play protected digital video content. For example, HDCP.

note

This feature is not supported by PlayReady 2 and older clients; for those clients, keys for which this feature is specified are not included in the license.

Default	No digital video output protections are added to the license.
Data type	Array of Output Protection objects (see the example for details).
Supported values	An array of Output Protection objects (see the example for details), which contain: "id" - any valid GUID in the 00000000-0000-0000-0000-000000000000 format, which represents the ID of the output protection technology. "config_data" - any binary data encoded using base64 encoding, which conforms to RFC 4846. See the PlayReady Compliance Rules for valid values and their meaning.

Some frequently used values:

Name	Value	Binary Configuration
HDCP Type Restriction	ABB2C6F1-E663-4625-A945-972D17B231E7	1
Maximum Effective Resolution Decode Size	9645E831- E01D-4FFF-8342-0A720E3E028F	Maximum Frame Width in Pixels, Maximum Frame Height in Pixels

digital_audio_output_protections

Allows to specify output protections that are allowed to play protected digital audio content. For example, SCMS.

Default	No digital audio output protections are added to the license.
Data type	Array of Output Protection objects (see the example for details).
Supported values	An array of Output Protection objects (see the example for details), which contain: "id" - any valid GUID in the 00000000-0000-0000-0000-000000000000 format, which represents the ID of the output protection technology. "config_data" - any binary data encoded using base64 encoding, which conforms to RFC 4846. See the PlayReady Compliance Rules for valid values and their meaning.

Some frequently used values:

Name	Value	Binary Configuration
SCMS	6D5CFA59-C250-4426-930E-FAC72C8FCFA6	00, 01, 10, 11

Widevine

Allows to specify a list of Widevine-specific content key usage policies. These policies only have an effect if the Widevine DRM is used.

Default	The settings in this section have their default behaviour.
Supported values	Any array of valid Widevine Content Key Usage Policy objects (see below).

The Widevine Content Key Usage Policy object consists of the following properties:

device_security_level

Allows to specify the minimum security level that the device must have in order to acquire the license. If the device doesn’t meet the security requirements, playback is not allowed.

Default

"SW_SECURE_CRYPTO".

Supported values

"SW_SECURE_CRYPTO" - software-based whitebox crypto is required. "SW_SECURE_DECODE" - software crypto and an obfuscated decoder are required. "HW_SECURE_CRYPTO" - the key material and crypto operations must be performed within a hardware-backed trusted execution environment. "HW_SECURE_DECODE" - the crypto and decoding of content must be performed within a hardware-backed trusted execution environment. "HW_SECURE_ALL" - the crypto, decoding, and all handling of the media (compressed and uncompressed) must be handled within a hardware-backed trusted execution environment.

You can read more about setting the security levels with Axinom DRM from here.

cgms-a

Allows to specify the CGMS-A rule that must be used by the device while playing the protected media. CGMS-A doesn’t affect playback. It only affects the possibility of recording (copying) protected media.

Default	CGMS-A isn’t enforced.
Supported values	free - unlimited number of copies may be made. once - only one generation of copies may be made. never - no copying permitted.

hdcp

Allows to specify the HDCP rule that must be used in order to play protected media. If the specified HDCP rule is not supported by the device, playback is not allowed.

Default	HDCP is not enforced.
Supported values	1.0 2.0 2.1 2.2 2.3 (Axinom DRM Widevine API v6.22.0+) NO_DIGITAL_OUTPUT

disable_analog_output

Allows to specify whether analog output shall be disallowed.

Default	false
Supported values	false - analog output is allowed. true - analog output is not allowed.

License Service Configuration

The License Service Configuration(license_server) section of Entitlement Message v2 allows default behavior that is not related to generating a License to be overridden.

The structure of a License Service object is defined as follows.

entitlement_message.license_server

{
    "return_license_request_info": true,

    "access_control":
    {
        "allowed_ip_addresses":
        [
            "10.11.12.13",
            "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
        ],

        "fairplay":
        {
            "allowed_device_ids":
            [
                "dd5f6907-f579-45e0-8b49-632a49d4fe55",
                "ded51696-dd59-464c-9890-5b6db5e673c3"
            ]
        },

        "playready":
        {
            "allowed_device_ids":
            [
                "ed85e2bc-63d8-4a26-8ad0-18c382c12dd9",
                "0d268a04-ca6e-4e9e-8412-e05344817cf5"
            ]
        },

        "widevine":
        {
            "min_vmp_level": "PLATFORM_SOFTWARE_VERIFIED",
            "allow_tampered_platforms": false,
            "allow_non_vmp_platforms": true

            "allowed_device_ids":
            [
                "fbdcdcaf-af84-4bf3-8dbf-3e7c47922c65",
                "5a0f8872-4c83-4362-a6b5-03228a4547ce"
            ],

            "allowed_device_certificate_serial_numbers":
            [
                "29a622dd-ef79-4f8f-92be-96175a3e145d",
                "5a164b33-63fc-4ac6-a7db-b304f897e08f"
            ]
        }
    }
}

return_license_request_info

Allows to specify if license request info is returned.

Default	false
Supported values	false - License request info is not returned. true - License request info is returned.

access_control

Allows to specify restrictions on which clients can obtain a License.

note

This object uses device IDs. For more information on device IDs, see the License Request Info Message document.

Default	The settings in this section have their default behaviour.
Supported values	Any valid Access Control object (see below).

allowed_ip_addresses

Allows to specify a list of client IP addresses that may receive a License. If a client’s IP address is not in this list they are not allowed to receive a License. If this list is defined but empty then no clients receive a License.

Default	No IP addresses are restricted.
Supported values	Any array of strings, each of which represents an IP address in IPv4 or IPv6 format. For example: ["10.11.12.13", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]

fairplay

Allows to specify restrictions on which clients can obtain a License from Axinom DRM FairPlay API. These access controls only have an effect if the FairPlay DRM is used.

Default	The settings in this section have their default behaviour.
Supported values	Any valid FairPlay Access Control object (see below).

allowed_device_ids

Allows to specify a list of client device IDs that may receive a License. If a client’s device ID is not in this list they are not allowed to receive a License. If this list is defined but empty, no clients receive a License.

Default	No device IDs are restricted.
Supported values	Any array of strings, each of which represents a GUID. For example: ["dd5f6907-f579-45e0-8b49-632a49d4fe55", "ded51696-dd59-464c-9890-5b6db5e673c3"]

playready

Allows to specify restrictions on which clients can obtain a License from Axinom DRM PlayReady API. These access controls only have an effect if the PlayReady DRM is used.

Default	The settings in this section have their default behaviour.
Supported values	Any valid PlayReady Access Control object (see below).

allowed_device_ids

Allows to specify a list of client device IDs that may receive a License. If a client’s device ID is not in this list they are not allowed to receive a License. If this list is defined but empty, no clients receive a License.

Default	No device IDs are restricted.
Supported values	Any array of strings, each of which represents a GUID. For example: [ "ed85e2bc-63d8-4a26-8ad0-18c382c12dd9", "0d268a04-ca6e-4e9e-8412-e05344817cf5" ]

widevine

Allows to specify restrictions on which clients can obtain a License from Axinom DRM Widevine API. These access controls only have an effect if the Widevine DRM is used.

Default	The settings in this section have their default behaviour.
Supported values	Any valid Widevine Access Control object (see below).

allowed_device_certificate_serial_numbers

Allows to specify a list of Widevine DRM device certificate serial numbers that may receive a License. If the corresponding device DRM client device certificate serial number is not in this list, it is not allowed to receive a License. If this list is defined but empty, no clients receive a License.

A Widevine DRM device certificate serial number can be retrieved from the LicenseRequestInfo message. To signal the License Service to return the LicenseRequestInfo message, set the return_license_request_info parameter to true in the Entitlement Message. More information on LicenseRequestInfo message can be found in the License Request Info Message documentation.

Default	No devices are restricted by their serial number.
Supported values	Any array of strings, each of which represents a GUID. For example: [ "29a622dd-ef79-4f8f-92be-96175a3e145d", "5a164b33-63fc-4ac6-a7db-b304f897e08f" ]

allowed_device_ids

Allows to specify a list of client device IDs that may receive a License. If a client’s device ID is not in this list, they are not allowed to receive a License. If this list is defined but empty, no clients receive a License.

warning

Current Widevine clients no longer report the Device ID. Use this option only if you need compatibility with older clients. Otherwise, use the allowed_device_certificate_serial_numbers instead.

Default	No devices are restricted by their Device ID.
Supported values	Any array of strings, each of which represents a GUID. For example: [ "fbdcdcaf-af84-4bf3-8dbf-3e7c47922c65", "5a0f8872-4c83-4362-a6b5-03228a4547ce" ]

allow_non_vmp_platforms

Specifies whether client platforms that do not support Verified Media Path (VMP) are allowed to get licenses. Such platforms include: Android, Tizen, WebOS and Roku.

warning

This is an advanced setting that should not be used unless there is a special reason for it. Non-VMP platforms do not implement VMP by design and should not be considered less secure.

Default	true
Supported values	true, false
Availability	Axinom DRM Widevine API v6.21.0+

allow_tampered_platforms

Specifies whether client platforms with tampered Verified Media Path implementation should be allowed to get a license.

warning

It is highly recommended to set this to false. The default is true to align with the default behaviour of Google’s Widevine license service SDK and service, to avoid backwards incompatible changes.

Default	true
Supported values	true, false
Availability	Axinom DRM Widevine API v6.21.0+

min_vmp_level

Specifies the minimum Verified Media Path (VMP) level of client platforms that should be allowed to get a license. Verified Media Path is an anti-tamper system mainly intended to ensure the integrity of browser platforms.

The levels, from the lowest to the highest, are:

1. "PLATFORM_UNVERIFIED" - indicates that a browser-based client is used where the Widevine CDM cannot verify its hosting application. This includes all browser-based platforms on Linux, Electron apps without proper VMP implementation and Chrome OS running in developer mode or with remote attestation blocked.
2. "PLATFORM_SOFTWARE_VERIFIED" - VMP is verified at software level. This is equivalent to clients with L3 security level.
3. "PLATFORM_SECURE_STORAGE_SOFTWARE_VERIFIED" - this is equivalent to clients with L3 security level that also have a secure storage required for license persistence.
4. "PLATFORM_HARDWARE_VERIFIED" - VMP is verified at the hardware level. This is equivalent to clients with L1 security level.

tip

It is recommended to set the minimum VMP level higher than "PLATFORM_UNVERIFIED". However, it should be kept in mind that raising the level beyond the minimum may block some popular platforms, such as browser clients on Linux or some Electron-based solutions without proper VMP implementation.

The default used by Axinom is "PLATFORM_UNVERIFIED", since it is also the default of Google’s Widevine license service SDK and services, and avoids backwards incompatible changes.

Default	"PLATFORM_UNVERIFIED"
Supported values	"PLATFORM_UNVERIFID", "PLATFORM_SOFTWARE_VERIFIED", "PLATFORM_SECURE_STORAGE_SOFTWARE_VERIFIED", "PLATFORM_HARDWARE_VERIFIED"
API support	Widevine API 6.21.0+

Session

Allows to specify data related to a particular session.

The structure of a Session object is defined as follows.

entitlement_message.session

{
    "user_id": "arbitrary_string"
}

Default	Settings in this section have their default behaviour.
Supported values	Any valid Session object (see below).

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.

Default	User-ID logging and meachanisms based on it are disabled.
Supported values	Any 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