SaltyRTC WebRTC Task for JavaScript

This is a SaltyRTC WebRTC task version 1 implementation for JavaScript (ES5 / ES2015), written in TypeScript.

:warning: Note: The SaltyRTC client libraries are in maintenance mode. They will still receive bugfixes and regular maintenance, but if you want to start using these libraries, be prepared that you will need to take over maintenance at some point in time. (If you are interested in maintaining the libraries, please let us know, our e-mails are in the README, section "Security".)

Installing

Via npm

You can install this library via npm:

npm install --save @saltyrtc/task-webrtc @saltyrtc/client

Usage

To create the task instance, you need to use the WebRTCTaskBuilder instance which can be used to configure the task before creating it.

The below configuration represents the default values chosen by the builder as if you had not configured the builder and just called .build() directly.

const task = new WebRTCTaskBuilder()
    .withLoggingLevel('none')
    .withVersion('v1')
    .withHandover(true)
    .withMaxChunkLength(262144)
    .build();

To send offers, answers and candidates, use the following task methods:

• task.sendOffer(offer: RTCSessionDescriptionInit): void
• task.sendAnswer(answer: RTCSessionDescriptionInit): void
• task.sendCandidate(candidate: RTCIceCandidateInit): void
• task.sendCandidates(candidates: RTCIceCandidateInit[]): void

You can register and deregister event handlers with the on, once and off methods:

task.on('candidates', (e) => {
    for (let candidateInit of e.data) {
        pc.addIceCandidate(candidateInit);
    }
});

The following events are available:

• offer(saltyrtc.tasks.webrtc.Offer): An offer message was received.
• answer(saltyrtc.tasks.webrtc.Answer): An answer message was received.
• candidates(saltyrtc.tasks.webrtc.Candidates): A candidates message was received.
• disconnected(number): A previously authenticated peer disconnected from the signaling server.

Data Channel Crypto Context

The task provides another security layer for data channels which can be leveraged by usage of a DataChannelCryptoContext instance. To retrieve such an instance, call:

const context = task.createCryptoContext(dataChannel.id);

You can encrypt messages on the sending end in the following way:

const box = context.encrypt(yourData);
dataChannel.send(box.toUint8Array());

On the receiving end, decrypt the message by the use of the crypto context:

const box = saltyrtcClient.Box.fromUint8Array(message, DataChannelCryptoContext.NONCE_LENGTH);
const yourData = context.decrypt(box);

Note, that you should not use a crypto context for a data channel that is being used for handover. The task will take care of encryption and decryption itself.

Handover

Before initiating the handover, the application needs to fetch the SignalingTransportLink instance which contains the necessary information to create a data channel.

const link = task.getTransportLink();

const dataChannel = peerConnection.createDataChannel(link.label, {
    id: link.id,
    negotiated: true,
    ordered: true,
    protocol: link.protocol,
});

Note that the data channel used for handover must be created with the label and parameters as shown in the above code snippet.

Now that you have created the channel, you need to implement the SignalingTransportHandler interface. Below is a minimal handler that forwards the necessary events and messages to the created data channel.

const handler = {
    get maxMessageSize() {
        return peerConnection.sctp.maxMessageSize;
    },
    close() {
        dataChannel.close();
    },
    send(message) {
        dataChannel.send(message);
    },
}

Furthermore, you have to bind all necessary events in order to connect the data channel to the SignalingTransportLink.

dataChannel.onopen = () => task.handover(handler);
dataChannel.onclose = () => link.closed();
dataChannel.binaryType = 'arraybuffer';
dataChannel.onmessage = (event) => link.receive(new Uint8Array(event.data));

The above setup will forward the close event and all messages to the task by the use of the SignalingTransportLink. On open, the handover will be initiated.

To be signalled once the handover is finished, you need to subscribe to the handover event on the SaltyRTC client instance.

Testing

1. Preparing the Server

First, clone the saltyrtc-server-python repository.

git clone https://github.com/saltyrtc/saltyrtc-server-python
cd saltyrtc-server-python

Then create a test certificate for localhost, valid for 5 years.

openssl req \
   -newkey rsa:1024 \
   -x509 \
   -nodes \
   -keyout saltyrtc.key \
   -new \
   -out saltyrtc.crt \
   -subj /CN=localhost \
   -reqexts SAN \
   -extensions SAN \
   -config <(cat /etc/ssl/openssl.cnf \
     <(printf '[SAN]\nsubjectAltName=DNS:localhost')) \
   -sha256 \
   -days 1825

You can import this file into your browser certificate store. For Chrome/Chromium, use this command:

certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n saltyrtc-test-ca -i saltyrtc.crt

Additionally, you need to open chrome://flags/#allow-insecure-localhost and enable it.

In Firefox the easiest way to add your certificate to the browser is to start the SaltyRTC server (e.g. on localhost port 8765), then to visit the corresponding URL via https (e.g. https://localhost:8765). Then, in the certificate warning dialog that pops up, choose "Advanced" and add a permanent exception.

Create a Python virtualenv with dependencies:

python3 -m virtualenv venv
venv/bin/pip install .[logging]

Finally, start the server with the following test permanent key:

export SALTYRTC_SERVER_PERMANENT_KEY=0919b266ce1855419e4066fc076b39855e728768e3afa773105edd2e37037c20 # Public: 09a59a5fa6b45cb07638a3a6e347ce563a948b756fd22f9527465f7c79c2a864
venv/bin/saltyrtc-server -v 5 serve -p 8765 \
    -sc saltyrtc.crt -sk saltyrtc.key \
    -k $SALTYRTC_SERVER_PERMANENT_KEY

2. Running Tests

To compile the test sources, run:

npm run rollup_tests

Then simply open tests/testsuite.html in your browser!

Alternatively, run the tests automatically in Firefox and Chrome:

npm test

Security

Responsible Disclosure / Reporting Security Issues

Please report security issues directly to one or both of the following contacts:

• Danilo Bargen
  • Email: [email protected]
  • Threema: EBEP4UCA
  • GPG: EA456E8BAF0109429583EED83578F667F2F3A5FA
• Lennart Grahl
  • Email: [email protected]
  • Threema: MSFVEW6C
  • GPG: 3FDB14868A2B36D638F3C495F98FBED10482ABA6

Coding Guidelines

• Write clean ES2015
• Favor const over let

License

MIT, see LICENSE.md.