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 is built using cmake. By default, only the cgosling static libraries, shared libraries, and C/C++ headers are built. A typical development setup would be:
# Create out-of-tree build directory
mkdir build && cd build
# Generate Makefiles
cmake .. -DCMAKE_INSTALL_PREFIX=../dist -DCMAKE_BUILD_TYPE=Release
# Build default targets
make
# Install to ../dist
make installYou must explicitly set the CMAKE_BUILD_TYPE variable. The usual CMake build types are supported and mapped to equivalent cargo flags:
- Debug: no optimization, asserts enabled, debug symbols generated
- Release: optimize for speed, asserts disabled, debug symbols stripped
- ReleaseWithDebInfo: optimize for speed, asserts disabled, debug symbols generated
- MinSizeRel: optimize for size, asserts disabled, debug symbols stripped
See CMake's CMAKE_BUILD_TYPE documentation for additional information.
Tests and examples depend on additional libraries consumed as git submodules. They can be initialised by:
$ git submodule update --initGosling currently has the following required build dependencies:
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:
Build-time configuration options for features which may be conditionally enabled or disabled.
cmake -DENABLE_MOCK_TOR_PROVIDER=ONEnable the mock TorProvider implementation. This TorProvider is in-process and local only; it does not connect to the internet or the real Tor Network. It is only useful for testing. This option is ON by default.
cmake -DENABLE_LEGACY_TOR_PROVIDER=ONEnable the (for now, default) c-tor daemon TorProvider implementation. This allows Gosling to connect to the Tor Network using the legacy c-tor daemon. This option is ON by default.
cmake -DENABLE_ARTI_CLIENT_TOR_PROVIDER=ONEnable the arti-client TorProvider implementation. This allows Gosling to connect to the Tor Network using the experimental Rust arti-client crate. This option is OFF by default and is not for production use.
The following additional dependencies are required for this configure option:
Additional optional bindings, tests, and documentation can be enabled with the following cmake options. Each of these options are OFF by default.
cmake -DENABLE_TESTS=ONEnables the following ctest test targets (internet access is only required when a non-mock tor provider is enabled):
- honk_rpc_cargo_test
- tor_interface_cargo_test
- gosling_cargo_test
- cgosling_cargo_test
- gosling_functional_test
- gosling_unit_test
The following additional dependencies are required for this configure option:
cmake -DENABLE_FUZZ_TESTS=ONEnables the following cargo-fuzz ctest test targets (enabling this option also enables the ENABLE_TESTS option):
- honk_rpc_cargo_fuzz_test
- tor_interface_crypto_cargo_fuzz_test
- gosling_identity_server_cargo_fuzz_test
- gosling_identity_client_cargo_fuzz_test
- gosling_endpoint_server_cargo_fuzz_test
- gosling_endpoint_client_cargo_fuzz_test
- cgosling_cargo_fuzz_test
The following additional dependencies are required for this configure option:
- rust nightly (for
-zrustc compiler flag) - cargo-fuzz
- libfuzzer
cmake -DENABLE_LINTING=ONThe following additional dependencies are required for this configure option:
cmake -DENABLE_FORMATTING=ONThe following additional dependencies are required for this configure option:
cmake -DBUILD_PYTHON_BINDINGS=ONGenerates cgosling.py Python bindings as part of build
cmake -DBUILD_JAVA_BINDINGS=ONBuilds a cgosling-based JNI shared library and Gosling.jar java bindings.
The following additional dependencies are required for this configure option:
cmake -DBUILD_EXAMPLES=ONBuilds a cgosling-based C++ example program.
The following additional dependencies are required for this configure option:
cmake -DBUILD_DEBIAN_SOURCE_PACKAGE=ONBuilds a debian source package which generate libcgosling0, libcgosling-dev, and libcgosling0-dbgsym debian packages.
The following additional dependencies are required for this configure option:
- tar
- dpkg-source
See source/packages/debian-source/README.md for additional information.
cmake -DBUILD_HOMEBREW_FORMULA=ONBuilds a homebrew flask formula which installs libcgosling static libs, shared libs, and developemnt headers.
See source/packages/homebrew-formula/README.md for more additional information.
cmake -DBUILD_MSYS2_PKGBUILD=ONBuilds an MSYS2 PKGBUILD script which builds and installs libcgosling static libs, shared libs, and development headers.
See source/packages/msys2-pckbuild/README.md for more additional information.
cmake -DBUILD_PAGES=ONGenerate the gosling.technolgoy website including test code-coverage, Rust crate documentation, cgosling C/C++ documentation, and specifications. This configuration is only valid for Debug and RelWithDebInfo cmake targets.
Access to the tor network is required to run the tests and generate code-coverage.
The following additional dependencies are required for this configure option:
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