Stream Security Documentation - mekya/antmedia-doc GitHub Wiki

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

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

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

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.

Create a Token in Publish&Play Scenario

The Server creates tokens with getToken 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/broadcast/getToken?id=<Stream_Id>&expireDate=<Expire_Date>&type=publish

The sample token creation service URL in Play Scenario:

http://[IP_Address]:5080/<Application_Name>/rest/broadcast/getToken?id=<Stream_Id>&expireDate=<Expire_Date>&type=play

RTMP URL usage:

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

Live Stream / VoD URL usage:

http://[IP_Address]/<Application_Name>/streams/streamID.mp4?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.

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",
}

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

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

settings.hashControlPublishEnabled=false
settings.hashControlPlayEnabled=false
tokenHashSecret=

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.

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.

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

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

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

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.

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.

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.allowedPublisherIps in AMS_DIR/webapps/<App_Name>/WEB_INF/red5.properties file with the allowed IP addresses.

Example: settings.allowedPublisherIps=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.