License Request Info Message
License Request Info Message is a JSON data structure
designed to hold information about a DRM License Request. License Request Info
Message is returned by Axinom DRM License Service as a
payload of a Axinom DRM License Service Message
inside a custom HTTP header X-AxDRM-Message if the
return_license_request_info field in the
Entitlement Message was set to true. Read
Device Specific Restriction
to understand how a License Request Info Message can be used.
Examples​
The following shows the structure of a License Request Info Message.
{
"version": 1,
"type": "widevine_license_request_info",
"device_info": {
"client_token": "b6dfac08-9ead-4842-aa99-4fabb6075c34",
"device_certificate_serial_number": "29a622dd-ef79-4f8f-92be-96175a3e145d",
"device_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1",
"recommended_client_id": "29a622dd-ef79-4f8f-92be-96175a3e145d",
"platform": "android",
}
"request_type": "new"
}
{
"version": 1,
"type": "fairplay_license_request_info",
"device_info": {
"device_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1",
"recommended_client_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1",
"supported_license_protocol_versions": [ "1", "2" ]
},
"license_protocol_version": "1",
"playback_state": "new_session",
"streaming_indicator": "requesting_device",
"session_id": "bb529255-ee30-4d2d-b5b2-879359c6aadd"
}
{
"version": 1,
"type": "playready_license_request_info",
"device_info": {
"device_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1",
"recommended_client_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1"
}
}
Structure​
The following fields are available in the License Request Info Message:
| Property | Required | Data Type | Supported Values | Description |
|---|---|---|---|---|
| version | Yes | Integer | 1 | Indicates the version of the License Request Info Message |
| type | Yes | String | "fairplay_license_request_info", "playready_license_request_info", "widevine_license_request_info" | Indicates the type of a License Request Info Message |
| device_info | No | JSON | Device Info object | Encapsulates information about a device requesting a License |
| device_info.device_id | No | String | Any string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format | Indicates the ID of a device that made a License Request. |
| device_info. recommended_client_id | No | String | Any string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format | Widevine API v6.21.0+, FairPlay API v6.20.0+, PlayReady API v6.20.0+ The recommended client identifier to use for device management. This field is intended to simplify choosing which client ID to use, as some DRMs may expose several with only specific ones being usable for certain clients. For FairPlay and PlayReady this will be the device_id. For Widevine, this will either be the client_token or the device_certificate_serial_number, chosen automatically by the license service based on the client information. Widevine specifics This will be set to the value of client_token in case the client has security level 3 and is one of "windows", "macos", "linux" or "chromeos". For such clients the device_ceritifcate_serial_number is not suitable for device identification as the ID can be constant for many users. NB! If the field is empty, it means that for the current platform "client ID" has to be used, but for some reason, it is not available. This should be treated as a warning that proper client identification may not be possible and that the playback application may need to be re-configured to properly support client tokens. NOTE: device_id will never be set as the recomended_client_id as the device ID is depreacted and it’s use is not recommended. Notify Axinom if you find a use-case where the device ID is still a valid and the only usable indicator. |
| device_info.client_token | No | String | Any string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format | Widevine only. Contains the client token, which the client is currently using, or in the absence of an existing token, a new token, which has been generated by the license service and sent to the client in the license. This token persists on the client between playback sessions and can be used to uniquely identify the client (e.g. desktop browser). If the client doesn’t support client tokens, this field is missing. |
| device_info. device_certificate_serial_number | No | String | Any string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format | Widevine only. Indicates the Widevine DRM device certificate serial number of the device that made the License Request. This is a GUID representation of the actual DRM client device certificate serial number. The serial number should be quite constant and unique in case of native players applications. L1 and L3 CDMs on a particular device likely to have different serial numbers. So if a player were to switch between them, the serial could change to the one or the other. In case of Android browsers the serial can additionally change when the browser app data is cleared or the browser is reinstalled. Browser cache clearing doesn’t seem to affect on Android. Also, on Android, different browser on the same device may have different serials. |
| device_info. platform | No | String | As of May 2023, the possible values are: "chromecast", "fuchsia", "ios", "ipados", "tvos", "android", "windows", "chromeos", "macos", "linux", "webos", "tizen", "fireos", "roku", "playstation", "xbox", "kaios", "rdk", "other", "PLATFORM_UNSPECIFIED" and null. | Widevine API v6.21.0+ Reports the client device "platform". This can be used by a proxy to implement custom platform-specific behaviour. If this field is missing from a particular info message, please report to Axinom - this means there is a new platform that we don’t yet know about. |
| device_info. supported_license_protocol_versions | Yes | Array of strings | Any array of strings. For example: ["1", "2"] | FairPlay API v6.20.0+ Indicates which FairPlay Streaming protocol versions the playback device supports. Note: while some clients are known to indicate support for several versions, the only version publicly documented by Apple, and therefore used by Axinom DRM, is "1". |
| session_id | No | String | Any string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format | Widevine API v6.24.0+, FairPlay API v6.20.0+ The ID of the current playback session. This ID will be constant for all related requests. For example: license renewals (FairPlay, Widevine) and releases (Widevine). This can be used, for example, for session tracking and implementing session-based concurrent playback limiting. |
| request_type | No | String | One of: "new", "renewal", "release" | Widevine API v6.21.0+ The type of the license request. Knowing this may enable taking advanced action by a license proxy. "new" means this is a request for a new license, with a new session ID. "renewal" means this is a renewal request for an existing license. "release" means this is a request for releasing a persisted license. |
| playback_state | No | String | "new_session", "license_renewal_with_valid_content_key_required", "license_renewal_required", "session_stopped" | FairPlay API v6.20.0+ Indicates the state of the playback when the license request was created. This essentially represents the request type. This is supported on iOS 9+ and modern Safari. * "new_session" - a new playback session has been opened and the device requires a license to start playback. * "license_renewal_with_valid_content_key_required" - device is playing media, but requires a renewed license that contains a valid content key. * "license_renewal_required" - device is playing media, but requires a renewed license (valid content key is not required). * "session_stopped" - playback session is halted due to an error state or a lack of session ID. |
| streaming_indicator | Yes | String | "requesting_device", "airplay", "av_adapter" | FairPlay API v6.20.0+ Indicates whether the playback occurs on the requesting device or content is streamed to an external device: * "requesting_device" - playback occurs on the device that sends the license request. * "airplay" - device streams content over AirPlay to Apple TV for playback. * "av_adapter" - device streams content to an Apple digital AV adapter for playback. |
| license_protocol_version | Yes | String | Any string. For example: "1". | FairPlay API v6.20.0+ Indicates the version of the FairPlay Streaming protocol that is used for the current transaction. This is chosen by the playback device as the most recent version that both the playback device and the license service support, where the version supported by the license service is determined by the "KEYFORMATVERSIONS" parameter in the HLS playlist. Note: while some clients are known to indicate support for several versions, the only version publicly documented by Apple, and therefore used by Axinom DRM, is "1". |
In case of PlayReady and FairPlay, the device ID is always obtainable. However, in
case of Widevine, this is not always possible.
On some devices and platforms, for example, Google Chrome on desktop devices,
Widevine is not able to uniquely identify the device
– in such a case, the device_id field is missing in the License Request Info
Message.
Furthermore, device_id is now deprecated for Widevine. Newer Widevine clients
no longer report the device ID.
Therefore, use allowed_device_certificate_serial_numbers for Widevine instead.
The recommended way of executing device ID based restrictions is to use Axinom DRM License Service in the Proxy Mode. Proxy Mode is strongly advised to obtain License Request Info. In the Proxy Mode, the device ID based restriction decisions can be made upon receiving the License Request Info Message along with the license response - if device ID in the received License Request Info Message does not match the expected one, the License Proxy may decide not to return the license to the client.
Deprecated Version​
License Request Info Message is used with an Entitlement Message v2 and above. Previously, for the Entitlement Message v1, a data structure called Client Info Message was used.
Revision History​
The table below lists the document versions and any changes to them.
|
Version |
Date |
Description |
|---|---|---|
|
1 |
April 29, 2019 |
Initial Revision |
|
2 |
September 17, 2020 |
Added |
|
3 |
October 14, 2020 |
Changed the |
|
4 |
February 23, 2022 |
Restructured |
|
5 |
September 01, 2023 |
|
|
6 |
April 02, 2024 |
Replaced "vNext" version information with real versions. |