search

blueprint-freespeech / gosling

Rust crate providing anonymous, secure, and private peer-to-peer functionality using Tor onion services
https://gosling.technology
Other
32 stars 8 forks source link
anonymity onion-service peer-to-peer rust tor

readme

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:

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:

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

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

The following additional dependencies are required for this configure option:

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:

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:

TEB_TARGET

cmake -DTEB_TARGET==${TEB_TARGET}

The tor-expert-bundle target to download and use when ENABLE_TOR_EXPERT_BUNDLE=ON. If not provided, CMake will do its best to guess.

The supported targets are:

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