WebRTC Signaling in Nabto Edge

As discussed in the Introduction, WebRTC connections do not define a way to transfer signaling messages between peers to establish a connection. This guide describes the features of the Nabto Edge WebRTC Signaling Protocol. It also describes how this is implemented and the security implications in browsers where native Nabto Edge Connections are not possible.

WebRTC Signaling

To establish a connection, WebRTC requires Offers, Answers, and ICE candidates to be sent between peers in signaling messages. How these messages are transported between the peers are not specified by WebRTC as it requires a pre-established connection between the peers. Nabto Edge WebRTC defines a protocol for signaling messages on a Nabto Edge Stream. This protocol is fully implemented in the Nabto provided libraries.

In addition to transmitting the required data, the Nabto Edge signaling protocol supports TURN server credentials, Track IDs, and Track Error Reporting as outlined in the following.

TURN server credentials

The embedded device can query the Nabto Edge Basestation for credentials. If WebRTC is not able to establish a Peer-to-Peer connection, these credentials can be used to gain access to a Nabto provided TURN server for a relay connection. The client can use the signaling protocol to query the device for these credentials.

Currently, these credentials will grant access to Nabto hosted TURN servers. Relay traffic using these servers will incur relay traffic charges in the same way native Nabto Edge Connections do when using relay connections. Customer hosted TURN server support is in the Nabto Roadmap.

Track IDs

Each track in a WebRTC connection, is identified by a media identifier (the mid attribute) which in principle can be any string. However, most implementations do not provide access to this. For this reason, in the Nabto Edge WebRTC APIs, a track ID is specified when adding a media track. A mapping between the mid and this track ID is then sent along with the WebRTC signaling messages. In applications, this means the tracks can be identified consistently across all platforms. In most cases, the Nabto APIs hide all these details from the application so developers only have to consider the track ID. Track IDs are especially useful in applications where multiple video sources are available.

Track Errors

In WebRTC, when a peer adds a track to the connection, the details of the track must be negotiated with the other peer. If this negotiation fails, WebRTC does not specify a way to report the error to the other peer. Nabto Edge handles these errors either by CoAP negotiation or by reporting errors through the signaling protocol.

The most common use case for using WebRTC in Nabto Edge is a client wanting to receive a video feed from a device. And, commonly, the device only supports a single codec for encoding its video feeds, whereas clients often support a wide array of codecs. So to simplify the negotiation, it is preferred for the client to make a CoAP request to the device asking it to add the media tracks to the WebRTC connection. This way, the device does not need to sort through all codecs supported by the client, but can simply add the one it supports. This also means if an error occurs, the device can choose not to add the track and return an error response to the CoAP request.

In some cases, tracks must be added by the client (eg. when Alexa is the client). In such cases, if the device is not able to satisfy the requested track, it can set an error on the track which is sent to the client using the signaling protocol. Based on this, the client is able to present a proper error to the user.

Browser Support

Though browsers natively supports WebRTC, it cannot make a Nabto Edge connection for the signaling messages. For this case, Nabto Edge provides a Signaling Service which browsers can connect to using Websockets. The Signaling Service will then create a Nabto Edge Connection to the device on the browsers behalf. Nabto provides a javascript library handling all the signaling. This allows browser clients to establish WebRTC connections to a device.

Since the browser still does not have a Nabto Edge Connection to the device, Nabto Edge provides mechanisms for making a virtual Nabto Edge Connection through the WebRTC connection which can be used for CoAP requests. Nabto Edge Streaming through WebRTC data channels will be added in the future (in the javascript library. Device support already exist). This allows browser implementations to follow the recommendation of adding media tracks using CoAP requests.

In WebRTC connections, the peers are authenticated by validating each others fingerprints exchanged by the signaling messages. Since browsers relays signaling messages through the Nabto Edge Signaling Service, the browser should authenticate the connection after it has been established using the fingerprint validation mechanism described below. Doing this ensures the Signaling Service does not become a trusted entity.

Similarly, the browser changes its fingerprint for each connection, so the device cannot authorize the connection using Public Key Authentication as used in IAM Pairing. So browsers should authorize their connection using an oAuth token or a Password as described in the Session Authentication guide.

Session Authentication

In a standard Nabto Edge Connection, the client and device has previously been Paired. This means, when they have established their DTLS connection, they can each calculate the fingerprint of the others public key. The device can then compare the client fingerprint to its users list in the IAM module and the client can compare the device fingerprint against whatever bookmarking system it has implemented.

In WebRTC, connections create new encryption keys every time they are established. This means the two peers cannot be Paired and store each others fingerprints for future connections. The WebRTC fingerprints are exchanged and validated during the signaling process. This means if the signaling channel is validated and trusted, the WebRTC connection will also be valid. For mobile Apps where the signaling channel is a Paired Nabto Edge Connection between the client and device, they can validate the fingerprints of the Nabto Edge connection, and the WebRTC fingerprints do not need to be revalidated.

If the WebRTC connection was established through the Nabto Edge Signaling Service or the client and device was not Paired, they must authenticate the connection in another way. The client can be authenticated by the device using IAM Session Authentication. The device can be authenticated by the client using the Fingerprint Validation mechanism described below.

The Fingerprint Validation mechanism validates that the device is in possession of the encryption keys it normally uses for Nabto Edge Connections. The validation is based on the public key fingerprint. This is the same fingerprint that has been configured in the Nabto Cloud Console for the device and is also the fingerprint clients normally stores in their bookmarks.

In the validation, the client makes a CoAP request to the device with a nonce. The device will then generate a JWT using its encryption key and return it to the client for validation.

In the javascript library validating the fingerprint is a simple function call after the WebRTC connection has been established. Other client libraries does not implement this feature as they are encouraged to authenticate their preexisting Nabto Edge Connection.