License Configuration

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

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,

    "concurrency_interval": 300,
    "concurrency_grace_period": 60,

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

concurrency_interval

Specifies the interval, in seconds, at which license renewal should occur when using Concurrent Stream Limiting (CSL). Has no effect when CSL is disabled.

Note:

• For FairPlay and PlayReady, this only affects the license duration calculation (duration = interval + grace period). Renewal for these DRMs can only be triggered by out-of-band player side logic. The same interval value specified here, should also be utilized on the player side.
• Widevine CDMs utilize this setting natively and automatically issue a renewal request at each interval.

See the CSL guide for more information.

Default	300
Supported values	60 - 600
Availability	Axinom DRM FairPlay API 6.23.0+, Widevine API 6.28.0+, PlayReady API 6.22.0+

concurrency_grace_period

Specifies the duration, in seconds, for how long the playback can still proceed after triggering a license renewal, but before the license is successfully renewed. Has no effect when CSL is disabled.

This, together with concurrency_interval, effectively determines the duration playback can occur if the license is not renewed.

See the CSL guide for more information.

Default	60
Supported values	1 - 120
Availability	Axinom DRM FairPlay API 6.23.0+, Widevine API 6.28.0+, PlayReady API 6.22.0+

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+