Crate tor_interface

Expand description

§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§