Entitlement Message Version 1

warning

This document describes the deprecated version of the entitlement message format (v1). For the latest version (v2) read Entitlement Message v2.

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.

warning

Some DRM clients may not understand certain license configurations, thinking that a license is invalid. This doesn’t mean that the license was incorrectly generated by the licensing service. If the license is incorrectly configured, the licensing service returns an error. If the licensing service successfully returns the license, but the DRM client is not able to use it, it’s only the DRM client’s fault.

Root Structure

The following is the structure of an Entitlement Message.

{
    "type": "entitlement_message",

    "client_ip": "127.0.0.1",

    "return_client_info": true,

    "persistent": false,

    "begin_date": "2015-08-18T15:22:40+03:00",
    "expiration_date": "2015-09-18T12:22:40+00:00",

    "first_play_expiration": 300,

    "keys_based_on_request": false,

    "keys": [
        {
            "id": "c816b99c-66c9-a755-b899-9e78f3ec151a",
            "encrypted_key": "QmfHgvFfRne5ckn3jsy0nA=="
        },
        {
            "id": "4267c782-f15f-4677-b972-49f78eccb49c"
        },
        {
            "id": "83a7d6a5-d8fe-4b39-8683-6613f2f059c7",
            "key_seed_id": "e8c0b553-4d82-46cb-93a2-ea41ad8bd4f7"
        },
        {
            "id": "9e86d6e6-da0e-4606-9d0d-719f2641a949",
            "iv": "1cnkPtwRkSo8uhFasL2D1g=="
        }
    ],

    "fairplay": {
        "device_id": "6d639d02-03d6-4e55-8e76-3140ed2687f5",

        "real_time_expiration": true
    },

    "playready": {
        "min_app_security_level": 2000,

        "device_id": "24fb8698-1556-4fc7-90d5-930ccec07c10",

        "real_time_expiration": true,

        "custom_data": "Sample custom data.",

        "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=="
            },
            {
                "id": "<value>",
                "config_data": "+2j0if7TR/2nvWHJuQUsCA=="
            }
        ],

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

    "widevine": {
        "device_id": "a467ea98-d201-4d7b-8fb3-eac0e46ed907",

        "cgms-a": "once",
        "hdcp": "2.1",

        "device_security_level": 1
    }
}

Common Features

The following features are present in all supported DRMs and they work in a similar way.

begin_date

The license begin date is the date when the license becomes active. The playback works only when the license is active. In the case of FairPlay, this value isn’t used in license configuration. FairPlay licenses always become active immediately after generation.

Required	No.
Default value	Absent, the license becomes active right after being generated.
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).

client_ip

The IP address of the device that is allowed to acquire the license. If the specified IP address doesn’t match the IP address of the license request, the licensing service rejects such a request.

Required	No.
Default value	Absent, which means that any IP address is able to acquire the license.
Data type	String (for example: "10.0.4.25").
Supported values	Any string that represents the valid IPv4 or IPv6 address.

expiration_date

The license expiration date is the date after which the license is no longer active. In case of Widevine, the playback stops when the license expires. In case of PlayReady and FairPlay, the playback doesn’t stop, unless the real-time expiration feature is used.

note

In FairPlay, the expiration date is supported only on iOS 9 onwards; in other cases, this feature is ignored.

Required	No.
Default value	Absent, the license never expires (unless other policies limit its duration).
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).

first_play_expiration

Allows to specify for how long the playback is allowed after it has been started for the first time. After the playback exceeds the specified number of seconds, the playback stops. In case of FairPlay, this feature is ignored.

Required	No.
Default value	Absent, the license never expires after it has been started for the first time (unless other policies limit its duration).
Data type	An integer that represents the number of seconds (for example: 300).
Supported values	Any integer from 1 to 4294967295 (unsigned 32-bit integer).

keys

Allows to specify the content keys that can be included in the license response. Whether the content key is included into the license response or not, depends on key IDs in the license request. Only content keys with matching key IDs are included.

Required	No.
Default value	Absent, no content keys can be included into the license response (unless the keys_based_on_request feature is used).
Data type	Array of Content Key objects.
Supported values	Any array of valid Content Key objects.

The Content Key object consists of the following properties:

Property	Required	Description
encrypted_key	No.	The content key itself (exactly 16 bytes), encrypted using the Advanced Encryption Standard (AES), using the https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Cipher_Block_Chaining_.28CBC.29[Cipher Block Chaining (CBC)] mode, without padding, and encoded using the Base64 encoding, which conforms to RFC 4846. The communication key must be used as the encryption key, and the key ID must be used as the initialization vector (IV). When the key ID is used as the IV, the order of the bytes must be big-endian. In other words, if the string representation of the key ID is "1E0DE660-B47E-4C79-B5CE-EDBD72BB17B3", its byte representation when used as the IV must be "0x1E0DE660B47E4C79B5CEEDBD72BB17B3". If not specified, a content key is generated based on the key ID and the default key seed of your tenant.
id	Yes.	The identifier of a content key (also known as "key ID" or "KID"). It can be any valid GUID in the 00000000-0000-0000-0000-000000000000 format, except the empty GUID (all zeroes).
key_seed_id	No.	The identifier of a key seed that must be used to generate a content key. It can be any valid GUID in the 00000000-0000-0000-0000-000000000000 format. If not specified, the default key seed of your tenant is used.
iv	No.*	The initialization vector (IV; exactly 16 bytes) to be used for the decryption of media together with the provided or generated content key. Only used by FairPlay DRM, other DRM-s ignore it. Note that, in case of FairPlay, this property is required, unless the key IV is provided in the asset ID of the license request; also, the IV in the entitlement message takes precedence over the IV in the license request, in case both are provided.

The key_seed_id and the encrypted_key properties are mutually exclusive, which means that they must not be used together at the same time.

keys_based_on_request

Allows to specify whether keys must be generated based on information from a license request. If this feature is enabled, the keys must not be specified in the entitlement message. In the case of FairPlay, this feature is allowed only when the key IV is provided in the asset ID of the license request.

warning

Use this feature at your own risk, because it exposes a security issue related to the fact that keys are generated for any media. It’s highly recommended to avoid using this feature. If you still want to use it, make sure that you completely understand the risk you’re taking.

Required	No.
Default value	false
Data type	Boolean (for example: true)
Supported values	* false - keys are generated based on the information provided in the entitlement message. * true - keys are generated based on the information provided in the license request.

persistent

Allows to specify whether the license must be persistent or not. Depending on a DRM system, this feature may work differently:

• PlayReady: there’s a guarantee that if the license is persistent, it is stored on the client’s device.
• Widevine: there’s no guarantee that if the license is persistent, it is stored on the client’s device. It’s up to the device whether the license is stored or not.
• FairPlay: there’s no guarantee that if the license is persistent, then it is stored on the client’s device. It’s up to the device whether the license is stored or not.

Additionally, PlayReady has the following limitations:

• The license response can contain only one non-persistent license.

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 setting and is active until the playback is stopped.
• Persistent licenses don’t support and ignore the 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. Always requires an internet connection. * true - the license is persistent. It is stored on the client’s device, in the local license store. An internet connection is not needed if the license is already in the license store.

return_client_info

Allows to specify whether the client info (additional information about a DRM client) must be returned together with the license response.

Required	No.
Default value	false
Data type	Boolean (for example: true)
Supported values	* false - client info must not be returned. * true - client info must be returned.

DRM-Specific Features

These are the features that are unique for a specific DRM technology, such as FairPlay, PlayReady, and Widevine.

FairPlay

device_id

The ID of the device that is allowed to acquire the license. If the specified device’s ID doesn’t match the ID of the device that requested the license, the licensing service rejects such license request.

Required	No.
Default value	Absent, any device can acquire the license.
Data type	String (for example: "78471be8-2696-47c4-b065-6a3e154ae221").
Supported values	Any valid GUID in the 00000000-0000-0000-0000-000000000000 format.

real_time_expiration

Allows to specify whether the license must expire in real time, during the playback. Note that this feature is only supported starting from iOS 9. In other cases, it is ignored.

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 immediately after the license expires.

PlayReady

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

Required	No.
Default value	0
Data type	Integer (for example: 100).
Supported values	From 0 to 65535. See the PlayReady Compliance Rules for valid values.

analog_video_output_protections

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

Required	No.
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 the 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

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

Required	No.
Default value	0
Data type	Integer (for example: 100).
Supported values	From 0 to 65535. See the PlayReady Compliance Rules for 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 back 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 valid values.

custom_data

Allows to specify the custom data of the license response.

Required	No.
Default value	Absent, no custom data is added to the license response.
Data type	String (for example: "This is an example.")
Supported values	Any string.

device_id

The ID of the device that is allowed to acquire the license. If the specified device ID doesn’t match the ID of the device that requested the license, the licensing service rejects such a license request.

Required	No.
Default value	Absent, any device can acquire the license.
Data type	String (for example: "3ebb4aad-8ff4-42f4-a808-66c6b3f5d4bc").
Supported values	Any valid GUID in the 00000000-0000-0000-0000-000000000000 format.

digital_audio_output_protections

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

Required	No.
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 the 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

digital_video_output_protections

Allows to specify output protections that are allowed to play protected digital video content. For example, HDCP. This feature may not be supported by clients that don’t support PlayReady 3 features.

Required	No.
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 the 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

min_app_security_level

Allows to specify the minimum application security level that the application must have to use the license. If the security level of the application is lower than the specified one, the license is not issued.

Required	No.
Default value	2000
Data type	Integer (for example: 2000)
Supported values	* 50 - software-based security, which is the least secure and intended for testing purposes only. * 2000 - software-based security, which is secure and intended for production purposes. * 3000 - hardware-based security, which is the most secure and intended for production purposes.

play_enablers

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

Required	No.
Default value	Absent, no play enablers are added to a license. This may be a problem if the output is unknown (for example, the playback is attempted in a virtual machine). To enable playback to the unknown output, the "786627D8-C2A6-44BE-8F88-08AE255B01A7" play enabler must be used. See the PlayReady Compliance Rules (section 3.9.1.) for details.
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. The GUID represents the technology ID. See the PlayReady Compliance Rules for valid values.

Some frequently used values for play_enablers:

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

real_time_expiration

Allows to specify whether the license must expire in real time, during the playback.

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 immediately after the license expires.

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, the source ID isn’t added to the license.
Data type	Integer (for example: 258).
Supported values	See the PlayReady Compliance Rules for a list of valid values.

Some frequently used values for source_id:

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

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

Required	No.
Default value	0
Data type	Integer (for example: 100).
Supported values	From 0 to 65535. See the PlayReady Compliance Rules for 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 back.

Required	No.
Default value	0.
Data type	Integer (for example: 100).
Supported values	From 0 to 65535. See the PlayReady Compliance Rules for valid values.

Widevine

cgms-a

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

Required	No.
Default value	Absent, CGMS-A isn’t used.
Data type	String (for example: "once").
Supported values	* free - an unlimited amount of copies can be made. * once - only one generation of copies can be made. * never - no copying permitted.

device_id

The ID of the device that is allowed to acquire the license. If the specified device ID doesn’t match the ID of the device that requested the license, the licensing service rejects such a license request.

Required	No.
Default value	Absent, any device can acquire the license.
Data type	String (for example: "2d4e7258-e152-47d8-8d17-fc920e56ce50").
Supported values	Any valid GUID in the 00000000-0000-0000-0000-000000000000 format.

hdcp

Allows to specify the version of HDCP that must be used to play protected media. The playback doesn’t work if the specified version of HDCP is not supported by the device.

Required	No.
Default value	Absent, HDCP is not required for playback.
Data type	String (for example: "2.1").
Supported values	1.0, 2.0, 2.1, 2.2.

device_security_level

Allows to specify the minimum security level that the device must have to acquire the license. If the device doesn’t meet the security requirements, the playback doesn’t work.

Required	No.
Default value	1
Data type	Integer (for example: 2).
Supported values	* 1 - software-based whitebox crypto is required. * 2 - software crypto and an obfuscated decoder are required. * 3 - the key material and crypto operations must be performed within a hardware backed trusted execution environment. * 4 - the crypto and decoding of content must be performed within a hardware backed trusted execution environment. * 5 - the crypto, decoding and all handling of the media (compressed and uncompressed) must be handled within a hardware backed trusted execution environment.

Using the Features

There are certain rules for how to use specific features. By ignoring such rules, it’s possible to generate a license that is not usable by a specific DRM client. It’s highly recommended to consider these rules while creating entitlement messages.

PlayReady

There are multiple versions of PlayReady DRM clients. Older versions may not support features that were added to newer versions.

All DRM Clients

The DRM client’s security level must be greater than or equal to the minimum application security level that is required by the entitlement message.

PlayReady 3 Clients

The real-time expiration feature cannot be used on its own. It must be used together with the expiration date feature, or together with the first play expiration feature.

PlayReady 2 and Older Clients

• The maximum application security level is 2000.
• The real-time expiration feature is not supported.
• The digital video output protections are not supported.
• Multiple non-persistent licenses in one license response are not supported. When the non-persistent license is requested by the entitlement message, there must be only one key in the entitlement message.
• Non-persistent licenses with the expiration date or the first play expiration are not supported.