Use Verimatrix VCAS DRM with Wowza Streaming Engine

This article describes how to set up and use Wowza DRM with Wowza Streaming Engine™ media server software, Verimatrix Video Content Authority System (VCAS), and Microsoft PlayReady encryption services using the Verimatrix DRM key management system for HLS streaming.

Note: Contact Verimatrix to obtain the Verimatrix Video Content Authority System (VCAS).

Configure a stream


To use Verimatrix DRM with Wowza DRM, you must set up a Wowza Streaming Engine live or video-on-demand (VOD) application to deliver an unencrypted stream.
  1. Use one of the following articles to create an application:
  1. Verify that you can play the unencrypted live stream using your player or one of the players on the Video Test Players webpage.

Configure DRM


Verimatrix DRM module

  1. Open the [install-dir]/conf/[application-name]/Application.xml file in a text editor and add the ModuleDRMVerimatrix module as the last entry in the <Modules> list:
     
    <Module>
        <Name>ModuleDRMVerimatrix</Name>
        <Description>ModuleDRMVerimatrix</Description>
        <Class>com.wowza.wms.drm.module.verimatrix.ModuleDRMVerimatrix</Class>
    </Module>
  2. Add the following properties to the application-level <Properties> container at the bottom of the file (be sure to get the correct <Properties> container; there are several in Application.xml):
     
    <Property>
        <Name>drmVerimatrixStreamToResourceMapperPath</Name>
        <Value>${com.wowza.wms.context.VHostConfigHome}/conf/verimatrixstreammap.txt</Value>
    </Property>
    <Property>
        <Name>drmVerimatrixPingInterval</Name>
        <Value>4000</Value>
        <Type>Integer</Type>
    </Property>
    <Property>
        <Name>drmVerimatrixPingTimeout</Name>
        <Value>4000</Value>
        <Type>Integer</Type>
    </Property>
    <Property>
        <Name>drmVerimatrixDebugLog</Name>
        <Value>true</Value>
        <Type>Boolean</Type>
    </Property>
    <Property>
        <Name>drmVerimatrixUseBackdoorURL</Name>
        <Value>false</Value>
        <Type>Boolean</Type>
    </Property>

    Verimatrix configuration properties

     
    Property Description
    drmVerimatrixStreamToResourceMapperPath Specifies the path to the verimatrixstreammap.txt file. If you want to have a map file per-application, create a verimatrixstreammap.txt file in each [install-dir]/conf/[application-name] folder and then set the property value to:

    <Value>${com.wowza.wms.context.VHostConfigHome}/conf/${com.wowza.wms.context.Application}/verimatrixstreammap.txt </Value>
    drmVerimatrixPingInterval Specifies how frequently the Verimatrix key server is pinged to determine if it's available, in milliseconds. If set to 0, ping tests are disabled. The Verimatrix key server for Microsoft PlayReady doesn't support this property.
    drmVerimatrixPingTimeout Specifies the ping request timeout, in milliseconds.
    drmVerimatrixDebugLog When set to true, turns on more verbose logging.
    drmVerimatrixUseBackdoorURL When set to true, a scrambler URL is used as the license URL in the playlist.m3u8 file for iOS devices. This is a good debugging tool to verify that the system is working. Be sure to set this property value to false when running in production. The Verimatrix key server for Microsoft PlayReady doesn't support this property.

HLS (Cupertino) encryption

To enable encryption of HLS (Cupertino) streams, open [install-dir]/conf/[application-name]/Application.xml in a text editor and add the following properties to the application-level <Properties> container at the bottom of the file. Be sure to add these properties below the properties that you added when you configured the Vermatrix DRM module.

<Property>
    <Name>drmVerimatrixProtectCupertinoStreaming</Name>
    <Value>true</Value>
    <Type>boolean</Type>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoKeyServerIpAddress</Name>
    <Value>public-ott.verimatrix.com</Value>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoKeyServerPort</Name>
    <Value>12684</Value>
    <Type>Integer</Type>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoKeyServerSecure</Name>
    <Value>false</Value>
    <Type>Boolean</Type>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoRequestTimeout</Name>
    <Value>5000</Value>
    <Type>Integer</Type>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoIfFailFakeKey</Name>
    <Value>true</Value>
    <Type>Boolean</Type>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoFailLicenseURL</Name>
    <Value>http://localhost</Value>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoCallCreate</Name>
    <Value>true</Value>
    <Type>Boolean</Type>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoKeyRotateInterval</Name>
    <Value>120000</Value>
    <Type>Integer</Type>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoDefaultPositionCount</Name>
    <Value>1000</Value>
    <Type>Integer</Type>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoVODPerSessionKeys</Name>
    <Value>false</Value>
    <Type>Boolean</Type>
</Property>
<Property>
    <Name>drmVerimatrixCupertinoLiveStreamPacketizer</Name>
    <Value>cupertinostreamingpacketizer</Value>
</Property>
<Property>
    <Name>cupertinoEncryptionAPIBased</Name>
    <Value>true</Value>
    <Type>Boolean</Type>
</Property>

Verimatrix HLS configuration properties

 
Property Description
drmVerimatrixProtectCupertinoStreaming Enables/disables encryption of HLS (Cupertino) streams.
drmVerimatrixCupertinoKeyServerIpAddress The IP address or domain name of the Verimatrix HLS key server.
drmVerimatrixCupertinoKeyServerPort The Verimatrix HLS key server scrambler port.
drmVerimatrixCupertinoKeyServerSecure Set to true if the Verimatrix HLS key server scrambler port (drmVerimatrixCupertinoKeyServerPort) is protected using SSL.
drmVerimatrixCupertinoRequestTimeout The key request timeout, in milliseconds.
drmVerimatrixCupertinoIfFailFakeKey If set to true, streams that either aren't listed in the verimatrixstreammap.txt file or are requested while the key server is offline are encrypted using a random 128-bit encryption key. The license URL for the stream is set to the URL provided by the drmVerimatrixCupertinoFailLicenseURL property. If set to false, then these streams aren't encrypted.
drmVerimatrixCupertinoFailLicenseURL The alternate key server URL to use if the Verimatrix HLS key server is offline.
drmVerimatrixCupertinoCallCreate If set to true, the Verimatrix DRM module will create the number of keys specified by the positionCount argument in the stream map file (verimatrixstreammap.txt) before streaming out the resource. If set to false, keys are created as needed. This property typically is set to true when the player prefetches all of the keys listed in the manifest, versus fetching a key when it receives a chunk that uses it.
drmVerimatrixCupertinoKeyRotateInterval The default key rotation interval. If set to 0, key rotation is disabled.
drmVerimatrixCupertinoDefaultPositionCount The default number of positions (or keys) to use for key rotation.
drmVerimatrixCupertinoDTVPosition If set to true, the position is the time of day, in UTC, for which this key is valid. If set to false, the position is calculated by the chunk ID.
drmVerimatrixCupertinoVODPerSessionKeys If set to true, a new position (key) is used for each new streaming session (per-session keys). If set to false, a single key or set of keys is used. If multiple positions are defined, the keys are rotated during playback. The same keys are used for each session of the same stream name.
drmVerimatrixCupertinoLiveStreamPacketizer The live stream packetizer to use. Don't change this value.
cupertinoEncryptionAPIBased If set to true, Wowza Streaming Engine uses the API method to encrypt the HLS (Cupertino) streams. For more information, see On-the-fly encryption with the Wowza Streaming Engine Java API.

Map file details (verimatrixstreammap.txt)

Use a text editor to create the Verimatrix stream map file [install-dir]/conf/verimatrixstreammap.txt and add the following content to the file:
 
myStream={resourceId:4000, positionCount:4, keyRotateInterval:120000}
sample.mp4={resourceId:4500, positionCount:4, keyRotateInterval:120000}

The verimatrixstreammap.txt map file is used to map stream names to resource IDs and control key rotation. When a new stream is started or played, the Verimatrix DRM module searches for the stream name in this file. If there's a match in the file, the stream is encrypted based on how the entry is defined in the file. If the stream name isn't found in the file, and if the drmVerimatrixCupertinoIfFailFakeKey property is set to true, then the stream is encrypted using a random 128-bit key. This will basically make the stream unplayable. If the property value is false, the stream isn't encrypted. Each time the map file is updated, the Verimatrix DRM module will re-read the file.

The Verimatrix stream map file supports the following arguments:

  • resourceId: Specifies the resourceId to use to encrypt the given stream name.
     
  • positionCount: Specifies the number of positions (keys) to use to encrypt the stream for key rotation.
     
  • keyRotateInterval: Specifies how often the keys are rotated during packetization (live) or playback (video on demand). The value is in milliseconds.
The following shows some example Verimatrix stream map entries:

# The stream with the name myStream will be encrypted using resourceId 1234 and will use the
# default position count (drmVerimatrixCupertinoDefaultPositionCount) and will rotate keys
# using the default key rotation interval (drmVerimatrixCupertinoKeyRotateInterval)
myStream={resourceId:1234}

# The stream with the name sample.mp4 will be encrypted using resourceId 1235 and will use 4 key positions
# that will be rotated every 20 seconds (20000 milliseconds)
sample.mp4={resourceId:1235, positionCount:4, keyRotateInterval:20000
}

Test DRM playback


Start Wowza Streaming Engine and publish a stream named myStream from your encoder to Wowza Streaming Engine.

HLS (Cupertino) playback

Note: You must install the Verimatrix ViewRight Live app on your iOS device to complete this procedure, which was last verified with ViewRight Live 3.5.0.1. You can get the app from the Apple App Store. Both Live and VOD streaming are supported.
  1. Using a text editor, create a playlist file named index.html and set the contents of the file to:
     
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
        <playlistItemList>
            <count>4</count>
        <playlistItem>
            <id>1</id>
            <contenturl>http://184.72.239.149/livev/myStream/playlist.m3u8</contenturl>
            <imageurl>http://www.wowza.com/downloads/images/verimatrix_ch1.jpg</imageurl>
            <createdat>2012-10-26T23:30:37.692Z</createdat>
            <updatedat>2013-09-25T03:58:13.272Z</updatedat>
            <version>1</version>
            <position>1</position>
        <content>
            <id>1</id>
            <contenttype>DTV</contenttype>
            <description>This is a description for the Wowza live test stream</description>
            <createdat>2012-10-26T23:26:06.573Z</createdat>
            <provider>Wowza</provider>
            <name>Wowza live test stream</name>
            <updatedat>2013-02-24T16:27:40.949Z</updatedat>
            <version>1</version>
        </content>
        </playlistItem>
        <playlistItem>
            <id>2</id>
            <contenturl>http://184.72.239.149/vodv/mp4:sample.mp4/playlist.m3u8</contenturl>
            <imageurl>http://www.wowza.com/downloads/images/verimatrix_ch1.jpg</imageurl>
            <createdat>2012-10-26T23:30:37.692Z</createdat>
            <updatedat>2013-09-25T03:58:13.272Z</updatedat>
            <version>1</version>
            <position>1</position>
        <content>
            <id>2</id>
            <contenttype>VOD</contenttype>
            <description>This is a description for the Wowza vod test stream</description>
            <createdat>2012-10-26T23:26:06.573Z</createdat>
            <provider>Wowza</provider>
            <name>Wowza vod test stream</name>
            <updatedat>2013-02-24T16:27:40.949Z</updatedat>
            <version>1</version>
        </content>
        </playlistItem>
        <playlistItem>
            <id>3</id>
            <contenturl>http://[wowza-ip-address]:1935/[application-name]/myStream/playlist.m3u8</contenturl>
            <imageurl>http://[httpserver-ip-address]/still.jpg</imageurl>
            <createdat>2012-10-26T23:30:37.692Z</createdat>
            <updatedat>2013-09-25T03:58:13.272Z</updatedat>
            <version>1</version>
            <position>1</position>
        <content>
            <id>3</id>
            <contenttype>DTV</contenttype>
            <description>This is a description for MyStream (live)</description>
            <createdat>2012-10-26T23:26:06.573Z</createdat>
            <provider>Wowza</provider>
            <name>MyStream (live)</name>
            <updatedat>2013-02-24T16:27:40.949Z</updatedat>
            <version>1</version>
        </content>
        </playlistItem>
        <playlistItem>
            <id>4</id>
            <contenturl>http://[wowza-ip-address]:1935/[application-name]/sample.mp4/playlist.m3u8</contenturl>
            <imageurl>http://[httpserver-ip-address]/still.jpg</imageurl>
            <createdat>2012-10-26T23:30:37.692Z</createdat>
            <updatedat>2013-09-25T03:58:13.272Z</updatedat>
            <version>1</version>
            <position>1</position>
        <content>
            <id>4</id>
            <contenttype>VOD</contenttype>
            <description>This is a description for Sample.mp4 (vod)</description>
            <createdat>2012-10-26T23:26:06.573Z</createdat>
            <provider>Wowza</provider>
            <name>Sample.mp4 (vod)</name>
            <updatedat>2013-02-24T16:27:40.949Z</updatedat>
            <version>1</version>
        </content>
    </playlistItem>
    </playlistItemList>
    Where [wowza-ip-address] is the Wowza Streaming Engine server IP address, and [httpserver-ip-address] is the IP address of the web server hosting the still image file(s).
     
    Note: The example playlist above is formatted for readability, however, the tested version of the ViewRight Live player can't handle newlines and/or carriage returns in the playlist file, so be sure to remove such characters from your final playlist file.
  2. Create the following folder path in the content root of your web server: OMIWebappserviceplaylist1playlistItemList. Copy the index.html file to this folder.
     
  3. On your iOS device, tap Settings and select the ViewRight app. Set the following values and then close Settings:
     
  • Reset on Launch: ON
     
  • VCAS > Host: Enter the IP address or domain name of the Verimatrix HLS key server ([keyserver-ip-address]). You must contact Verimatrix to get the IP address.
     
  • VCAS > Port: 80
     
  • Registration Server > Host: ott-content.verimatrix.com
     
  • Content Server > Host: [httpserver-ip-address], where [httpserver-ip-address] is the IP address of the web server that hosts the playlist.plist file. Make sure that the IP address that you specify here can be accessed by the iOS device.
  1. Open the ViewRight application on your iOS device and enter any name and email address to register (this information isn't used). Next, click the first entry in the playlist. If working properly, Your Stream should play. The second stream in the list (Wowza Stream (live)) is a test stream provided by Wowza Streaming Engine running on Amazon EC2.
The setup is similar for VOD streaming. The Verimatrix public key server is configured with open live streams on the resourceId range 4000-4499 and VOD streams on the resourceId range 4500-4999. Mapping from stream name to resourceId is done in the [install-dir]/conf/verimatrixstreammap.txt file. The test setup above includes an entry for the sample file [install-dir]/content/sample.mp4.

Test playback

Enter the URL below in your player or the HLS player on the Video Test Players webpage, and then click Start:
 
http://[address]:1935/[application-name]/myStream/playlist.m3u8

Use Verimatrix DRM with Wowza nDVR


When using Verimatrix DRM with Wowza nDVR, be aware of the following:
 
  • For nDVR playback, use a URL with the ?DVR query string parameter:
     
    http://[address]:1935/[application-name]/[stream-name]/playlist.m3u8?DVR

     
  • The Verimatrix DRM module must be enabled during nDVR recording and playback.
     
  • When using Wowza nDVR in a live stream repeater (origin/edge) configuration, the Verimatrix DRM module must be enabled on both origin and edge.
     
  • In origin/edge mode, both origin and edge servers use a common shared secret string to encrypt data exchanged between instances. The dvrEncryptionSharedSecret or liveRepeaterEncryptionSharedSecret properties can be used to customize the shared secret that's used. For more information about how to use these properties, see nDVR advanced configuration.
For more information, see Set up and run Wowza nDVR in Wowza Streaming Engine.