Skip to main content

Content Keys Source

Allows to specify a content keys source under the content_keys_source section of the entitlement message. These sources provide alternative ways of providing or generating content keys. Note: exactly one content keys source must be specified at a time.

The structure of a Content Keys Source object is defined as follows.

entitlement_message.content_keys_source
"content_keys_source":
{
    "inline":
    [
        {
            "id": "11111111-0000-0000-0000-000000000000",
            "encrypted_key": "EREREREREREREREREREREQ==",
            "iv": "EREREREREREREREREREREQ==",
            "seed_id": "88888888-0000-0000-0000-000000000000",
            "usage_policy": "Policy A"
        }
    ],

    "license_request":
    {
        "seed_id": "88888888-0000-0000-0000-000000000000",
        "usage_policy": "Policy A"
    },

    "stored":
    [
        {
            "id": "11111111-0000-0000-0000-000000000000",
            "usage_policy": "Policy A"
        }
    ]
}
RequiredYES
Supported valuesAny valid Content Keys Source object (see below).

The Content Keys Source object consists of the following properties:

Inline​

Allows to specify the content keys that can be included in the license. Whether the content key is included into the license response or not, depends on key IDs in the license request. Only the content keys the IDs of which are also present in the license request are included. If, however, the license request contains any key ID not specified here, the license is denied.

RequiredOne of the content key sources must be specified.
DefaultNo content keys are entitled (only useful for testing)
Supported valuesAny array of valid Content Key objects (see below).

The Content Key object consists of the following properties:

id​

Specifies the ID of the content key (also known as "key ID" or "KID"). It can be any valid GUID in the 00000000-0000-0000-0000-000000000000 format.

RequiredYes
Supported valuesAny valid GUID string in the "00000000-0000-0000-0000-000000000000" format.

seed_id​

Specifies the ID of a key seed that is used to generate the content key. If not specified, the default key seed of the tenant is used. Note: the "seed_id" and "encrypted_key" properties are mutually exclusive.

DefaultThe default key seed will be utilized.
Supported valuesAny valid GUID string in the "00000000-0000-0000-0000-000000000000" format.

encrypted_key​

Allows to provide the content key itself, in encrypted form, encoded using the Base64 encoding (RFC 4846). The key (exactly 16 bytes) must be encrypted using the AES-CBC algorithm, without padding, where the encryption key is the tenant’s communication key and the initialization vector (IV) is the content key ID in big-endian byte order. For example, when using the following key ID, "1E0DE660-B47E-4C79-B5CE-EDBD72BB17B3", as the IV for encryption, its byte representation must be "0x1E0DE660B47E4C79B5CEEDBD72BB17B3". If not specified, a content key is generated based on the key ID and the default key seed of the tenant. Note: the "encrypted_key" and "seed_id" properties are mutually exclusive.

DefaultContent key is generated based on a key seed.
Supported valuesAny string representing Base64-encoded 16-byte binary data, for example: "HYDILKxZnPF0KizuWT0hww==".

iv​

Initialization vector (IV; exactly 16 bytes) is a randomizer that has an impact on generating the random content key. When regenerating the content Key, along with the content Key ID, Iv is needed. The IV is encoded as Base64 using a hex to Base64 converter tool, shall be used for the decryption of media together with the provided or generated content key. Only used by FairPlay DRM; ignored otherwise.

RequiredDepends*.
DefaultThe IV is loaded from another source.
Supported valuesAny string representing Base64-encoded 16-byte binary data, for example: "6oDIr6xZnPF0KizuWT0s1g==".

*It is required to specify the IV here when it is not provided as part of the asset ID in the FairPlay license request passed by the player CDM. In case it’s provided both here and in the license request, the IV specified here takes precedence.

If the passed IV is different than the IV that is used in encryption, there will be playback errors.

usage_policy​

Specifies the name of the content key usage policy that is applied to this content key (see Content Key Usage Policies). If not specified, the default server-side content key usage policy is applied to this key. The default content key usage policy is the one with all its properties set to their default values.

DefaultThe default usage policy is applied to this key.
Supported valuesAny non-empty string, for example: "Policy A".

License Request​

Allows to specify that content keys are generated and included into the license only based on the key IDs present in the license request. This can be set under the license_request section of the Entitlement service. In the case of FairPlay, this feature is allowed only when the key IV is provided in the asset ID of the license request. Usage of this content keys source is mutually exclusive with other sources. If not specified, another content keys source must be used.

warning

Usage of this feature presents a security risk as content keys are generated for any media, without any key ID based restrictions. It’s highly recommended to avoid using this feature, unless the risks involved are understood.

RequiredOne of the content key sources must be specified.
Supported valuesAny valid License Request Content Keys Source object (see below).

The License Request Content Keys Source object consists of the following properties:

seed_id​

The ID of the key seed that shall be used for generating content keys. If the key seed ID is specified, it must reference an existing key seed, otherwise the license is denied. If not specified, the default key seed of the tenant is used for key generation.

DefaultThe default key seed is utilized.
Supported valuesAny string that represents a valid GUID string in the "00000000-0000-0000-0000-000000000000" format.

usage_policy​

The name of the content key usage policy that is associated with the generated content key(s) (see Content Key Usage Policies). If not specified, the default server-side content key usage policy is associated with the content keys.

DefaultThe default usage policy is applied to this key.
Supported valuesAny non-empty string, for example: "Policy A".

Stored​

Allows to specify which content keys, stored in Axinom Key Service database, are entitled to be included in the license. Use this content keys source if you need to fetch the keys from our database, instead of having them be generated based on a key seed or providing them explicitly in the Entitlement Message. This is typically used when working with content keys imported to our Key Service database from 3rd party services.

The actual set of keys that will be included in the license will depend on which specific keys the client is requesting at the time. If any of the keys requested by the client are not entitled or are not present in the database, the license is denied.

Please note:

  • Retrieved content keys are cached for 1 day. Any updates performed on the content keys in the database are not visible sooner than that.
  • In case of FairPlay, the IV-s associated with content keys can come from two sources: 1) the database; 2) from the Asset ID in the license request. At least one of these sources must have an IV. If none have an IV, or if both have an IV and they don't match, the license is denied.
RequiredExactly one content key source must be specified at a time.
Supported valuesAny valid Stored Content Keys Source object (see below).
AvailabilityAxinom DRM FairPlay API 6.17.1, Widevine API v6.16.4+, PlayReady API 6.18.2+

The Stored Content Keys Source object consists of the following properties:

id​

Specifies the ID of the content key (also known as "key ID" or "KID"). It can be any valid GUID in the 00000000-0000-0000-0000-000000000000 format.

RequiredYes
Supported valuesAny valid GUID string in the "00000000-0000-0000-0000-000000000000" format.

usage_policy​

The name of the content key usage policy that is associated with the generated content key(s) (see Content Key Usage Policies). If not specified, the default server-side content key usage policy is associated with the content keys.

DefaultThe default usage policy is applied to this key.
Supported valuesAny non-empty string, for example: "Policy A".