Crate tor_interface

Tor-Interface

Developer-friendly crate providing connectivity to the Tor Network and functionality for interacting with Tor-specific cryptographic types.

This crate is not meant to be a general purpose Tor Controller nor does it aim to expose all of the functionality of the underlying Tor implementations. This crate also does not implement any of the Tor Network functionality itself, instead wrapping lower-level implementations.

Overview

The tor-interface crate provides the TorProvider trait with 3 concrete implementations:

• ArtiClientTorClient: an experimental wrapper around the arti-client crate; enabled using the arti-client-tor-provider feature flag.
• LegacyTorClient: a wrapper around either an owned or system-provided legacy c-tor daemon (aka ‘little-t tor’) with some basic configuration options; enabled using the legacy-tor-provider feature flag.
• MockTorClient: an in-process, mock implementation which makes no actual connections outside of localhost; enabled with the mock-tor-provider feature flag.

The TorProvider trait defines methods for connecting to various types of target addresses (ip, domains, and onion-services) and for creating onion-services.

⚠ Warning ⚠

The arti-client-tor-provider feature is experimental is not fully implemented. It also depends on the arti-client crate which is still under active development and is generally not yet ready for production use.

Usage

The following code snippet creates a LegacyTorClient which starts a bundled tor daemon, bootstraps, and attempts to connect to www.example.com.

// construct legacy tor client config
let tor_path = std::path::PathBuf::from_str("/usr/bin/tor").unwrap();
let mut data_path = std::env::temp_dir();
data_path.push("tor_data");

let tor_config = LegacyTorClientConfig::BundledTor {
    tor_bin_path: tor_path,
    data_directory: data_path,
    proxy_settings: None,
    allowed_ports: None,
    pluggable_transports: None,
    bridge_lines: None,
};
// create client from config
let mut tor_client = LegacyTorClient::new(tor_config).unwrap();

// bootstrap tor
let mut bootstrap_complete = false;
while !bootstrap_complete {
    for event in tor_client.update().unwrap().iter() {
        match event {
            TorEvent::BootstrapComplete => {
                bootstrap_complete = true;
            },
            _ => {},
        }
    }
}

// connect to example.com
let target_addr = TargetAddr::from_str("www.example.com:80").unwrap();
let mut stream: OnionStream = tor_client.connect(target_addr, None).unwrap();
// and convert to a std::net::TcpStream
let stream: TcpStream = stream.into();

Modules

arti_client_tor_client

Implementation of an in-process arti-client-based TorProvider

arti_process

arti_tor_client

Implementation of an out-of-process arti-based TorProvider

censorship_circumvention

Censorship circumvention configuration for pluggable-transports and bridge settings

legacy_tor_client

Implementation of an out-of-process legacy c-tor daemon-based TorProvider

legacy_tor_version

Legacy c-tor daemon version.

mock_tor_client

Implementation of a local, in-process, mock TorProvider for testing.

proxy

Proxy settings

tor_crypto

Tor-specific cryptographic primitives, operations, and conversion functions.

tor_provider

Traits and types for connecting to the Tor Network.