Setting per-stream authentication and parameters with SRT PASSet

SRT Publisher Assistance Security Set - or SRT PASSet - is a premium feature set of Nimble Streamer which allows extending authentication and control capabilities for SRT input.

The key capabilities of SRT PASSet are as follows:

1. Accept streamid parameter.
2. Make per-server, per-application and per-stream authentication with user and password.
3. Apply any SRT parameters to each individual stream and even individual publisher.
4. Apply allow and deny lists for IP addresses on server and stream level.
5. Manage published streams via publish control framework.

We have an article about per-user authentication for per-server and per-application processing and publish control the same way it's available for RTMP and RTSP, you can use that approach for various cases. However, more complicated cases of per-stream authorization and SRT parameters require different approach.

This article describes the following capabilities setup:

• Accepting "streamid" parameter in "<application>/<stream>" format.
• Creating configuration file for controlling per-stream settings.
• Setting server-wide allow and deny lists or IP ranges.
• Setting per-stream settings with allow/deny lists, user/password authentication and custom per-stream SRT parameters.

The key element of this feature set is a separate configuration file which has JSON-based format for describing all settings on global and per-stream level. So this article describes how this feature is enabled and set up.

A few notes

These features are applied when Nimble Streamer works as a receiver of SRT in Listen mode. Other receiving modes such as Pull and Rendezvous are not supported by PASSet feature set.

Current article assumes you have a WMSPanel account, you have a Nimble Streamer instance registered in your account and that instance is capable of receiving SRT streams via a designated port.

1. Activate Nimble Addenda

SRT PASSet is available as part of Nimble Addenda premium package and it requires a license to operate and a subscription to cover that license. That license also enables a number of other features like DRM and server-side ads insertion.

So if you don't have Addenda license yet, follow these steps:

1. Go to Settings menu and open Addenda licenses tab
2. Click on New Addenda subscription and select number of licenses, then click Next and once you see final cost, click on Pay now button.
3. Follow the payment procedure and once you complete it, you’ll see your active licenses.
4. Click on the license to see the registration procedure.
5. Log into the server which has Nimble Streamer installed and which you will use as your host.
6. Use the registration procedure to make it work.

That's it. Now all features described below will become available.

2. Set up SRT listener

In your WMSPanel account, click on Nimble Streamer -> Live Streams Settings menu and open MPEG-TS In tab.

Here you need to click on Add SRT stream button to see the following dialog.

Make the following setup:

1. Set Receive mode to Listen. This feature doesn't work for other modes.
2. Define Local IP and port. By default we recommend using 0.0.0.0 IP address.
3. Alias is a name of this setting for further usage in other setup areas. 
4. Un-check Add outgoing stream checkbox.
5. Finally, you need to add "nimble-srt-password-path" custom parameter with full path to a JSON text configuration file located on the same server where Nimble Streamer is running.

Save this setting and it will be synced to the Nimble Streamer instance within a few seconds.

Now let's look at how you can operate this JSON configuration file the path to which you've specified in listener socket settings.

3. JSON configuration file

First thing to notice is that the configuration file must have at least "read" permissions for a user which Nimble Streamer is running under.

This file is requested by Nimble Streamer every time when a new publisher is trying to connect to Nimble Streamer. So you may change the rules any time you need, either manually or via some script according to your business logic.

If the file is specified in listener settings but it doesn't exist or cannot be accessed or it has a malformed JSON then no publishers will be allowed to publish to this listener.

Here is the top-level structure of this JSON file:

{
  "publishers": {
  },
  "streams": {
  }
}

Both "publishers" and "streams" sections can be used alone, so you can define only one of them if needed.

3.1 "publishers" section 

The publishers section gives ability to define server-wide allow and deny rules for IP addresses of publishers. Those IP ranges are defined as CIDR ranges. You can define one range, several ranges or none of them for allow and deny lists.

The "deny" list defines the ranges of IPs to deny connection from. If a publisher with denied IP tries to connect then it will be rejected, and you'll find a proper line in Nimble log (see "Troubleshooting with logs" section for details).

If the "allow" list is added into the config then only publishers from allowed IP ranges will be able to connect.

Let's check an example.

{
  "publishers": {
    "deny": "127.0.0.1/32, 192.0.0.2/32",
    "allow":"127.0.0.0/24, 192.0.0.0/24"

  }
}

With these rules, all publisher from 127.0.0.0/24 and 192.0.0.0/24 allowed ranges can publish, except for 127.0.0.1 and 192.0.0.2 from deny list. Publishers from any other IPs will be rejected.

Both IPv4 and IPv6 IP addresses are supported.

If "publishers" section is not available then publishers from any IPs can publish unless something else is defined for specific stream in "streams" section.

3.2 "streams" section 

All stream which you want to allow for publishing must be described in this section.

Every stream has "allow", "deny" and "users" section. Both "allow" and "deny" sections work the same way as it's described in section 3.1. All allow/deny rules from "publishers" section will be applied first, then corresponding rules for a stream will be applied. Then if a publisher is allowed to publish then "users" section is applied.

Let's look at this example.

{
  "streams": {
    "live/stream": {
      "allow":"192.168.0.1/32",
      "users": {
        "user_id": {"passphrase": "123456789"}

       }
    }
  }
}

Here, only "live/stream" is allowed to be published into this listener, any other streams will be rejected. Also, only a publisher from 192.168.0.1 is allowed to stream, any other IP will be rejected.

The "users" section defines a list of users allowed to publish into particular stream. Each user can be assigned the SRT parameters which will be applied to that particular user.

Let's check another example.

{
  "streams": {
    "live/srtstream": {
      "allow":"127.0.0.1/32,::1/128",
      "users": {
        "srt_user": {"passphrase": "1234567890"},
        "ID_1": {"passphrase": "0987654321"}
      }
    },
    "srtlive/srtstream": {
      "allow":"127.0.0.1/32,::1/128",
      "users": {
        "srt_user": {"passphrase": "1234567890"}
      }
    }
  }
}

In this example, both "srt_user" and "ID_1" users can publish into "live/srtstream" and only "srt_user" can publish into "srtlive/srtstream".

There may be any unique "passphrase" parameter set to each individual user.

Also, any supported custom SRT parameters can be used for each user, e.g. latency, maxbw and pbkeylen.

Let's check another example:

{
  "streams": {
    "live/srtstream": {
      "users": {
        "user_1": {"passphrase": "1234567890", "latency": "2000"},
        "user_2": {"passphrase": "0987654321", "latency", "1000"}
      }
    }
}

Here you see "user_1" has SRT latency set to 2000ms and "user_2" has 1000ms latency.

3.3 Listener socket parameters vs. user parameters

If you define some SRT parameters in listener settings, they will be applied to all users unless you re-define them on user level in JSON config file.

E.g. if "latency" is set to "2000" in listener socket and then a user is set latency as "1000" then this user will connect with 1000ms latency. And if some user doesn't have "latency" parameter then it will have 2000ms latency.

This applies to all SRT custom parameters, including "passphrase".

4. Authorization options when using JSON configuration file

If you use JSON configuration file you have two options for authorizing your publishers.

4.1 Login authorization

This way you will authorize users with their respective passphrases.

Here's a JSON example:

{
  "streams": {
  "live/stream": {
    "users": {
      "user_1": {"passphrase": "0123456789"}
    }
  }
}

Your publisher can use this command to connect:

ffmpeg -re -i video.mp4 -codec copy -f mpegts pipe:1 | ./srt-live-transmit -v file://con "srt://127.0.0.1:2020?passphrase=0123456789&streamid=/live/stream?srtauth=user_1"

The "srtauth" parameter has only a user name which is listed in our config. The "passphrase" is used as a password for authorization. If you try to publish to any other stream, the publication will be rejected and you'll see a record in Nimble log. If publisher uses a user not specified in the config then it will be rejected as well.

The output application and stream will be created automatically based on "streamid" like this:

http://localhost:8080/live/stream/playlist.m3u8

If you want to pass SRT parameters, you can add them like this:

ffmpeg -re -i video.mp4 -codec copy -f mpegts pipe:1 | ./srt-live-transmit -v file://con "srt://127.0.0.1:2020?passphrase=0123456789&latency=1000&streamid=/live/stream?srtauth=user_1"

Here a publisher will pass a "latency" parameter with "1000" value.

4.2 Publish control authorization

The second option is to use publish control framework signature with user ID in it. The publish control signature is created the same way as described in section 5 of this article.

Here's a config example:

{
  "streams": {
  "live/srtstream": {
    "users": {
      "srt_user": {"passphrase": "0123456789"}
      "ID_1": {"passphrase": "0987654321"}
    }
  }
}

The publication command would be 

ffmpeg -re -i video.mp4 -codec copy -f mpegts pipe:1 | ./srt-live-transmit -v file://con "srt://127.0.0.1:2020?passphrase=0987654321&streamid=/live/srtstream?publishsign=aWQ9SURfMSZzaWduPWc5U093SGFJK2x2d3ZVd0FMMG9wcmc9PSZpcD06OjE="

If you decode base64 from publishsign you'll see "id=ID_1" and this is the user which will be taken for authorization with "passphrase" of "0987654321".

Read publish control framework overview, detailed setup description and PASSet per-user authorization setup articles to learn about full context of this control feature usage.

5. Troubleshooting with logs

We've made SRT PASSet feature as easy for you to analyse as possible.

Check logs. Nimble Streamer logs are very verbose for SRT PASSet use cases and they will include description of all errors which you may face. Read this article to see more details on server logs.

Make sure your stream to publish is described in JSON config. If you don't have respective stream there, you'll get a message in your log.

Then make sure you have a user and a password assigned to that stream.

Please check server logs in case of any problems. If you still have questions, please feel free to contact our helpdesk.

If you use Larix Broadcaster for publishing, we recommend using Larix Grove format for passing connection details including host and port, streamid, passphrase and other parameters.

Further reading

Read overview of PASSet feature set and also per-application and per-server authorization articles.

Also please take a look at Nimble Streamer SRT feature set and Softvelum SRT-powered products.