Description

Gosling is a protocol and reference library implementation of said protocol. The protocol enables building peer-to-peer applications over the tor network whereby each node's connection has the following properties:

• anonymous: the real identity of a node is hidden using tor onion services
• secure: all network traffic is end-to-end encrypted by virtue of using tor and tor onion services
• private+meta-data resistant: nodes have fine control over their visibility/online-status to other nodes

It is meant to generalize (and improve upon) the authentication scheme Ricochet-Refresh clients use to verify to each other's identity. Details can be found in the protocol specification here:

• Gosling Protocol

Dependencies

Gosling currently has the following required build dependencies:

• cmake >= 3.17
• rust >= 1.63.0

Cargo will automatically download and build the required Rust crates. The list of current dependencies can be found in each crate's Cargo.toml file:

• honk-rpc
• tor-interface
• gosling
• cgosling

Optional Dependencies

Gosling has a number of dependencies that are not needed to build the core library, but are needed for bindings, examples and tests:

• boost >= 1.66 (for C++ hello_world example and tests)
• ncurses (for C++ hello_world example)
• Java JDK (for Java JNI bindings)

The following optional dependencies consumed as git submodules:

• Catch2 (for C++ tests)
• nlohmann::json (for C++ hello_world example)

They can be initialised by:

$ git submodule update --init

The coverage- make targets have the following additional dependencies:

• cargo-tarpaulin

The fuzz- make targets have the following additional dependencies:

• rust nightly (for -z rustc compiler flag)
• cargo-fuzz
• libfuzzer

The website- make target has the following additional dependencies:

• doxygen
• graphviz
• mustache
• pandoc
• plantuml
• tidy

The format make target has the following additional dependencies:

• clang-format

The lint make target has the following additional dependencies:

• cppcheck
• jq

Building

The reference implementation is a work-in-progress and the API is not yet fully stable.

The following make targets are supported:

• Misc

  • clean - deletes all build artifacts in out and dist directories
  • format - runs cargo fmt on Rust source and clang-format on the C++ source
  • lint - runs cargo clippy on the Rust source and cppcheck on the C++ source

• Config Targets: creates Makefiles for different build types

  • config-debug - Debug CMake build type: no optimization, asserts enabled, debug symbols generated; build artifacts placed in out/debug
  • config-release - Release Cmake build type: optimize for speed, asserts disabled, debug symbols stripped; build artifacts placed in out/release
  • config-rel-with-deb-info - RelWithDebInfo CMake build type: optimize for speed, asserts disabled, debug symbols generated; build artifacts placed in out/rel-with-deb-info
  • config-min-size-rel - MinSizeRel CMake build type: optimize for size, asserts disabled, debug symbols stripped; build artifacts placed in out/min-size-rel

  Further information about CMake build types can be found in the CMake documentation:

  • https://cmake.org/cmake/help/v3.16/variable/CMAKE_BUILD_TYPE.html

• Build Targets: build gosling crates, cgosling, and language bindings

  • debug
  • release
  • rel-with-deb-info
  • min-size-rel

• Install Targets: build and deploy cgosling headers, static+shared libraries, bindings, and examples to dist/*

  • install-debug
  • install-release
  • install-rel-with-deb-info
  • install-min-size-rel

• Test Targets: build and run all tests using real tor daemon

  • test-debug
  • test-release
  • test-rel-with-deb-info
  • test-min-size-rel

• Offline Test Targets: build and run all tests using mock offline tor daemon

  • test-offline-debug
  • test-offline-release
  • test-offline-rel-with-deb-info
  • test-offline-min-size-rel

• Rust Test Coverage: build and run Rust tests and calculate code coverage using real tor daemon

  • coverage-debug
  • coverage-rel-with-deb-info

• Rust Offline Test Coverage: build and run Rust tets and calculate code coverage using mock offline tor daemon

  • coverage-offline-debug
  • coverage-offline-rel-with-deb-info

• Fuzz Targets: run cargo-fuzz tests

  • fuzz-honk-rpc-session - honk-rpc session
  • fuzz-tor-interface-crypto - tor-interface cryptography
  • fuzz-gosling-identity-server - gosling identity server protocol
  • fuzz-gosling-identity-client - gosling identity client protocol
  • fuzz-gosling-endpoint-server - gosling endpoint server protocol
  • fuzz-gosling-endpoint-client - gosling endpoint client protocol
  • fuzz cgosling - cgosling C FFI

• Website Targets: build pages, Rust crate documentation, C/C++ doxygen documentation, and Rust test coverage; websites deployed to dist/*

  • install-pages-debug
  • install-pages-rel-with-deb-info

Acknowledgements

Creation of innovative free software needs support. We thank the NGI Assure Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 957073