Gosling
Rust crate providing anonymous, secure, and private peer-to-peer functionality using Tor onion services
Install / Use
/learn @blueprint-freespeech/GoslingREADME
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:
Building
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 install
You 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 --init
Required Dependencies
Gosling 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:
Configuration Options
Build-time configuration options for features which may be conditionally enabled or disabled.
ENABLE_MOCK_TOR_PROVIDER
cmake -DENABLE_MOCK_TOR_PROVIDER=ON
Enable 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.
ENABLE_LEGACY_TOR_PROVIDER
cmake -DENABLE_LEGACY_TOR_PROVIDER=ON
Enable 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.
ENABLE_ARTI_CLIENT_TOR_PROVIDER
cmake -DENABLE_ARTI_CLIENT_TOR_PROVIDER=ON
Enable 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 Configuration Options and Optional Dependencies
Additional optional bindings, tests, and documentation can be enabled with the following cmake options. Each of these options are OFF by default.
ENABLE_TESTS
cmake -DENABLE_TESTS=ON
Enables the following ctest test targets (internet access is only required when a non-mock tor provider is enabled):
- honk_rpc_cargo_test
- tor_interface_crypto_cargo_test
- tor_interface_tor_provider_cargo_test
- tor_interface_mock_authenticated_onion_service_cargo_test
- tor_interface_mock_bootstrap_cargo_test
- tor_interface_mock_onion_service_cargo_test
- tor_interface_arti_authenticated_onion_service_cargo_test
- tor_interface_arti_client_bootstrap_cargo_test
- tor_interface_arti_client_onion_service_cargo_test
- tor_interface_legacy_authenticated_onion_service_cargo_test
- tor_interface_legacy_bootstrap_cargo_test
- tor_interface_legacy_onion_service_cargo_test
- tor_interface_legacy_pluggable_transport_bootstrap_cargo_test
- tor_interface_system_legacy_authenticated_onion_service_cargo_test
- tor_interface_system_legacy_onion_service_cargo_test
- tor_interface_mixed_arti_client_legacy_authenticated_onion_service_cargo_test
- tor_interface_mixed_arti_client_legacy_bootstrap_cargo_test
- tor_interface_mixed_legacy_arti_client_authenticated_onion_service_cargo_test
- tor_interface_mixed_legacy_arti_client_bootstrap_cargo_test
- gosling_cargo_test
- cgosling_cargo_test
- gosling_cpp_bindings_test
- gosling_java_bindings_test (depends on BUILD_JAVA_BINDINGS option)
The following additional dependencies are required for this configure option:
ENABLE_FUZZ_TESTS
cmake -DENABLE_FUZZ_TESTS=ON
Enables 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
ENABLE_TOR_EXPERT_BUNDLE
cmake -DENABLE_TOR_EXPERT_BUNDLE=ON
Downloads and extracts the tor-expert-bundle in tree. The tor-expert-bundle is an archive provided by the Tor Project containing the latest tor binaries, pluggable-transport binaries, and configuration options used in Tor Browser. Enabling this option allows testing the pluggable-transport integration in the tor-interface and cgosling crates.
ENABLE_LINTING
cmake -DENABLE_LINTING=ON
The following additional dependencies are required for this configure option:
ENABLE_FORMATTING
cmake -DENABLE_FORMATTING=ON
The following additional dependencies are required for this configure option:
BUILD_PYTHON_BINDINGS
cmake -DBUILD_PYTHON_BINDINGS=ON
Generates cgosling.py Python bindings as part of build
BUILD_JAVA_BINDINGS
cmake -DBUILD_JAVA_BINDINGS=ON
Builds a cgosling-based JNI shared library and Gosling.jar java bindings.
The following additional dependencies are required for this configure option:
BUILD_EXAMPLES
cmake -DBUILD_EXAMPLES=ON
Builds a Gosling-based Rust example chat application and the equivalent (and interoperable) cgosling-based C++ example chat application.
The following additional dependencies are required for this configure option:
It is also dependent on the ENABLE_LEGACY_TOR_PROVIDER config option.
BUILD_DEBIAN_SOURCE_PACKAGE
cmake -DBUILD_DEBIAN_SOURCE_PACKAGE=ON
Builds 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.
BUILD_HOMEBREW_FORMULA
cmake -DBUILD_HOMEBREW_FORMULA=ON
Builds 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.
BUILD_MSYS2_PKGBUILD
cmake -DBUILD_MSYS2_PKGBUILD=ON
Builds an MSYS2 PKGBUILD script which builds and installs libcgosling static libs, shared libs, and development headers.
See source/packages/msys2-pkgbuild/README.md for more additional information.
BUILD_PAGES
cmake -DBUILD_PAGES=ON
Generate 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:
- cargo-sbom
- cargo-tarpaulin
- doxygen
- graphviz
- mustache
- pandoc
- plantuml
- [tidy](https://git
