AMS License Configuration Mapping
Preword
The aim of this guide is to assist Azure Media Services (AMS) DRM users in mapping the license configurations to Axinom DRM and also to provide further general guidance for a successful migration. It is intended to be used in conjunction with Portal DRM documentation, particularly with the following:
-
Entitlement Message (EM) documentation - explains existing license configuration settings in more detail, including the supported values and defaults.
|
Note
|
There will be upcoming changes that can streamline mapping AMS settings. These will be denoted by "*" and are currently not covered by the EM documentation. |
-
License Request Info Message documentation - the purpose of some AMS and Axinom settings is to share information about the devices requesting licenses, to be acted upon by custom proxy logic. Such as the "parse_only" setting for AMS Widevine. In case of Axinom, such feature can be activated globally in order to return the most relevant information, such as device identifier, via the License Request Info message (header). In upcoming releases we’ll also be including: session identifiers, request types (new / renewal, etc), session identifiers, and more.
General guidance
Content key management and policy attachment
Different DRM vendors offer different ways to specify which content keys should be returned in a license, how the key data obtained and how to attach DRM policies to them.
DRMs fundamentally reference keys via their GUID Key IDs (KIDs), which is also the approach that Axinom uses in the Entitlement Message. In contrast with AMS, Axinom does not store content metadata, such as Content IDs and track labels, which can be internally mapped to the specific Key IDs. It is assumed the integrator has access to the existing content key and metadata information via AMS APIs and can extract it and perform the relevant mappings to Key IDs.
For a general overview of content key management, please see: License Service documentation.
-
With more technical details being available here.
-
Note: in addition the Direct Key and Key Seed models, we also now support the Stored Keys model, where keys are retrieved Key Service database. This mode is not yet publicly documented.
For policy attachments, please see the EM documentation:
-
General policies (affect all keys)
Returning requested keys vs bulk keys
Axinom by default operates in the mode where only the content keys explicitly requested by the player (via Key IDs in the PlayReady or Widevine PSSH boxes or in the Asset ID of FairPlay requests) is returned in a license. This is the original DASH-IF recommended and transparency-promoting way of operation. And this case, the keys listed in the Axinom DRM Entitlement Message are purely for "entitlement" purposes - i.e. for key selection purpose the EM is purely used to validate if a particular key requested by the player is allowed to be returned.
However, in some situations, it can be preferable that in addition to or instead of the player-requested keys, all the keys listed in the Entitlement Message are returned. Such cases usually are:
Player limitations
-
For example, when persisting multi-key content using Widevine and ExoPlayer or an ExoPlayer based player, the player for technical reasons requires all the keys for the content to be returned in one license.
-
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 ,then the Widevine license service denies the license. For example: a HD track key requiring L1 security level is requested by L3 security level device). However, several plays, instead of skipping playing that track, then instead consider it a general error and fail all playback.
The solution then is to also return 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.
This can be achieved by setting the "license.widevine.include_all_entitled_keys" setting in the EM to "true". Then, all the keys listed in the EM will be returned ( details).
DRMs that use non-standardized workflows
For example, when using 3rd party content with FairPlay. In FairPlay case the is not 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.
This can be solved by instructing Axinom FairPlay license services to ignore the content key info (Asset ID) in the license request and instead return keys purely based on the Key ID list in the EM.
For this, set the "license.fairplay.ignose_keys_in_license_request" setting in the EM to "true"( details).
Widevine Mappings
-
The list of AMS Widevine settings is based on: Media Services v3 Widevine license template overview
-
Unless specified, both the data type and defaults used by Axinom match those used by AMS and the settings can be carried over as-is.
-
Settings marked with "*" mean they will be introduced in the upcoming Widevine API version.
JSON message
| AMS setting | Axinom setting | Notes |
|---|---|---|
payload |
N/A |
Axinom licenses services expect license request data to be in the HTTP request body. In Widevine case, it is expected to be in binary format. Therefore the payload value needs to be base64-decoded into binary and the result set as the HTTP request body. |
content_id |
N/A |
See Content key management and policy attachment section. |
provider |
N/A |
Axinom license services identify user accounts via the Communication Key ID. See more under License Service Message |
policy_name |
N/A |
Axinom does not support stored policies. Policies are provided via the Entitlement Message. |
allowed_track_types |
N/A |
See Content key management and policy attachment section. |
content_key_specs |
Supported |
See the Content key specs section below. |
use_policy_overrides_exclusively |
N/A |
All policies are specified per-request via the Entitlement Message. |
policy_overrides |
Supported |
See Policy overrides section below. |
session_init |
Partially supported |
See "Session initialization" section below. |
parse_only |
Partially supported |
Content key specs
| AMS setting | Axinom setting | Notes |
|---|---|---|
track_type |
No direct mapping |
See Content key management and policy attachment section on how to achieve the equivalent behaviour. |
security_level |
content_key_usage_policies.widevine.device_security_level |
AMS uses integer values; Axinom uses string values. Map these as follows:
If no value provided by AMS, omit value for Axinom as well (results in the default value). |
required_output_protection.hdcp |
content_key_usage_policies.widevine.hdcp |
Note: AMS doc says the field is called “output_protection.hdc“, with missing “p” in the end. Perhaps a mistake in the doc? The allowed string values are different, to be mapped as follows:
Note: Axinom supports further values (see the EM doc). |
key |
content_keys_source.inline[n].encrypted_key |
Note: The content key must be additionally encrypted. More about this and other key provisioning methods, please see under License Service |
key_id |
content_keys_source.inline[n].id |
For Axinom, the value must be in the GUID string format. So a base64 → GUID string conversion is needed. For example:
|
Policy overrides
| AMS setting | Axinom setting | Notes |
|---|---|---|
can_play |
license.widevine.allow_playback* |
Note: Axinom defaults to “true”. Hence this can be omitted, if “true”. |
can_persist |
license.allow_persistence OR license.widevine.allow_persistence* |
|
can_renew |
license.widevine.allow_renewal* |
Note: Axinom doesn’t allow any other renewal settings to be set if renewal is not allowed. |
license_duration_seconds |
Axinom doesn’t allow negative values. Note: this setting is deprecated by Widevine. It is recommended to use a combination of rental and playback duration, together with the more modern native “hard” and “soft” enforcement flags, to achieve the desired behaviour. Note that these flags will be released in an upcoming Widevine API version. The flags will be:
|
|
rental_duration_seconds |
license.widevine.rental_duration* |
Axinom doesn’t allow negative values. |
playback_duration_seconds |
license.widevine.playback_duration |
Axinom currently uses “uint32” data type for it, while AMS uses “int64”. In the next version we’ll change to “int64” as well to provide a matching value range. However, negative values will not be allowed. |
renewal_server_url |
license.widevine.renewal_url* |
Axinom doesn’t allow setting it if renewal is not allowed (must be omitted from JSON or explicitly null). Note: this value will have no effect for Axinom server-side as the same license service instances can handle both new and renewal license requests. If set, ensure players send renewals to valid licensing endpoints. This logic is controlled by the players. |
renewal_delay_seconds |
license.widevine.renewal_delay* |
Must be omitted or “null” if renewal is not allowed. Axinom default: 300 Axinom minimum: 180*
Contact Axinom if a lower minimum values is desired. |
renewal_retry_interval_seconds |
license.widevine.renewal_retry_interval* |
Must be omitted or “null” if renewal is not allowed. Axinom default: 10 Axinom minimum: 3*
|
renewal_recovery_duration_seconds |
license.widevine.renewal_recovery* |
Must be omitted or “null” if renewal is not allowed. Axinom default: 60 |
renew_with_usage |
license.widevine.renew_with_usage |
Session initialization
All settings here are handled internally by Axinom DRM. If there is a usage case of setting any of them explicitly, please contact us.
| AMS setting | Axinom setting | Notes |
|---|---|---|
provider_session_token |
not supported |
Note: “session_id”-s, suitable for session-management are supported and are set internally. These will be exposed in the License Request Info Message in an upcoming release. |
provider_client_token |
not exposed - handled internally |
Automatically set internally to a random GUID string, unless it is already set to a valid GUID string. Note: When returning the “License Request Info” message is enabled, this value will be returned in that message (if the client platform supports client tokens) and can be used for device management. See License Request Info Message. |
override_provider_client_token |
not exposed - handled internally |
Automatically overridden, unless already set to a valid GUID string. |
FairPlay Mappings
Based on Axinom research, AMS seems to have a very limited set of license configurations options. Most notably, missing were:
-
Duration settings for controlling online streaming (non-persistent) playback.
-
In Axinom case, if persistence is disallowed (default), then the license duration and real time expiration settings control the online playback.
-
According to AMS doc all duration settings seemed to be related only to the offline case, and there was no hint of "leaseDuration", which in Axinom terms means "real_time_expiration".
-
-
HDCP settings
|
Note
|
in the upcoming release Axinom will also provide DRM-enforced options to prevent playback via AirPlay or Digital AV Adapters. |
FairPlay certificate settings
AMS settings:
-
ask
-
fairPlayPfx
-
fairPlayPfxPassword
In Axinom case, these settings, also called the FairPlay Data Sets or FairPlay Credentials, need to be provided just once in the License Service Tenant configuration in Axinom Portal. These are then synced to all FairPlay license services via our backend and do not need to be provided as part of license configuration.
License configuration settings
| AMS setting | Axinom setting | Notes |
|---|---|---|
rentalAndLeaseKeyType |
license.allow_persistence OR license.fairplay_allow_persistence* |
As far as we can tell the AMS supported KeyTypes are:
The only important factor for Axinom here is that the first three key types designate that a persistent license is required. Any other value could be considered as persistence should not be allowed. This means:
In Axinom case, a specific key type does not need to be specified as our backend automatically chooses the most appropriate key type to be used for the offline case. |
offlineRentalConfiguration.playbackDurationSeconds |
license.fairplay.playback_duration |
Should only be available when AMS rentalAndLeaseKeyType is “DualExpiry”. Since AMS type is “TimeSpan” and Axinom type is “uint”, conversion is needed. Axinom supported range is: 1 - 4294967295 (uint). If the AMS value is out of this range, please constrain to this range. Axinom does not allow 0. If the AMS value is effectively 0, omit Axinom value – this will default to 0. |
offlineRentalConfiguration.storageDurationSeconds |
license.duration OR license.fairplay.duration* |
Same “Notes” apply as for AMS “offlineRentalConfiguration.playbackDurationSeconds”. |
rentalDuration |
license.duration OR license.fairplay.duration* |
Should only be available when AMS rentalAndLeaseKeyType = “PersistentLimited”. Otherwise, same “Notes” apply as for AMS “offlineRentalConfiguration.playbackDurationSeconds” |
PlayReady Mappings
| AMS setting | Axinom setting | Notes |
|---|---|---|
beginDate |
license.start_datetime |
AMS value can be directly used. |
expirationDate |
license.expiration_datetime |
AMS value can be directly used. |
licenseType |
license.allow_persistence |
AMS uses string values; Axinom uses a boolean. Map these as follows:
|
securityLevel |
content_key_usage_policies.playready.min_device_security_level |
AMS uses string values; Axinom uses string values. Map these as follows:
|
contentType |
content_key_usage_policies.playready.source_id |
AMS uses string values; Axinom uses string values. Map these as follows:
|
firstPlayExpiration |
license.playready.playback_duration |
AMS uses timespan string values; Axinom uses integer values (in seconds). Map these as follows:
|
analogVideoOpl |
content_key_usage_policies.playready.analog_video_opl |
|
compressedDigitalAudioOpl |
content_key_usage_policies.playready.compressed_digital_audio_opl |
|
compressedDigitalVideoOpl |
content_key_usage_policies.playready.compressed_digital_video_opl |
|
uncompressedDigitalAudioOpl |
content_key_usage_policies.playready.uncompressed_digital_audio_opl |
|
uncompressedDigitalVideoOpl |
content_key_usage_policies.playready.uncompressed_digital_video_opl |
|
allowPassingVideoContentToUnknownOutput |
content_key_usage_policies.playready.play_enablers |
AMS uses string values; Axinom uses GUID string values. Map these as follows:
|
agcAndColorStripeRestriction |
content_key_usage_policies.playready.analog_video_output_protections |
AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows: Key (“id”) → ”C3FD11C6-F8B7-4D20-B008-1DB17D61F2DA” Values (“config_data“):
E.g: 00 → analog_video_output_protections = [ { “id“:”C3FD11C6-F8B7-4D20-B008-1DB17D61F2DA”, “config_data“: “AA==” } ] |
explicitAnalogTelevisionOutputRestriction.configurationData |
content_key_usage_policies.playready.analog_video_output_protections |
AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows: Key (“id”) → ”2098DE8D-7DDD-4BAB-96C6-32EBB6FABEA3” Values (“config_data“):
|
explicitAnalogTelevisionOutputRestriction.bestEffort |
content_key_usage_policies.playready.analog_video_output_protections |
AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows: Key (“id”) → ”225CD36F-F132-49EF-BA8C-C91EA28E4369” Values (“config_data“):
|
imageConstraintForAnalogComponentVideoRestriction |
content_key_usage_policies.playready.analog_video_output_protections |
AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows: Key (“id”) → ”811C5110-46C8-4C6E-8163-C0482A15D47E” Values (“config_data“):
|
imageConstraintForAnalogComputerMonitorRestriction |
content_key_usage_policies.playready.analog_video_output_protections |
AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows: Key (“id”) → ”D783A191-E083-4BAF-B2DA-E69F910B3772” Values (“config_data“):
|
digitalVideoOnlyContentRestriction |
content_key_usage_policies.playready.analog_video_output_protections |
AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows: Key (“id”) → ”760AE755-682A-41E0-B1B3-DCDF836A7306” Values (“config_data“):
|
scmsRestriction |
content_key_usage_policies.playready.digital_audio_output_protections |
AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows: Key (“id”) → ”6D5CFA59-C250-4426-930E-FAC72C8FCFA6” Values (“config_data“):
|
relativeExpirationDate |
license.duration |
AMS uses timespan string values; Axinom uses integer values (in seconds). Map these as follows: “00:01:10“ → 70 |
relativeBeginDate |
Not supported |
Same effect could be achieved in Axinom DRM by computing the absolute timestamp and set it in |
allowTestDevices |
Not supported |
Please contact Axinom for more information. |
gracePeriod |
Not supported and Deprecated |
This flag is only available in PlayReady older client versions below 3.0 and now deprecated. |
contentKeyLocation |
Not Applicable |
AMS allows two settings “ContentEncryptionKeyFromHeader” (default) and “ContentEncryptionKeyFromKeyIdentifier”. Axinom also get the key ID from the PSSH box (PlayReady Header) by default. However, if the key IDs are set in AMS content key policies, similar behaviour can be achieved in Axinom by use of stored content keys or encrypted content keys. For this key IDs/key must be known. Contact Axinom for more information. |
|
Note
|
In addition to the above-mentioned parameter mappings, Axinom supports more protection flags in PlayReady, for example, HDCP restrictions, content source IDs, etc. |