• How to set up Verimatrix DRM

    This article describes how to set up and use Wowza DRM with Verimatrix Video Content Authority System (VCAS) and Microsoft PlayReady encryption services using the Verimatrix DRM key management system.

    Note: Verimatrix DRM can be used with Wowza Streaming Engine™ software and Wowza Media Server™ (version 3) to encrypt Apple HLS streams. Verimatrix DRM must be used with Wowza Streaming Engine or Wowza Media Server 3.6 to encrypt Microsoft Smooth Streams.

    Contents


    Prerequisites
    Configuration
    Testing
    Using Verimatrix DRM with Wowza nDVR
    More resources

    Prerequisites


    To use Verimatrix DRM with Wowza DRM, you must set up Wowza media server live or video-on-demand (VOD) applications to deliver unencrypted streams.

    Apple HLS (Cupertino) streaming

    Note: Verimatrix DRM can be used with Wowza Streaming Engine software and Wowza Media Server software (version 3) to encrypt Apple HLS streams.
    1. Set up a live or video on demand streaming application by following the instructions in one of our Tutorials. For this example, we'll assume that you've set up an application named live for live Apple HLS streaming (added cupertinostreamingpacketizer to the Streams/LiveStreamPacketizers property in Application.xml) and that you're using the stream name myStream.

    2. Verify that you can play the unencrypted live stream on an iOS device by entering the following URL into the Safari web browser on the device:

      http://[wowza-ip-address]:1935/live/myStream/playlist.m3u8

    Microsoft Smooth Streaming

    Note: Verimatrix DRM MUST be used with Wowza Streaming Engine or Wowza Media Server (version 3.6) to encrypt Microsoft Smooth Streams.
    1. Set up a live or video on demand streaming application by following the instructions in one of our Tutorials. For this example, we'll assume that you've set up an application named live for live Smooth Streaming (added smoothstreamingpacketizer to the <Streams>/<LiveStreamPacketizers> property in Application.xml) and that you're using the stream name myStream.

    2. Verify that you can play the unencrypted live stream using the example Silverlight player in your Wowza media server installation. Double-click [install-dir]/examples/LiveVideoStreaming/SilverlightPlayer/player.html, enter the URL below, and then click the Connect button:

      http://[wowza-ip-address]:1935/live/myStream/Manifest

    Configuration


    Verimatrix DRM module

    1. Open the [install-dir]/conf/live/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. In [install-dir]/conf/live/Application.xml, use the text editor to add the following properties to the application-level <Properties> container at the bottom of the file (be sure to get the correct <Properties> container as 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 name 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] folder (see step 1 above) 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 often 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.

    Apple HLS (Cupertino) encryption

    To enable encryption of Apple HLS (Cupertino) streams, open [install-dir]/conf/live/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 Cupertino configuration properties


    Property name * Legacy property name Description
    drmVerimatrixProtectCupertinoStreaming Enables/Disables encryption of Apple HLS (Cupertino) streams.
    drmVerimatrixCupertinoKeyServerIpAddress drmVerimatrixServerIpAddress The IP address or domain name of the Verimatrix HLS key server.
    drmVerimatrixCupertinoKeyServerPort drmVerimatrixServerPort The Verimatrix HLS key server scrambler port.
    drmVerimatrixCupertinoKeyServerSecure drmVerimatrixServerSecure Set to true if the Verimatrix HLS key server scrambler port (drmVerimatrixCupertinoKeyServerPort) is protected using Secure Sockets Layer (SSL).
    drmVerimatrixCupertinoRequestTimeout drmVerimatrixRequestTimeout The key request timeout, in milliseconds.
    drmVerimatrixCupertinoIfFailFakeKey drmVerimatrixIfFailFakeKey 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 drmVerimatrixFailLicenseURL The alternate key server URL to use if the Verimatrix HLS key server is offline.
    drmVerimatrixCupertinoCallCreate drmVerimatrixCallCreate 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 drmVerimatrixKeyRotateInterval The default key rotation interval. If set to 0, key rotation is disabled.
    drmVerimatrixCupertinoDefaultPositionCount drmVerimatrixDefaultPositionCount 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 drmVerimatrixVODPerSessionKeys 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 drmVerimatrixCupertinoLiveStreamPacketizer The live stream packetizer to use. This value shouldn't be changed.
    cupertinoEncryptionAPIBased cupertinoEncryptionAPIBased If set to true, the Wowza media server uses the API method to encrypt the Apple HLS (Cupertino) streams. For more information, see "On-the-Fly PlayReady Encryption Using Server-Side API" in How to secure Apple HLS streaming using DRM encryption.

    * Wowza Streaming Engine and Wowza Media Server (version 3.6) support the legacy properties for Cupertino stream encryption. This enables you to seamlessly migrate your configuration files from older versions of the media server software. To avoid confusion, we encourage you to update any legacy property names in the configuration files in your Wowza media server installation.

    Smooth Streaming encryption

    Note: Wowza Streaming Engine or Wowza Media Server (version 3.6) is required.
    To enable encryption of Microsoft Smooth Streams, open [install-dir]/conf/live/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>drmVerimatrixProtectSmoothStreaming</Name>
        <Value>true</Value>
        <Type>boolean</Type>
    </Property>
    <Property>
        <Name>drmVerimatrixSmoothKeyServerIpAddress</Name>
        <Value>VerimatrixPlayReadyKeyServerIpAddress</Value>
    </Property>
    <Property>
        <Name>drmVerimatrixSmoothKeyServerPort</Name>
        <Value>12345</Value>
        <Type>Integer</Type>
    </Property>
    <Property>
        <Name>drmVerimatrixSmoothKeyServerSecure</Name>
        <Value>false</Value>
        <Type>Boolean</Type>
    </Property>
    <Property>
        <Name>drmVerimatrixSmoothRequestTimeout</Name>
        <Value>5000</Value>
        <Type>Integer</Type>
    </Property>
    <Property>
        <Name>drmVerimatrixSmoothIfFailFakeKey</Name>
        <Value>true</Value>
        <Type>Boolean</Type>
    </Property>
    <Property>
        <Name>drmVerimatrixSmoothFailLicenseURL</Name>
        <Value>http://localhost</Value>
    </Property>
    Verimatrix Smooth Streaming configuration properties

    Property name Description
    drmVerimatrixProtectSmoothStreaming Enables/Disables encryption for Smooth Streams.
    drmVerimatrixSmoothKeyServerIpAddress The IP address or domain name of the Verimatrix PlayReady key server. You must contact Verimatrix to get the IP Address.
    drmVerimatrixSmoothKeyServerPort The Verimatrix PlayReady key server scrambler port. You must contact Verimatrix to get the port value.
    drmVerimatrixSmoothKeyServerSecure Set to true if the Verimatrix PlayReady key server scrambler port (drmVerimatrixSmoothKeyServerPort) is protected using Secure Sockets Layer (SSL).
    drmVerimatrixSmoothRequestTimeout The key request timeout, in milliseconds.
    drmVerimatrixSmoothIfFailFakeKey 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 drmVerimatrixSmoothFailLicenseURL property. If set to false, then these streams aren't encrypted.
    drmVerimatrixSmoothFailLicenseURL The alternate key server URL to use if the Verimatrix PlayReady key server is offline.

    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}

    Note: Wowza DRM doesn't support key rotation with Smooth Streaming, so the positionCount and keyRotateInterval arguments in the map file are ignored for Smooth Streaming encryption.
    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 (for Apple HLS) or drmVerimatrixSmoothIfFailFakeKey property (for Smooth Streaming) 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: For Apple HLS encryption, specifies the number of positions (keys) to use to encrypt the stream for key rotation.

    • keyRotateInterval: For Apple HLS encryption, specifies how often the keys are rotated during packetization (live) or playback (video on demand). The value is in milliseconds.

      Note: The positionCount and keyRotateInterval arguments are NOT supported for Smooth Streaming encryption.
    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}

    Testing


    Start your Wowza media server and publish a stream with the name myStream from your encoder to the media server.

    Apple HLS (Cupertino) playback

    Note: You must install the Verimatrix ViewRight Live app on your iOS device to complete this procedure (Last verified with ViewRight Live version 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/live/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/vod/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 media server IP address, and [httpserver-ip-address] is the IP address of the web server hosting the still image file(s).

      Note: While the example playlist above is formatted for readability, 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:

      1. Reset on Launch: ON

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

      3. VCAS > Port: 80

      4. Registration Server > Host: ott-content.verimatrix.com

      5. Content Server > Host: [httpserver-ip-address], where [httpserver-ip-address] is the IP address of your 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 media server software running on Amazon EC2.


    The setup is similar for video-on-demand streaming. The Verimatrix public key server is configured with open live streams on the resourceId range 4000-4499 and video-on-demand 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.

    Smooth Streaming playback

    Double-click [install-dir]/examples/LiveVideoStreaming/SilverlightPlayer/player.html, enter the URL below, and then click the Connect button:

    http://[wowza-ip-address]:1935/live/myStream/Manifest

    Where [wowza-ip-address] is the Wowza media server IP address.

    To play the stream from your web server, copy the SilverlightPlayer folder to the content root of your web server, and then connect to:

    http://[httpserver-ip-address]/SilverlightPlayer/player.html

    Using 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://[wowza-ip-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.

    • If you're running Wowza Media Server software version 3.6.3.2 (or earlier), the following property must also be in the <DVR>/<Properties> container in Application.xml:
      <Property>
          <Name>cupertinoEncryptionAPIBased</Name>
          <Value>true</Value>
          <Type>Boolean</Type>
      </Property>

    For more information, see How to set up and run Wowza nDVR for live streaming.

    More resources


    Wowza and Verimatrix Secure End-to-End HLS Solution


    Originally Published: 10-08-2011.
    Updated: For Wowza Streaming Engine on 08-11-2014.

    If you're having problems or want to discuss this article, post in our forum.