Entitlement Message data structure tells the Axinom License Service how to configure a license. Learn about the entitlement message's structure and available options.

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 the documentation for 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 (license), Content Keys Source (content_keys_source), and Content Key Usage Policies (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 (license)

Allows to configure the license usage policy. 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": true,

    "fairplay":
    {
        "real_time_expiration": true,
        "playback_duration": 3600
    },

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

    "widevine":
    {
        "playback_duration": 360000
    }
}

Required

No.

Default value

N/A.

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.

Required

No.

Default value

N/A.

Data type

String (for example: "2015-08-18T15:22:40+03:00").

Supported values

Any string that represents the combined date and time value in the ISO 8601 format (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.

Required

No.

Default value

N/A.

Data type

String (for example: "2015-08-18T15:22:40+03:00").

Supported values

Any string that represents the combined date and time value in the ISO 8601 format (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 and it does not stop in real-time:

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

Required

No.

Default value

N/A.

Data type

Integer (for example: 300; represents seconds).

Supported values

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

Required

No.

Default value

False.

Data type

Boolean (for example: true).

Supported values

  • false - the license is non-persistent. An in-memory license that is never stored on the device. Internet connection is required for each playback.

  • true - the license is persistent. It is stored on the client device, in the local license store. Internet connection is not required for playback once the license has been stored.

FairPlay

Allows to specify FairPlay DRM specific license configuration features.

Required

No.

Default value

N/A.

Data type

FairPlay License Configuration object.

Supported values

Any valid FairPlay License Configuration object (see below).

The FairPlay License Configuration object consists of the following properties:

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.

Required

No.

Default value

false.

Data type

Boolean (for example: true).

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.

Required

No.

Default value

N/A.

Data type

Integer (for example: 300; represents seconds).

Supported values

From 1 to 4294967295.

PlayReady

Allows to specify PlayReady DRM specific license configuration features.

Required

No.

Default value

N/A.

Data type

PlayReady License Configuration object.

Supported values

Any valid PlayReady License Configuration object (see below).

The PlayReady License Configuration object consists of the following properties:

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.

Required

No.

Default value

false.

Data type

Boolean (for example: true).

Supported values

  • false - the playback continues after the license expires.

  • true - the 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.

Required

No.

Default value

N/A.

Data type

Integer (for example: 300; represents seconds).

Supported values

From 1 to 4294967295.

custom_data

Allows to specify the custom data of the license response.

Required

No.

Default value

N/A (no custom data is added to the license response).

Data type

String (for example: "This is an example.").

Supported values

Any string.

Widevine

Allows to specify Widevine DRM specific license configuration features.

Required

No.

Default value

N/A.

Data type

Widevine License Configuration object.

Supported values

Any valid Widevine License Configuration object (see below).

The Widevine License Configuration object consists of the following properties:

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.

Required

No.

Default value

N/A.

Data type

Integer (for example: 300; represents seconds).

Supported values

From 1 to 4294967295.

Content Keys Source (content_keys_source)

Allows to specify a content keys source. 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.

Default value

N/A.

Data type

Content Keys Source object.

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

No*.

Default value

N/A.

Data type

Array of Content Key objects.

Supported values

Any array of valid Content Key objects (see below).

*If inline content keys source is not specified, another content keys source must be used. Exactly one content keys source is required.

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.

Default value

N/A.

Data type

String (for example: "03AD7975-2DF6-4573-874F-D9E219CB7C23").

Supported values

Any valid GUID 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.

Required

No.

Default value

N/A.

Data type

String (for example: "73FEA67A-4A4A-409D-9ECD-B01FE6CB237B").

Supported values

Any valid GUID 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.

Required

No.

Default value

N/A.

Data type

String (for example: "HYDILKxZnPF0KizuWT0hww==").

Supported values

Any string representing Base64 encoded 16-byte binary data.

iv

Specifies the initialization vector (IV; exactly 16 bytes), encoded as Base64, that shall be used for the decryption of media together with the provided or generated content key. Only used by FairPlay DRM; ignored otherwise.

Required

No*.

Default value

N/A.

Data type

String (for example: "6oDIr6xZnPF0KizuWT0s1g==").

Supported values

Any string representing Base64 encoded 16-byte binary data.

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

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.

Required

No.

Default value

N/A.

Data type

String (for example: "Policy A").

Supported values

Any non-empty string.

License Request (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. 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

No*.

Default value

N/A.

Data type

License Request Content Keys Source object.

Supported values

Any valid License Request Content Keys Source object (see below).

*If the license request content keys source is not specified, another content keys source must be used. Exactly one content keys source is required.

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.

Required

No.

Default value

N/A.

Data type

String (for example: "63E79796-E94F-4739-BDA8-771F9EDA4547").

Supported values

Any string that represents a valid GUID 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.

Required

No.

Default value

N/A.

Data type

String (for example: "Policy A").

Supported values

Any non-empty string.

Content Key Usage Policies (content_key_usage_policies)

Allows to specify a list of content key usage policies – rules that can be applied individually to each content key. 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",

        "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=="
                }
            ]
        }
    }
]

Required

No.

Default value

N/A.

Data type

Array of Content Key Usage Policy objects.

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.

Default value

N/A.

Data type

String (for example: "Policy A").

Supported values

Any non-empty string.

FairPlay

For FairPlay, there are currently no content key specific features available, because FairPlay licenses can only contain a single key.

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.

Required

No.

Default value

N/A.

Data type

Array of PlayReady Content Key Usage Policy objects.

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.

Required

No.

Default value

2000.

Data type

Integer (for example: 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.

Required

No.

Default value

0.

Data type

Integer (for example: 100).

Supported values

From 0 to 65535. See the PlayReady Compliance Rules for the list of valid values.

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.

Required

No.

Default value

0.

Data type

Integer (for example: 100).

Supported values

From 0 to 65535. See the PlayReady Compliance Rules for the list of valid values.

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.

Required

No.

Default value

0.

Data type

Integer (for example: 100).

Supported values

From 0 to 65535. See the PlayReady Compliance Rules for the list of valid values.

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.

Required

No.

Default value

0.

Data type

Integer (for example: 100).

Supported values

From 0 to 65535. See the PlayReady Compliance Rules for the list of valid values.

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.

Required

No.

Default value

0.

Data type

Integer (for example: 100).

Supported values

From 0 to 65535. See the PlayReady Compliance Rules for the list of valid values.

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.

Required

No.

Default value

0 (meaning that the source ID isn’t added to the license).

Data type

Integer (for example: 258).

Supported values

From 0 to 65535. See the PlayReady Compliance Rules for the list of valid values.

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.

Required

No.

Default value

N/A (meaning that no play enablers are added to the license).

Data type

Array of strings (for example: [ "7d9ae684-bd6a-4234-b1d5-910d1b4bed62", "81b6f874-7614-47b5-b79d-8193630ce358" ]).

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.

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.

Required

No.

Default value

N/A (meaning that no analog video output protections are added to the license).

Data type

Array of Output Protection objects (see the example for details).

Supported values

  • "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.

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.

Required

No.

Default value

N/A (meaning that no digital video output protections are added to the license).

Data type

Array of Output Protection objects (see the example for details).

Supported values

  • "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.

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.

Required

No.

Default value

N/A (meaning that no digital audio output protections are added to the license).

Data type

Array of Output Protection objects (see the example for details).

Supported values

  • "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.

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.

Required

No.

Default value

N/A.

Data type

Array of Widevine Content Key Usage Policy objects.

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 security level that the device must have in order to use the license. If the device doesn’t meet the security requirements, playback is not allowed.

Required

No.

Default value

"SW_SECURE_CRYPTO".

Data type

String (for example: "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.

Required

No.

Default value

N/A (meaning that CGMS-A isn’t used).

Data type

String (for example: "once").

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.

Required

No.

Default value

N/A (meaning that HDCP is not required for the playback).

Data type

String (for example: "2.1").

Supported values

  • 1.0

  • 2.0

  • 2.1

  • 2.2

  • NO_DIGITAL_OUTPUT

disable_analog_output

Allows to specify whether analog output shall be disallowed.

Required

No.

Default value

false.

Data type

Boolean (for example: true).

Supported values

  • false - analog output is allowed.

  • true - analog output is not allowed.

License Service Configuration (license_server)

The License Service Configuration 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":
        {
            "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.

Required

No.

Default value

false.

Data type

Boolean (for example: true).

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.

Required

No.

Default value

N/A.

Data type

Access Control object.

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.

Required

No.

Default value

N/A.

Data type

Array of strings (for example: ["10.11.12.13", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]).

Supported values

Any array of strings, each of which represents an IP address in IPv4 or IPv6 format.

fairplay

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

Required

No.

Default value

N/A.

Data type

FairPlay Access Control object.

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.

Required

No.

Default value

N/A.

Data type

Array of strings (for example: ["dd5f6907-f579-45e0-8b49-632a49d4fe55", "ded51696-dd59-464c-9890-5b6db5e673c3"]).

Supported values

Any array of strings, each of which represents a GUID.

playready

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

Required

No.

Default value

N/A.

Data type

PlayReady Access Control object.

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.

Required

No.

Default value

N/A.

Data type

Array of strings (for example: ["ed85e2bc-63d8-4a26-8ad0-18c382c12dd9", "0d268a04-ca6e-4e9e-8412-e05344817cf5"]).

Supported values

Any array of strings, each of which represents a GUID.

widevine

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

Required

No.

Default value

N/A.

Data type

Widevine Access Control object.

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.

Required

No.

Default value

N/A.

Data type

Array of strings (for example: ["29a622dd-ef79-4f8f-92be-96175a3e145d", "5a164b33-63fc-4ac6-a7db-b304f897e08f"] ).

Supported values

Any array of strings, each of which represents a GUID.

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.

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

Required

No.

Default value

N/A.

Data type

Array of strings (for example: ["fbdcdcaf-af84-4bf3-8dbf-3e7c47922c65", "5a0f8872-4c83-4362-a6b5-03228a4547ce"] ).

Supported values

Any array of strings, each of which represents a GUID.

Session (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"
}

Required

No.

Default value

N/A.

Data type

Session object.

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.

Required

No.

Default value

N/A (no user_id is logged).

Data type

String.

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