Skip to content

Stream Security Documentation

Jump to bottom
Ahmet Oğuz Mermerkaya edited this page Jun 6, 2021 · 34 revisions

This guide explains stream security options in Ant Media Server. Briefly, Stream Security options are;

  1. Enable/Disable Accepting Undefined Streams
  2. One Time Token Control
  3. CORS Filter
  4. Hash-Based Token
  5. Publisher IP Filter
  6. JWT Stream Security Filter [Draft]

1. Enable/Disable Accepting Undefined Streams

This setting shortly is checking if live stream is registered in Ant Media Server.

For example: If Ant Media Server accepts undefined streams, it accepts any incoming streams. If accepting undefined Streams is disabled, only streams with their stream id in the database are being accepted by Ant Media Server.

You can find in more detail in here

After modifying the configuration, please add the streamId, stream name in "broadcast" collections of your App.

Accepting Undefined Streams

2. One Time Token Control

One Time Token Control feature usage is in Dashboard / Application(LiveApp or etc.) / Publish/Play with One-time Tokens section.

One Time Token

By enabling this option, one-time tokens are required for publishing and playing. Publish/Play requests without tokens will not be streamed.

If One-Time Token control is enabled, then all publish and play requests should be sent with a token parameter.

After version 2.2 one time token security option in the Dashboard will be divided into two parts. There will be seperate options for enabling/disabling one time tokens for publishing and for playing. This will allow for example using one time tokens for only players and hash-based tokens (or no security) for publishers or vice-versa.

Create a Token in Publish&Play Scenario

The Server creates tokens with getTokenV2 Rest Service getting streamId, expireDate and type parameters with query parameters. Service returns tokenId and other parameters. It is important that streamId and type parameters should be defined properly. Because tokenId needs to match with both streamId and type.

The sample token creation service URL in Publish Scenario:

http://[IP_Address]:5080/<Application_Name>/rest/v2/broadcasts/<Stream_Id>/token?expireDate=<Expire_Date>&type=publish

The sample token creation service URL in Play Scenario:

http://[IP_Address]:5080/<Application_Name>/rest/v2/broadcasts/<Stream_Id>/token?expireDate=<Expire_Date>&type=play

Expire Date format is Unix Timestamp. Check also -> https://www.epochconverter.com/

RTMP URL usage:

rtmp://[IP_Address]/<Application_Name>/streamID?token=tokenId

Here is OBS settings for the Hash-Based Token OBS One Time Token Image

Live Stream / VoD URL usage:

http://[IP_Address]/<Application_Name>/streams/streamID.mp4?token=tokenId
http://[IP_Address]/<Application_Name>/streams/streamID.m3u8?token=tokenId
http://[IP_Address]/<Application_Name>/play.html?name=streamID&playOrder=hls&token=tokenId

WebRTC usage:

-Playing usage: Again the token parameter should be inserted to play WebSocket message. Also please have a look at the principles described in the WebRTC playing wiki page.

TODO: Please tell or give link how to get token from Ant Media Server --> 
Secure WebSocket: wss://SERVER_NAME:5443/WebRTCAppEE/websocket
WebSocket without Secure: ws://SERVER_NAME:5080/WebRTCAppEE/websocket

{
command : "play",
streamId : "stream1",
token : "tokenId",
}

-Publishing usage: Again the token parameter should be inserted to WebSocket message. Also please have a look at the principles described in the WebRTC publishing wiki page.

Secure WebSocket: wss://SERVER_NAME:5443/WebRTCAppEE/websocket
WebSocket without Secure: ws://SERVER_NAME:5080/WebRTCAppEE/websocket

{
command : "publish",
streamId : "stream1",
token : "tokenId",
}

3. CORS Filter

CORS(Cross-Origin Resource Sharing) Filter is enabled and accepts requests from everywhere by default.

If you want to customize by yourself CORS Filters in Application, you can access in SERVER_FOLDER / webapps / {Application} / WEB-INF / web.xml

<filter>
	<filter-name>CorsFilter</filter-name>
	<filter-class>io.antmedia.filter.CorsHeaderFilter</filter-class>
	<init-param>
	    <param-name>cors.allowed.origins</param-name>
	    <param-value>*</param-value>
	 </init-param>
	 <init-param>
	 	<param-name>cors.allowed.methods</param-name>
	 	<param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>
	 </init-param>
</filter>
<filter-mapping>
	<filter-name>CorsFilter</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

If you want to customize by yourself CORS Filters in Root, you can access in SERVER_FOLDER / webapps / root / WEB-INF / web.xml

<filter>
	<filter-name>CorsFilter</filter-name>
	<filter-class>io.antmedia.filter.CorsHeaderFilter</filter-class>
	<init-param>
	  <param-name>cors.allowed.origins</param-name>
	  <param-value>*</param-value>
	</init-param>
	<init-param>
	  <param-name>cors.allowed.methods</param-name>
	  <param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>
	</init-param>
</filter>
<filter-mapping>
	<filter-name>CorsFilter</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

Quick Learn: Tomcat CORS Filter

4. Hash-Based Token

Firstly, settings should be enabled from the settings file of the application in SERVER_FOLDER / webapp / {Application} / WEB-INF / red5-web.properties

settings.hashControlPublishEnabled=true
settings.hashControlPlayEnabled=true
tokenHashSecret=PLEASE_WRITE_YOUR_SECRET_KEY

Set true settings.hashControlPublishEnabled to enable secret based hash control for publishing operations, and settings.hashControlPlayEnabled for playing operations.

Also, do not forget to define a secret key for generating a hash value.

Publishing Scenario

Step 1. Generate a Hash

You need to generate a hash value using the formula sha256(STREAM_ID+ROLE+SECRET) for your application and send to your clients. The values used for hash generation are:

STREAM_ID: The id of stream, generated in Ant Media Server.
ROLE: It is either "play or "publish"
SECRET: Shared secret key (should be defined in the setting file)

Step 2. Request with Hash

The system controls hash validity during publishing or playing. Keep in mind that there is NO '+' in calculating the hash in this formula sha256(STREAM_ID+ROLE+SECRET) Here is an example for that.

Let's say STREAM_ID: stream1, ROLE: publish, SECRET: this_is_secret Your hash is the result of this calculation: sha256(stream1publishthis_is_secret)

Go to JavaScript SHA-256 for online demo

RTMP Publishing: You need to add a hash parameter to RTMP URL before publishing. Sample URL:

rtmp://[IP_Address]/<Application_Name>/<Stream_Id>?token=hash

Here is OBS settings for the Hash-Based Token OBS Hash-Based Token Image

WebRTC Publishing: Hash parameter should be inserted to publish WebSocket messages.

{
command : "publish",
streamId : "stream1",
token : "hash",
}

Playing Scenario

Step 1. Generate a Hash

You need to generate a hash value using the formula sha256(STREAM_ID + ROLE + SECRET) for your application and send to your clients. The values used for hash generation are:

STREAM_ID: The id of stream, generated in Ant Media Server.
ROLE: It is either "play or "publish"
SECRET: Shared secret key (should be defined in the setting file)

Step 2. Request with Hash

Live Stream/VoD Playing: Same as publishing, the hash parameter is added to the URL. Sample URL:

http://[IP_Address]/<Application_Name>/streams/<Stream_Id_or_Source_Name>?token=hash

WebRTC Playing: Again the hash parameter should be inserted to play WebSocket message.

{
command : "play",
streamId : "stream1",
token : "hash",
}

Please have a look at the principles described in the WebRTC WebSocket wiki page.

Evaluation of the Hash

If related settings are enabled, Ant Media Server first generates hash values based on the formula sha256(STREAM_ID + ROLE + SECRET) using streamId, role parameters and secret string which is defined in the settings file.

Then compare this generated hash value with the client's hash value during authentication.

Once the hash is successfully validated by Ant Media Server, the client is granted either to publish or play according to application setting and user request.

5. Publisher IP Filter

Publisher IP Filter feature is available for later versions of the 1.9.0+ version.

Publisher IP filter feature allows you to specify the IP addresses allowed for publishing. You can define multiple allowed IPs in CIDR format as comma (,) separated.

To enable publisher IP filtering you must set settings.allowedPublisherCIDR in AMS_DIR/webapps/<App_Name>/WEB_INF/red5.properties file with the allowed IP addresses.

Example: settings.allowedPublisherCIDR=10.20.30.40/24,127.0.0.1/32 allows IPs 10.20.30.[0-255] and 127.0.0.1.

You can read more about CIDR notation.

6. JWT Stream Security Filter

JWT Stream Security feature is enabled/disabled in Dashboard/LiveApp( or any other)/ Settings/Publish/Play with JWT Filter. Just take a look at the image for the related part. You can use JWT Stream Security Filter for Stream Publishing and Playing. Publish/Play requests without JWT tokens will not be streamed if you enable the JWT Stream Security Filter as shown below by also adding Secret Key on web panel.

Ant Media Server JWT Stream Security Filter

After version 2.3.3 JWT Stream Security filter option in the Dashboard will be divided into two parts. There will be separate options for enabling/disabling JWT Stream Security for publishing and for playing. This will allow for example using JWT Stream Security for only players and other security (or no security) for publishers or vice-versa.

Generate Publish/Play JWT Token

Let's assume that our secret key is zautXStXM9iW3aD3FuyPH0TdK4GHPmHq so that we just need to create a JWT token. Luckily, there are plenty of libraries available for JWT for your development. For our case, we will just use Debugger at JWT.

As shown above, we use HS256 as algorithm and use our secret key zautXStXM9iW3aD3FuyPH0TdK4GHPmHq to generate the token. The payload is not critical for this authorization. You can use any payload to create the token. On the server side, it just checks the token is signed with secret key. So that our JWT token to publish/play the stream is:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHJlYW1JZCI6InN0cmVhbTEiLCJ0eXBlIjoicHVibGlzaCJ9.9otWqr4qTvh8afoBOifR9t9wkeaFQ3FcjMNtPuC2WKk

Generate Publish/Play JWT Token with Expiration Time

Even if it's not necessary to have the payload, there are really useful options that can be used. For instance, you can use exp(expiration time) for JWT token. In order to get more information for the structure, please visit to Introduction to JWT. Anyway, let me give an example about JWT Token with Expiration Time.

As shown above, the expiration time of the token is Mar 08, 2021 02:14:08 GMT+3. It means that you can use the generated token until the expiration time. The unit of expiration time is unix timestamp. When it expires, the JWT token becomes invalid.

Generate Publish/Play JWT Token with REST API

You can also generate Publish/Play JWT Token with REST API. The Server creates JWT tokens with getJwtTokenV2 Rest Service getting streamId, expireDate and type parameters with query parameters. Service returns tokenId and other parameters. It is important that streamId and type parameters should be defined properly. Because tokenId needs to match with both streamId and type.

The sample JWT token creation service URL in Publish Scenario:

http://[IP_Address]:5080/<Application_Name>/rest/v2/broadcasts/<Stream_Id>/jwt-token?expireDate=<Expire_Date>&type=publish

The sample JWT token creation service URL in Play Scenario:

http://[IP_Address]:5080/<Application_Name>/rest/v2/broadcasts/<Stream_Id>/jwt-token?expireDate=<Expire_Date>&type=play

Expire Date format is Unix Timestamp. Check also -> https://www.epochconverter.com/

RTMP URL usage:

rtmp://[IP_Address]/<Application_Name>/streamID?token=tokenId

Here is OBS setting for the JWT Token:

Live Stream / VoD URL usage:

http://[IP_Address]/<Application_Name>/streams/streamID.mp4?token=tokenId
http://[IP_Address]/<Application_Name>/streams/streamID.m3u8?token=tokenId
http://[IP_Address]/<Application_Name>/play.html?name=streamID&playOrder=hls&token=tokenId

WebRTC Publish/Play usages:

-Playing usage: Again the JWT token parameter should be inserted to play WebSocket message. Also please have a look at the principles described in the WebRTC playing wiki page.

{
command : "play",
streamId : "stream1",
token : "tokenId",
}

-Publishing usage: Again the JWT token parameter should be inserted to publish WebSocket message. Also please have a look at the principles described in the WebRTC publishing wiki page.

{
command : "publish",
streamId : "stream1",
token : "tokenId",
}

This feature is available in Ant Media Server 2.4+ versions.

User Guide

Reference

Troubleshooting

Draft

Proposals

Clone this wiki locally