saltyrtc-client-rs

Asynchronous SaltyRTC client implementation for Rust.

: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".)

SaltyRTC is an end-to-end encrypted signalling protocol. It offers to freely choose from a range of signalling tasks, such as setting up a WebRTC or ORTC peer-to-peer connection, or using the WebSocket based signaling server as a relay. SaltyRTC is completely open to new and custom signalling tasks for everything feasible.

Docs

Testing

Setup

The integration tests currently expect a SaltyRTC Server instance to run on localhost:8765.

First, create a test certificate for localhost.

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

Create a Python virtualenv with dependencies:

python3 -m virtualenv venv
venv/bin/pip install saltyrtc.server[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

Before you run the client tests, symlink the saltyrtc.crt file into your saltyrtc-client-rs directory.

Unit Tests

To run the testsuite:

cargo test

Fuzz Testing

To run fuzz tests, first install cargo-fuzz:

cargo install cargo-fuzz

Then run the fuzzer against a target:

cargo +nightly fuzz run <target>

You can list all targets with cargo fuzz list.

Example Client

There is an example chat client at examples/chat/main.rs. You can invoke it both as initiator or responder. Note that you need to have libncurses installed on your system for the chat example to work.

If you start the chat as initiator, the signaling path and auth token will be randomly generated and printed:

$ cargo run --example chat -- initiator
INFO:saltyrtc_client::crypto: Generating new key pair
INFO:saltyrtc_client::crypto: Generating new auth token

******************************
Connecting as Initiator

Signaling path: f637d7fff53defe8db111b17b2c445f7888a83c13dc40d7ff8449f700910f01f
Auth token: 0e94b54a49e4ec7f4398ec9bec5d4359cca810f7eca31704e6c0afadd54a7818

To connect with a peer:
cargo run --example chat -- responder \
    --path f637d7fff53defe8db111b17b2c445f7888a83c13dc40d7ff8449f700910f01f \
    --auth-token 0e94b54a49e4ec7f4398ec9bec5d4359cca810f7eca31704e6c0afadd54a7818
******************************

INFO:saltyrtc_client: Connected to server as Initiator
...

Simply copy that command in the second half of the output to another terminal to connect to the initiator with a responder.

To see all options, use cargo run --example chat -- initiator --help and cargo run --example chat -- responder --help.

The chat example will log to a file called chat.<role>.log.

Note: The tests currently expect a SaltyRTC Server instance to run on localhost:8765.

Msgpack Debugging

If you enable the msgpack-debugging compile flag, you'll get direct msgpack analysis URLs for all decoded messages in your TRACE level logs.

cargo build --features 'msgpack-debugging'

You can customize that URL prefix at compile time using the MSGPACK_DEBUG_URL env var. This is the default URL:

MSGPACK_DEBUG_URL='https://msgpack.dbrgn.ch/#base64='

Release Signatures

Release commits and tags are signed with the Threema signing key (E7ADD9914E260E8B35DFB50665FDE935573ACDA6).

FFI

You can find C FFI bindings in the ffi subdirectory of this source repository.

Note: The FFI bindings are currently incomplete and blocked by rust-lang/rust#36342.

Dependency Patching

The following patches in Cargo.toml are recommended to solve problems in transitive dependencies:

[patch.crates-io]
traitobject = { git = "https://github.com/philip-peterson/destructure_traitobject", rev = "d49b0af9087b3b7848d19d5baae43948ebc7fb9d" }

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.