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

1. Use one of the following articles to create an application:

• Set up video-on-demand streaming in Wowza Streaming Engine
• Set up live streaming using an RTMP-based encoder in Wowza Streaming Engine
• Set up live streaming using an RTSP/RTP based encoder in Wowza Streaming Engine
• Publish and play a live stream (MPEG-TS based encoder) in Wowza Streaming Engine

2. 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

Map file details (verimatrixstreammap.txt)

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.

Test DRM playback

HLS (Cupertino) playback

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.

4. 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.

Test playback

Use Verimatrix DRM with Wowza nDVR

• 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.