This article describes publish control setup process from deployment point of view. We'll overview available scenarios and let's go through them step-by-step.
1. Set up publishing
1.1 Setup for RTMP, RTSP and WebRTC
To start implementing multi-level protection with Nimble Streamer you need to
use publishing credentials. You specify a unique username and password for a separate application which will be used for accepting published RTSP, RTMP and WebRTC streams.
 |
| Publishing applications list. |
 |
| New publishing application. |
1.2 Setup for SRT
The SRT receiver working in Listen mode needs to be set up a bit differently, please check
Setting SRT user and password authentication with SRT PASSet article for setup details.
2. Using publish signature
Now we'll start setting up publish control framework. This type of protection requires a
publish signature to be added to the connection URI used for RTSP or RTMP streaming from the source.
The signature is based on the following parameters:
- user identifier (ID);
- application name and stream name;
- password which was specified in application;
- publisher IP address (optional).
You need to specify an application in WMSPanel control UI to operate the incoming streams the publishing users will be grouped in. The application name should be the same as specified on "Start publishing" step. The password which is used in this signature should be specified in the publish control application settings via the UI.
 |
| Empty applications list for further publish control. |
To publish to Nimble Streamer, the publisher will use the URL like this:
rtsp://192.168.1.1:554/publish/stream?publishsign=aWQ9SURfMSZzaWduPW95Zi9YVHBLM0c3QkQ4SmpwVnF1VHc9PSZpcD0xMjcuMC4wLjE=
For RTMP it will be:
rtmp://192.168.5.5:1935/publish?publishsign=aWQ9SURfMSZzaWduPW95Zi9YVHBLM0c3QkQ4SmpwVnF1VHc9PSZpcD0xMjcuMC4wLjE=/stream
For SRT you will define publisher as show in the following example:
ffmpeg -re -i video.mp4 -codec copy -f mpegts pipe:1 | ./srt-live-transmit -v file://con "srt://127.0.0.1:2020?streamid=/live/srtstream?publishsign=aWQ9SURfMSZzaWduPVQ3SzVlMkMySlRxRExmSTdybVdibVE9PSZpcD0xMjcuMC4wLjE="
For WebRTC it will be:
https://your_host/live/whip?publishsign=aWQ9SURfMSZzaWduPW95Zi9YVHBLM0c3QkQ4SmpwVnF1VHc9PSZpcD0xMjcuMC4wLjE=
Here, a
publishsign is the signature for incoming RTSP or RTMP stream.
Check an
example of code for generating a signature in our github repo.
The signature is added in URI either manually or via your own application business logic, this is up to a developer to decide on that.
When the user starts publishing the stream, the media server will
check publish signature and if this signature
does not match the calculated signature, then the user stream
will not pass.
At this step the publish control is very similar to the
hotlinking protection.
You may skip the signature in case you handle your authorization in some other way. Click the "Signature-free mode" checkbox in "Add application settings" dialog (see screenshot above) to disable the signature check described above.
3. Using publish authorization handler
You can get further control of the incoming streams during connection time. For this case you need to
create a handler application and specify its URL in the control UI in "Control" -> "Publish control" menu.
The handler is an
HTTP application which is able to process POST requests and return the response according to your business logic. If you don't specify the handler URL then Publish control framework will not try to call the handler. This is done to allow debugging the signature-checking mechanism described above.
 |
| Publish control handler URL setup. |
Besides handler URL, you can set up the grouping interval for the incoming streams. The handler is called with some timeout to aggregate several requests in one. This allows avoiding the resources waste in case of frequent calls.
Nimble publish control passes the client signature to the handler. As a response to the request, the handler must
return the status and Nimble Streamer acts accordingly to
allow or deny the connection, based on the status received from the handler.
The
sample code of the handler is available in our github repo. It takes the call from Nimble and returns proper response. The call is a POST request with "Content-type" field of "application/json".
Here's an example of request:
{"PublishAuthRequest":[{"seq":"1", "id":"ID_1", "ip":"192.168.1.1","stream":"publish/stream"},{"seq":"2", "id":"ID_2","ip":"192.168.1.2","stream":"publish/stream2"}]}
Here you can see the following fields.
- seq - a sequence number, which is serial number of an entry; it will be used in a response.
- id - publisher ID within your business logic; each publisher may use several devices while having same user account so this field may be useful for block duplicate streams as example.
- ip - the IP address of the publisher.
- stream - the URI of the stream which is being published.
A response will contain statuses of each sequence - either success or fail. Here is an example:
{"PublishAuthResponse":[{"seq":"1", "status":"success"},{"seq":"2", "status":"fail"}]}
You also noticed the "Allow by default" check box in application settings on "Using publish signature" step. If the handler in not available or sequence number is not specified, and this checkbox is turned on, then incoming streams will not be blocked. If it's unchecked then the stream is blocked.
4. Controlling streaming process
With publish control you can manipulate RTSP and RTMP streams not only at
connection time, but also
during the streaming process as well when the user is already connected and streaming. To use this capability, you need to create a controller app which will
request Nimble with any frequency
to identify which users still publish their streams. If you
need to stop certain streaming session then this controller calls Nimble, specifies the session key and this stream will be
blocked immediately.
4.1 Working with Nimble API
All operations described below are made via
Nimble Streamer control API. Please refer to the reference to see how it can be used. First of all, please check
how to enable API. You may also want to
make authorized requests.
When API is enabled, you can start working with it from your controller application. There are two steps to deny unwanted sessions from publishing. First one is to get list of sessions and the second one is to send list of blocked sessions.
4.2 Request sessions from Nimble
To get info about all current published streams you need to call the following method via GET request from your controller app:
/manage/publish_control/status
Here is how Nimble Streamer responds with sessions IDs.
{"PublishControlStatus":[{"key":"1", "id":"ID_1", "ip":"192.168.1.1","stream":"publish/stream"}, {"key":"2", "id":"ID_2", "ip":"192.168.1.2","stream":"publish/stream2"}]}
Here are the response fields:
- key - session key.
- id - publisher ID within your business logic.
- ip - the IP address of the publisher.
- stream - the URI of the stream which is being published.
With that information you can now make decisions about denying some streams.
4.3 Block designated sessions
Now you need to call Nimble API with list of blocked sessions. It's a POST request to the following URI:
/manage/publish_control/deny
The body of this message will contain the list of denied sessions, like this:
{"PublishControlDenyRequest":["1", "2"]}
Here, 1 and 2 are the session key. The response is from Nimble would be:
{"PublishControlDenyResponse":{"status":"success"}
Now those sessions are blocked.
