Security and Authentication

Stream Aliasing

Stream Aliasing is the premier mechanism for securing your online content. You can specify Aliases for each of your inbound streams. When Stream Aliasing has been enabled, inbound streams cannot be accessed directly. Instead, you must create aliases for each stream that clients then use to obtain the stream. It is important to note again that when aliasing is on, streams can no longer be requested/played by using the localStreamName. In addition, stream aliases are single use , meaning that once a stream has been requested using an alias, that alias is deleted and is no longer available. This allows you to tightly control access to your online content.

Stream Aliasing allows the protection of streams on servers that are available to the public. You can generate stream aliases for use by your website or player/clients. Once the client uses that alias you can be assured that the stream is again secured until you issue a new alias to an authorized user. Stream Aliasing can be enabled by changing the value hasStreamAliases in config.lua to true.

Aliases can be managed using four API commands:

• addStreamAlias
• removeStreamAlias
• listStreamAliases
• flushStreamAliases

Alias Expired Period

While aliases are typically single-use, there is an additional parameter, ExpirePeriod, which allows for additional flexibility in the automatic removal of aliases by the system. ExpirePeriod is an integer value that can either be positive or negative.:

Positive number: The alias is not a single use, it will be valid for this many seconds. For example,

expirePeriod=10

The alias will be valid for 10 seconds, and may be used repeatedly during that 10 seconds.

Negative number: The alias is a single use and will also expire after the absolute-value of the parameter seconds have passed. For example,

expirePeriod=-10

In this case the alias will expire after 10 seconds unless it has been used before then

Value of 0: Zero is a special case in which the alias is made permanent. The alias will never automatically expire. This can be used to rename streams.

Common Alias Configuration

Example: Pay-wall/Registered User Section

Stream Aliasing allows you to maintain your own client authentication methods, whether that requires your users to login via your web site, through a mobile app, or some other means. Once a client has been authenticated via your existing method, you then simply need to issue the addStreamAlias command to the EMS just before issuing the video link to the client.

For example: a user has logged into her home security account and has just clicked on a link to view the “front door camera”. Your web server will be called by that link and do the following:

1. Verify the user’s current session
2. Issue the following command to the EMS:
3. addStreamAlias localstreamname=privateDoorCam aliasName=publicDoorCam
4. Serve the player page to the client with the following URI (using flash in this example): rtmp://MyServer/live/publicDoorCam

When the user’s app or browser loads the player and plays the stream, the alias will be automatically deleted. This means that if anyone sniffed the link, or if the user copies the link somehow and tries to play it back directly at a later date, it will fail to play.

Group Name Aliasing

Stream Aliasing only works for connection based protocols (RTMP and RTSP), so what about HLS, DASH and all the other HTTP based protocols? That is where Group Name Aliasing comes in.

The EMS Web Server (EWS) API functions provide the means for adding/removing/checking/listing group name aliases. Same as stream aliases, group name aliases are designed to be used to protect or hide your source stream. Once a group name alias is created the group name can no longer be used to request HTTP playback of that stream. Once a group name alias is requested by a client the alias is then removed.

The hasGroupNameAliases option in the web server configuration file, webconfig.lua, should be set to true to enable group name aliases. HLS/HDS/MSS/DASH streams should be created before adding group name aliases.

Group name aliases can be managed using five API commands:

• addGroupNameAlias
• removeGroupNameAlias
• getGroupNameByAlias
• listGroupNameAliases
• flushGroupNameAliases

A typical use case for Group Name Aliases is shown below. The use case also applies to HDS, MSS, and DASH streams (simply replace createHLSstream with createHDSstream, createMSSstream, or createDASHstream, respectively, and use a compatible player.

See the Interoperability section for a list of compatible players for different HTTP stream types).

1. Setup an HTTP Stream

• Create an HLS stream:

  createhlsstream localstreamnames=mystream targetfolder=/var/evo-webroot groupname=mygroup playlisttype=rolling cleanupdestination=1

• List all active HTTP streaming sessions:

  listHttpStreamingSessions

• Add a group name alias for the HTTP stream

  addGroupNameAlias groupName=mygroup aliasName=myalias

2. Playback the HTTP stream

• Open a compatible player

• Open the URI of the aliased HTTP stream

  http://localhost:8888/myalias

Behind the scenes, this actually plays back http://localhost:8888/mygroup/mystream/playlist.m3u8

The EWS takes care of translating the group name alias to the correct path for the playlist.

Inbound Authentication

The EvoStream Media Server can require that streams be authenticated before they can be pushed into the server. This is done for protection and so that outside sources cannot overwhelm your server without your control. Pushing streams is only valid for TCP based protocols like RTMP and RTSP. By default, the authentication values used by the EMS are defined in the config/users.lua file.

To enable or disable Inbound Authentication you may do either of the following:

1. Comment, or un-comment, out the “Authentication” section in the config/config.lua file.
2. Set the Boolean value in config/auth.xml to true (enabled) or false (disabled).

An important part of inbound authentication for RTMP is validating the “Encoder Agent”. This is essentially a name that the stream source uses to identify itself. There are generally only a few Encoder Agents that are used since most encoders mimic the functionality of Adobe’s Flash Media Encoder. When pushing a stream into the EMS, there are two options when it comes to Encoder Agent strings:

1. Change your Encoder Agent string to one that the EMS anticipates:
   • FMLE/3.0 (compatible; FMSc/1.0)
   • Wirecast/FM 1.0 (compatible; FMSc/1.0)
   • EvoStream Media Server ( www.evostream.com)
2. Add your Encoder Agent string into the list of encoderAgents in the config.lua file.

Outbound Authentication

When pushing streams, the EMS makes it very easy to provide authentication for sources that require it. You simply need to specify the username and password in the URI for the push command.

The official format for the URI is as follows:

rtmp://Username:Password@IPAddress:Port/stream/destination

Using this, your pushstream command may look like this:

pushstream uri=rtmp://myname:mypass@192.168.1.5/live localstreamname=TestStream1 targetstreamname=PushedStream

Client Authentication

Users may optionally enforce client authentication for RTSP clients. By enabling the “AuthenticatePlay” parameter within the authentication -> rtsp node of the config.lua file. When enabled, all RTSP clients must provide a username/password combination specified in users.lua.

Encoder/User Agents

emulateUserAgent=FMLE/3.0\ (compatible;\ FMSc/1.0)

When pushing RTMP there is often the need to change the Encoder Agent used by the EMS. The Encoder Agent is essentially a string that identifies the software that is acting as the stream source. Some RTMP end-points require that streams come from well-known sources. To accomplish this simply add the emulateUserAgent parameter to your pushStream command. It is often best to use the FMLE encoder agent:

Note: Spaces have been escaped so that the parameter is parsed correctly.

For convenience, the EMS provides several shorthand User-Agent strings. These shorthand strings are not case-sensitive.

Note: The default emulateUserAgent is evo