• How to protect RTMP streaming using SecureToken (ModuleSecureToken)

    SecureToken is a challenge and response based security system that provides a high level of content protection against spoofing threats (such as those posed by the Replay Media Catcher and Grab Pro) when used in conjunction with Wowza StreamLock™ AddOn (RTMPS), RTMPE, or RTMPTE. Each connection is protected by a random single-use key and a password (shared secret).

    Note: SecureToken functionality is built-in with Wowza Media Server™ 3.5.0 and later. If you're using an earlier version of Wowza Media Server, you must download the MediaSecurity Addon package to get the module. Download and unzip the MediaSecurity Addon package, copy the wms-plugin-security.jar file from the package /lib folder to the Wowza Media Server /lib folder, and then restart the server.

    Overview

    When an Adobe Flash client connects to Wowza Media Server, a custom SecureToken module generates a unique key for the pending connection. The generated key is encrypted using a shared secret and is returned to the client as part of the NetConnection.onStatus info object. The Flash client decrypts the unique key using the same shared secret and sends the result back to the custom module. The server then compares this key to the originally generated key; if the values don't match, the connection is terminated.

    SecureToken security is included in the ModuleSecureToken and ModuleRTMPAuthenticate modules. For more information about the ModuleRTMPAuthenticate module, see How to enable username/password authentication for RTMP and RTSP sources (ModuleRTMPAuthenticate).

    Configuring SecureToken on the server

    To configure SecureToken server-side, do the following:

    1. Set up live or video on demand (VOD)streaming by following one of our Tutorials.

    2. Open [install-dir]/conf/[application]/Application.xml in a text editor and add the following <Module> definition as the last entry in the <Modules> list:
      <Module>
      	<Name>ModuleSecureToken</Name>
      	<Description>ModuleSecureToken</Description>
      	<Class>com.wowza.wms.security.ModuleSecureToken</Class>
      </Module>
      If you're running Wowza Media Server 3.1.2 or earlier, add the following <Module> definition as the last entry in the <Modules> list instead:
      <Module>
      	<Name>ModuleSecureToken</Name>
      	<Description>ModuleSecureToken</Description>
      	<Class>com.wowza.wms.plugin.security.ModuleSecureToken</Class>
      </Module>
      Note: If you're already using the ModuleRTMPAuthenticate module to authenticate RTMP streaming, then you don't need to add the ModuleSecureToken module to the <Modules> list. The ModuleRTMPAuthenticate module already supports SecureToken protection.
    3. Add the following property to the application-level <Properties> container at the bottom of the Application.xml file (be sure to get the correct <Properties> container - there are several in the file):
      <Property>
      	<Name>secureTokenSharedSecret</Name>
      	<Value>[secure-token-secret]</Value>
      </Property>
      Replace [secure-token-secret] with your SecureToken secret. An example is:
      <Property>
      	<Name>secureTokenSharedSecret</Name>
      	<Value>#ed%h0#w@1</Value>
      </Property>
    4. To require that a secure connection (RTMPS, RTMPE, or RTMPTE) be used to playback the content, add the following property to the the application-level <Properties> container at the bottom of the Application.xml file (be sure to get the correct <Properties> container - there are several in the file):
      <Property>
      	<Name>requireSecureConnection</Name>
      	<Value>true</Value>
      	<Type>Boolean</Type>
      </Property>

    Configuring SecureToken on the client

    The SecureToken security feature requires changes to your client-side ActionScript player code so that it can respond to the SecureToken challenge. This section describes how to do this in custom Flash client code.

    To illustrate how to integrate SecureToken into your client-side ActionScript code, assume that we've configured a server-side application named live that uses the ModuleSecureToken module to protect content publishing and playback and that the secureTokenSharedSecret property is set to mytestpassword.

    The Flash client code to make a secure connection to the server looks like this:
    import com.meychi.ascryptAS3.TEA;
    
    var nc:NetConnection = new NetConnection();
    
    function ncOnStatus(infoObject:NetStatusEvent)
    {
    	if (infoObject.info.code == "NetConnection.Connect.Success")
    	{
    		if (infoObject.info.secureToken != null)
    			nc.call("secureTokenResponse", null, TEA.decrypt(infoObject.info.secureToken, "mytestpassword"));
    	}
    }
    
    nc.addEventListener(NetStatusEvent.NET_STATUS, ncOnStatus);
    nc.connect("rtmp://localhost/vod");
    The first line of the example imports the TEA library that's used to decrypt the SecureToken token. ActionScript 2.0 and 3.0 versions of this code are included in the following download: ActionScriptTEA.zip

    To integrate this code into your player, you must copy these classes into your Flash client code.

    Next, we define and create a NetConnection object that will be used to communicate with Wowza Media Server. The next function is the onStatus handler that's invoked during the NetConnection object lifecycle. Add the onStatus handler as a listener to the NetConnection object and finally a NetConnection.connect(url) to connect to Wowza Media Server.

    When the NetConnection object establishes a connection with Wowza Media Server, the onStatus handler is called with an infoObject.info.code value of NetConnection.Connection.Success. If the server is protected with SecureToken, the infoObject.info object has a SecureToken challenge in the secureToken field. To respond to this challenge, the Flash client code calls the remote function secureTokenResponse with the first parameter set to the decrypted token. You can see that the token is being decrypted with the following call:
    TEA.decrypt(infoObject.info.secureToken, "mytestpassword")
    This is all that you need to do to complete the challenge/response cycle. After the call is made to secureTokenResponse, the connection is validated and the rest of your Flash code executes normally. If the secureTokenResponse function isn't called before your Flash client code calls play or publish, Wowza Media Server terminates the connection.

    Starting in Wowza Media Server 3.5, SecureToken client-side code is integrated into the LiveVideoStreaming and VideoOnDemandStreaming example players that ship with the server software. In addition, the SecureToken feature has been integrated into several open source Flash-based players such as JW Player and FlowPlayer. For more information, see the following article:




    Originally Published: 11-08-2012.
    Updated: For Wowza Media Server 3.5 on 11-08-2012.

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