SaltyRTC WebRTC Task for JavaScript

@saltyrtc/task-webrtc"">
@saltyrtc/task-webrtc"">

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

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: mail@dbrgn.ch
  • Threema: EBEP4UCA
  • GPG: EA456E8BAF0109429583EED83578F667F2F3A5FA
• Lennart Grahl
  • Email: lennart.grahl@gmail.com
  • Threema: MSFVEW6C
  • GPG: 3FDB14868A2B36D638F3C495F98FBED10482ABA6

Coding Guidelines

• Write clean ES2015
• Favor const over let

License

MIT, see LICENSE.md.