Repository files navigation

A WebRTC and ORTC library with a small footprint.

The following list represents all features that are planned for RAWRTC.Features with a check mark are already implemented.

• ICE[draft-ietf-ice-rfc-5245bis-08]
  • Trickle ICE[draft-ietf-ice-trickle-07]
  • IPv4
  • IPv6
  • UDP
  • TCP
• STUN[RFC 5389]
  • UDP
  • TCP
  • TLS over TCP
  • DTLS over UDP[RFC 7350]
• TURN[RFC 5766]
  • UDP
  • TCP
  • TLS over TCP
  • DTLS over UDP[RFC 7350]
• Data Channel
  • DCEP[draft-ietf-rtcweb-data-protocol-09]
  • SCTP-based[draft-ietf-rtcweb-data-channel-13]
• API
  • WebRTC C-API based on theW3C WebRTC API and[draft-ietf-rtcweb-jsep-24]
  • ORTC C-API based on theW3C CG ORTC API

1. Does this use multiple threads?

   No, this library is single-threaded and uses an event loop underneath.

2. Can I use it in a threaded environment?

   Yes. Just make sure you're always calling it from the same thread the eventloop is running on, or eitherlock/unlock the event loop threadoruse the message queues provided by re to exchange data withthe event loop thread. However, it is important that you only run onereevent loop in one thread.

3. I only want a data channel implementation for my SFU!

   Check outRAWRTCDC.

The following tools are required:

• git
• ninja >= 1.5
• meson >= 0.48.0
• pkg-config (pkgconf for newer FreeBSD versions)
• SSL development libraries (libssl-dev on Debian,openssl on OSX andFreeBSD)

cd<path-to-rawrtc>mkdir buildmeson buildcd buildninja

RAWRTC provides a lot of tools that can be used for quick testing purposes andto get started. Let's go through them one by one. If you just want to check outdata channels and browser interoperation, skip to thepeer-connection tool section which uses the WebRTC API orto thedata-channel-sctp tool section which uses theORTC API.

Most of the tools have required or optional arguments which are shared amongtools. Below is a description for the various shared arguments:

Whether the peer is going to create an offer. Provide1 to create an offerimmediately or0 to create an answer once the remote offer has beenprocessed.

Only used by WebRTC API tools.

Determines the ICE role to be used by the ICE transport, where0 meanscontrolled and1 meanscontrolling.

Only used by ORTC API tools.

The port number the internal SCTP stack is supposed to use. Defaults to5000.

Note: It doesn't matter which port you choose unless you want to be able todebug SCTP messages. In this case, it's easier to distinguish the peers bytheir port numbers.

Only used by ORTC API tools.

If supplied, one or more specific ICE candidate types will be enabled and allother ICE candidate types will be disabled. Can be one of the followingstrings:

• host
• srflx
• prflx
• relay

Note that this has no effect on the gathering policy. The candidates will begathered but they will simply be ignored by the tool.

If not supplied, all ICE candidate types are enabled.

API: ORTC

The ICE gatherer tool gathers and prints ICE candidates. Once gathering iscomplete, the tool exits.

Usage:

ice-gatherer

API: ORTC

The ICE transport loopback tool starts two ICE transport instances whichestablish an ICE connection. Once you see the following line for both clientsA andB, the ICE connection has been established:

(<client>) ICE transport state: connected

Usage:

ice-transport-loopback [<ice-candidate-type> ...]

API: ORTC

The DTLS transport loopback tool starts two DTLS transport instances whichwork on top of an established ICE transport connection.

To verify that the DTLS connection establishes, wait for the following line forboth clientsA andB:

(<client>) DTLS transport state change: connected

Usage:

dtls-transport-loopback [<ice-candidate-type> ...]

API: ORTC

The SCTP redirect transport tool starts an SCTP redirect transport on top of anestablished DTLS transport to relay SCTP messages from and to a third party.This tool has been developed to be able to test data channel implementationswithout having to write the required DTLS and ICE stacks. An example of such atesting tool isdctt which uses the kernel SCTP stack of FreeBSD.

Building:

This tool is not built by default. You can enable building it in the followingway:

cd<path-to-rawrtc>/buildmeson configure -Dsctp_redirect_transport=trueninja

Usage:

sctp-redirect-transport <0|1 (ice-role)> <redirect-ip> <redirect-port>                        [<sctp-port>] [<maximum-message-size>]                        [<ice-candidate-type> ...]

Special arguments:

• redirect-ip: The IP address on which the external SCTP stack is listening.
• redirect-port The port on which the external SCTP stack is listening.
• maximum-message-size: The maximum message size of a data channel messagethe external SCTP stack is able to handle.0 indicates that messages ofarbitrary size can be handled. Defaults to0.

API: ORTC

The data channel SCTP loopback tool creates several data channels on top of anabstracted SCTP data transport. As soon as a data channel is open, a messagewill be sent to the other peer. Furthermore, another message will be sent on aspecific channel after a brief timeout.

To verify that a data channels opens, wait for the following line:

(<client>) Data channel open: <channel-label>

The tool will send some large (16 MiB) test data to the other peer depending onthe ICE role. We are able to do this because RAWRTC handles data channelmessages correctly and does not have a maximum message size limitation comparedto most other implementations (check outthis article for a detailed explanation).

Usage:

data-channel-sctp-loopback [<ice-candidate-type> ...]

API: ORTC

The data channel SCTP tool creates several data channels on top of anabstracted SCTP data transport:

• A pre-negotiated data channel with the labelcat-noises and the id0that is reliable and ordered. In the WebRTC JS API, the channel would becreated by invoking:

  peerConnection.createDataChannel('cat-noises',{ordered:true,id:0});

• A data channel with the labelbear-noises that is reliable but unordered.In the WebRTC JS API, the channel would be created by invoking:

  peerConnection.createDataChannel('bear-noises',{ordered:false,maxRetransmits:0});

To establish a connection with another peer, the following procecure must befollowed:

1. The JSON blob afterLocal Parameters: must be pasted into the other peeryou want to establish a connection with. This can be either a browserinstance that uses theWebRTC-ORTC browser example tool or another instanceof this tool.

2. The other peer's local parameters in form of a JSON blob must be pasted intothis tool's instance.

3. Once you've pasted the local parameters into each other's instance, the peerconnection can be established by pressingEnter in both instances (presstheStart button in the browser).

The tool will send some test data to the other peer depending on the ICE role.However, the browser tool behaves a bit differently. Check the log output ofthe tool instances (console output in the browser) to see what data has beensent and whether it has been received successfully.

In the browser, you can use the created data channels by accessingpeer.dc['<channel-name>'], for example:

peer.dc['example-channel'].send('RAWR!')

Usage:

data-channel-sctp <0|1 (ice-role)> [<sctp-port>] [<ice-candidate-type> ...]

API: ORTC

The data channel SCTP streamed tool is the counterpart to thenormal datachannel SCTP tool but uses the streaming mode.Be aware this tool and thestreaming mode is currently experimental and incomplete.

The necessary peer connection establishment steps are identical to the onesdescribed for thedata-channel-sctp tool.

Usage:

data-channel-sctp-streamed <0|1 (ice-role)> [<sctp-port>]                           [<ice-candidate-type> ...]

API: ORTC

The data channel SCTP echo tool behaves just like any other echo server: Itechoes received data on any data channel back to the sender.

The necessary peer connection establishment steps are identical to the onesdescribed for thedata-channel-sctp tool.

Usage:

data-channel-sctp-echo <0|1 (ice-role)> [<sctp-port>]                       [<ice-candidate-type> ...]

API: ORTC

The data channel SCTP throughput tool allows you to test throughput by sendingone or more message. It will report the amount of seconds elapsed and thethroughput in Mbit/s.

The necessary peer connection establishment steps are identical to the onesdescribed for thedata-channel-sctp tool. However,be aware that this tool has no browser counterpart at the moment, so it onlymakes sense to use two instances of this tool for throughput testing.

Usage:

data-channel-sctp-throughput <0|1 (ice-role)> <message-size> [<n-times>]                             [<sctp-port>] [<ice-candidate-type> ...]

Special arguments:

• message-size: Is the message size in bytes used for throughput testing. Thecontrolling peer will determine the message size for both peers, so thisargument is being ignored for the controlled peer.
• n-times: Is the amount of times the message will be sent. Again, thisvalue is being ignored for the controlled peer.

API: WebRTC

The peer connection tool creates a peer connection instance and several datachannels:

• A pre-negotiated data channel with the labelcat-noises and the id0that is reliable and ordered. In the JS API, the channel would be createdby invoking:

  peerConnection.createDataChannel('cat-noises',{ordered:true,id:0});

• A data channel with the labelbear-noises that is reliable but unordered.In the WebRTC JS API, the channel would be created by invoking:

  peerConnection.createDataChannel('bear-noises',{ordered:false,maxRetransmits:0});

To establish a connection with another peer, the following procecure must befollowed:

1. If the peer is taking theoffering role, the generated JSON blob thatcontains theoffer SDP must be pasted into the other peer you want toestablish a connection with. This can be either a browser instance that usestheWebRTC browser example tool or another instance ofthis tool. In case it is a browser instance, press theStart button andpaste the data directly into the text area belowPaste remote description:. In case it is another instance of this tool,paste the data into the other peer's console and pressEnter.

2. The peer who takes theanswering role now generates a JSON blob as wellthat contains theanswer SDP. It must be pasted into the other browserinstance or tool instance as described in the previous step.

3. The peer connection should be established automatically onceoffer andanswer have been exchanged and applied.

The tool will send some test data to the other peer depending on whether or notit took theoffering role. However, the browser tool behaves a bitdifferently. Check the log output of the tool instances (in the browser, eitheropen the console log or check out the live log on the right side) to see whatdata has been sent and whether it has been received successfully.

In the browser, you can use the created data channels by accessingpc.dcs['<channel-name>'] in the console log, for example:

pc.dcs['cat-noises'].send('RAWR!')

Usage:

peer-connection <0|1 (offering)> [<ice-candidate-type> ...]

When creating a pull request, it is recommended to runformat-all.sh toapply a consistent code style.