13 unstable releases (6 breaking)

0.7.1-alpha Jan 24, 2024
0.7.0-alpha Dec 1, 2023
0.6.1-alpha Sep 22, 2023
0.6.0-alpha Jun 27, 2023
0.2.0 Nov 16, 2021

#2176 in Network programming

Download history 40209/week @ 2023-11-01 37575/week @ 2023-11-08 39055/week @ 2023-11-15 42858/week @ 2023-11-22 39351/week @ 2023-11-29 32268/week @ 2023-12-06 27406/week @ 2023-12-13 10893/week @ 2023-12-20 5165/week @ 2023-12-27 9753/week @ 2024-01-03 8278/week @ 2024-01-10 7871/week @ 2024-01-17 7035/week @ 2024-01-24 7611/week @ 2024-01-31 7120/week @ 2024-02-07 5351/week @ 2024-02-14

28,458 downloads per month

MIT license

520KB
10K SLoC

Implementation of the libp2p_core::Transport trait for WebRTC protocol without a signaling server.

Overview

 ## ICE

RFCs: 8839, 8445 See also: https://tools.ietf.org/id/draft-ietf-rtcweb-sdp-08.html#rfc.section.5.2.3

The WebRTC protocol uses ICE in order to establish a connection.

In a typical ICE setup, there are two endpoints, called agents, that want to communicate. One of these two agents can be the local browser, while the other agent is the target of the connection.

Even though in this specific context all we want is a simple client-server communication, it is helpful to keep in mind that ICE was designed to solve the problem of NAT traversal.

The ICE workflow works as follows:

  • An "offerer" determines ways in which it could be accessible (either an IP address or through a relay using a TURN server), which are called "candidates". It then generates a small text payload in a format called SDP, that describes the request for a connection.
  • The offerer sends this SDP-encoded message to the answerer. The medium through which this exchange is done is out of scope of the ICE protocol.
  • The answerer then finds its own candidates, and generates an answer, again in the SDP format. This answer is sent back to the offerer.
  • Each agent then tries to connect to the remote's candidates.

We pretend to send the offer to the remote agent (the target of the connection), then pretend that it has found a valid IP address for itself (i.e. a candidate), then pretend that the SDP answer containing this candidate has been sent back. This will cause the offerer to execute step 4: try to connect to the remote's candidate.

TCP or UDP

WebRTC by itself doesn't hardcode any specific protocol for media streams. Instead, it is the SDP message of the offerer that specifies which protocol to use. In our use case (one or more data channels), we know that the offerer will always request either TCP+DTLS+SCTP, or UDP+DTLS+SCTP.

The implementation only supports UDP at the moment, so if the offerer requests TCP+DTLS+SCTP, it will not respond. Support for TCP may be added in the future (see https://github.com/webrtc-rs/webrtc/issues/132).

## DTLS+SCTP

RFCs: 8841, 8832

In both cases (TCP or UDP), the next layer is DTLS. DTLS is similar to the well-known TLS protocol, except that it doesn't guarantee ordering of delivery (as this is instead provided by the SCTP layer on top of DTLS). In other words, once the TCP or UDP connection is established, the browser will try to perform a DTLS handshake.

During the ICE negotiation, each agent must include in its SDP packet a hash of the self-signed certificate that it will use during the DTLS handshake. In our use-case, where we try to hand-crate the SDP answer generated by the remote, this is problematic. A way to solve this is to make the hash a part of the remote's multiaddr. On the server side, we turn certificate verification off.

Dependencies

~18–60MB
~1M SLoC