Use BuyDRM map files to protect live and video-on-demand streams

Learn how to use BuyDRM KeyOS map files to write rules for applying DRM encryption to live and video-on-demand streams.

About BuyDRM KeyOS


BuyDRM KeyOS can protect HLS and MPEG-DASH live and video-on-demand streams using Apple Fairplay, Microsoft PlayReady, and Google Widevine encryption. For instructions on how to integrate the BuyDRM KeyOS and BuyDRM KeyOS MultiPack Wowza module with Wowza Streaming Engine™ media server software, see the following articles:

About buydrmstreammap.txt map files


The buydrmstreammap.txt map file is used by the BuyDRM KeyOS and BuyDRM KeyOS MultiPack Wowza module to map application stream names to BuyDRM keyIds, contentIds, and mediaIds. Each map entry must include a keyId, contentId, and mediaId property. The following is an example of a buydrmstreammap.txt file.

sample.mp4={keyId:F6005DCF-7F93-4B8E-85C7-F908840DA059,contentId:F6005DCF-7F93-4B8E-85C7-F908840DA059,mediaId:${Application.Name}/${AppInstance.Name}/${Stream.Name}}
mymusic.mp4={keyId:E45F3254-846D-BBE4-4FD6-E467B78A0910,contentId:E45F3254-846D-BBE4-4FD6-E467B78A0910,mediaId:mymusic}
music*={keyId:${KeyIdGenerator.Random},contentId:${KeyId},mediaId:music-${Stream.Name}}
video*={keyId:${KeyIdGenerator.Random},contentId:${KeyId},mediaId:video-${Stream.Name}}
myStream*={keyId:${KeyIdGenerator.Random},contentId:${KeyId},mediaId:video-${Stream.Name},adaptiveGroup:myAbrGroup}
myExtraAbrStream_1080p={keyId:${KeyIdGenerator.Random},contentId:${KeyId},mediaId:video-${Stream.Name},adaptiveGroup:myAbrGroup}
*={keyId:${KeyIdGenerator.Random},contentId:${KeyId},mediaId:${Stream.Name}}

The part of the entry to the left of the equal sign ( = ) is the stream name match and the right side is a structure that defines the BuyDRM keyIds, contentIds, mediaIds, and adaptiveGroup values. When matching a stream name to a map entry, the first entry that matches the stream name is used. If there's no match for a stream name, then the stream isn't protected. Stream map entries can include wildcard characters ( * ) or simple stream names.

Map file properties


The following properties can be added to the buydrmstreammap.txt map file:

Property Description

keyId

The ID of the content key used to encrypt the content. If more than one asset is encrypted with the same keyId, you can use a single license to play them. The keyId can be an explicit value or a variable. The following variables are supported.

  • ${KeyIdGenerator.Random}: Generates a random keyId each time the keyId is referenced.
  • ${KeyIdGenerator.Value}: Generates a keyId based on the keyIdDeriveFrom value. For more information, see keyIdDeriveFrom.
Note: The ${KeyIdGenerator.Value} variable is only relevant if you're using the BuyDRM KeyOS MultiPack Wowza module.
contentId

The unique file ID within the KeyOS infrastructure. The contentId can be an explicit value or a variable. The following variable is supported.

  • ${KeyId}: Sets the contentId to the same values as the keyId. This is the default value.
mediaId

The mediaId functions like a file name. The mediaId can be an explicit value or a variable. More than one variable can be used with mediaId. The following variables are supported:

  • ${Stream.Name} – Sets the mediaId to the stream name. This is the default value.
  • ${KeyId} – Sets the mediaId to the same value as the keyId.
  • ${VHost.Name} – Sets the mediId to the virtual host name.
  • ${Application.Name} – Sets the mediaId to the application name.
  • ${AppInstance.Name} – Sets the mediaId to the application instance name.

adaptiveGroup

(Optional) The name of the adaptive group to which this entry belongs (if any). All streams within the same adaptiveGroup are encrypted with the same key. Special characters aren't supported.

In addition to the properties in the above table, the KeyOS Multipack Wowza module also supports the following optional properties:

Property Description

prlaurl

Specifies the URL for the KeyOS MultiKey PlayReady license service. The default value is https://pr-keyos.licensekeyserver.com/core/rightsmanager.asmx.

wvlaurl

Specifies the URL for the KeyOS MultiKey Widevine license service. The default value is https://wv-keyos.licensekeyserver.com/.

keyIdDeriveFrom

Specifies the value used to create the content key. This property is required if the keyId is set to ${KeyIdGenerator.Value}. The keyIdDeriveFrom can be an explicit value or a variable, and more than one variable can be specified. The following variables are supported.

  • ${UserKey} – Bases the content key on the user key.
  • ${VHost.Name} – Bases the content key on the virtual host name.
  • ${Application.Name} – Bases the content key on the application name.
  • ${AppInstance.Name} – Bases the content key on the application instance name.
  • ${Stream.Name} – Bases the content key on the stream name.

hlsEncType

Sets the protection method to use for HLS to one of the following:

  • METHOD_SAMPLE_AES – Applies Fairplay encryption to HLS streams. This is the default value.
  • METHOD_SAMPLE_PLAYREADY – Applies PlayReady encryption to HLS streams. Use the KeyOS MultiKey SDKs to play PlayReady encrypted HLS streams.