Skip to main content

Axinom DRM License Service Message

Axinom DRM License Service Message is a JSON data structure designed to deliver data to and from the Axinom DRM License Service. Axinom DRM License Service Message is used to encapsulate inner messages defined in the context of Axinom DRM, such as Entitlement Message and License Request Info Message. An Axinom DRM License Service Message is packaged into a signed JSON Web Token (JWT) before delivery.

Example of an Axinom DRM License Service Message
{
    "version" : 1,
    "id": "c76d9f99-dd53-46a0-8aa0-1dc8a931202d",
    "begin_date": "2015-08-18T15:22:40+03:00",
    "expiration_date": "2015-08-18T15:22:40+03:00",
    "com_key_id" : "cc36e85d-2fdf-462c-b395-030907447afc",
    "message" : {ENTITLEMENT MESSAGE V2}
}

Signing JWT​

Axinom DRM License Service Message is delivered to the License Service as a digitally signed JWT. This JWT is provided by an Entitlement Service to the Client and is then sent by the Client to the License Service. The client must not be able to tamper the JWT on the way. For this, the Entitlement Service shall sign the JWT in cryptographically secure way.

  • Signing algorithm: HMAC-SHA256
  • Signing key: Communication Key (provided as a part of Axinom DRM configuration data). Communication Key is a shared secret between the Entitlement Service and the License Service.

Multiple communication keys are supported by Axinom DRM for a single tenant. Hence the The ID of the Communication Key (Communication Key ID) used for signing shall be included in the message itself (com_key_id).

Finally, the token is encoded with base64.

See: How to sign a License Service Message - samples in different programming languages.

Delivering JWT​

An Axinom DRM License Service Message shall be delivered to Axinom DRM License Service in exactly one of the following ways:

  • HTTP header X-AxDRM-Message
  • HTTP query string parameter AxDrmMessage
  • The Custom Data part of a PlayReady License Request (PlayReady only).

See License Acquisition API for further details.

An Axinom DRM License Service Message delivered from Axinom DRM License Service is always in the X-AxDRM-Message HTTP header.

Axinom DRM License Service Message Structure​

The following is the structure of Axinom DRM License Service Message.

The structure of an Axinom DRM License Service Message
{
    "version" : 1,
    "id": "c76d9f99-dd53-46a0-8aa0-1dc8a931202d",
    "begin_date": "2015-08-18T15:22:40+03:00",
    "expiration_date": "2015-08-18T15:22:40+03:00",
    "com_key_id" : "cc36e85d-2fdf-462c-b395-030907447afc",
    "message" : {ENTITLEMENT MESSAGE}
}
PropertyRequiredData TypeSupported valuesDescription
versionYesIntegerOnly the value 1The version of an Axinom DRM License Service Message schema
idNoStringAny non-empty and non-whitespace string. For example: "123" or "c76d9f99-dd53-46a0-8aa0-1dc8a931202d" (a GUID string). Default - none.Identifier of a License Service Message, can be used as a CorrelationID, for example, to enable easier troubleshooting by making the messages uniquely identifiable. The id, if specified, will be logged by the License Services. The feature is available in Axinom DRM FairPlay API v6.15.0+, PlayReady API 6.17.0+, Widevine API 6.16.0+
begin_dateNoStringAny string that represents a combined date and time value in the ISO 8601 format (time zones are supported as well), for example: "2015-08-18T15:22:40+03:00"). Default - none."The 'begin_date' and time denote the initiation point of an Axinom DRM License Service Message, signifying when it becomes active. If a message is not yet active, the License Service will reject it. To account for small drifts between the client creating the DRM message and the server, the 'begin_date' is permitted to be up to one second ahead of the server time. This aspect is enabled in: FairPlay API v6.21.0+, Widevine API v6.24.0+, PlayReady API v6.20.1+. If there is no specific business logic requiring the DRM message to become active in the future, the 'begin_date' can be omitted.
expiration_dateNoStringAny string that represents a combined date and time value in the ISO 8601 format (time zones are supported as well), for example: "2015-08-18T15:22:40+03:00"). Default - none.Expiration date and time of an Axinom DRM License Service Message. It indicates when the Axinom DRM License Service Message becomes inactive. The License Service rejects a message that is not active. Axinom recommends to add 'expiration_date' in the License Service Message.
com_key_idYesStringAny string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 formatCommunication Key ID of the key that was used to sign an Axinom DRM License Service Message. The License Service rejects a message that has an invalid signature.
messageYesObjectAny object that represents a message of the following types: * Entitlement Message - a message that instructs the License Service how to construct a License.The message field refers to the inner message encapsulated by an Axinom DRM License Service Message. It contains an object that represents an inner message defined in the context of Axinom DRM.

Message Validity​

The fields begin/expiration_date define the validity time frame of the License Service Message.

Caution

Don’t confuse the validity time frame of the License Service Message and the validity time frame of the generated DRM License (Entitlement Message). The former, begin/expiration_date from the Axinom DRM License Service Message means: the License Service will only issue a DRM License when a License Service Message is valid according to its begin/expiration_date. The latter, start/expiration_datetime from the Entitlement Message means: the player can only use the DRM License for content decryption during DRM License’s validity.

tip

Axinom recommends using short-lived License Service Messages (minutes) unless the system architecture requires longer-lived tokens (e.g. due to disconnected scenario, very high load or alike).

Revision History​

The table below outlines and describes the different versions of this document.

Version

Date

Description

1.0

July 26, 2016

Initial version.

2.0

January 27, 2020
  • Axinom DRM License Server Message renamed to Axinom DRM License Service message.
  • New delivery option: "AxDrmMessage" HTTP query parameter.

3.0

October 29, 2021

Added id field.

4.0

December 27, 2021

Added "feature availability" information to recent new features. This will be added also for all subsequent features.

5.0

February 22, 2022

Added details on JWT signing.

6.0

April 02, 2024

Added tolerance to begin_date.