Module circuit 

Multi-hop paths over the Tor network.

Right now, we only implement “client circuits” – also sometimes called “origin circuits”. A client circuit is one that is constructed by this Tor instance, and used in its own behalf to send data over the Tor network.

Each circuit has multiple hops over the Tor network: each hop knows only the hop before and the hop after. The client shares a separate set of keys with each hop.

To build a circuit, first create a crate::channel::Channel, then call its crate::channel::Channel::new_tunnel method. This yields a PendingClientTunnel object that won’t become live until you call one of the methods (typically PendingClientTunnel::create_firsthop) that extends it to its first hop. After you’ve done that, you can call ClientCirc::extend on the tunnel to build it into a multi-hop tunnel. Finally, you can use ClientTunnel::begin_stream to get a Stream object that can be used for anonymized data.

Implementation

Each open circuit has a corresponding Reactor object that runs in an asynchronous task, and manages incoming cells from the circuit’s upstream channel. These cells are either RELAY cells or DESTROY cells. DESTROY cells are handled immediately. RELAY cells are either for a particular stream, in which case they get forwarded to a RawCellStream object, or for no particular stream, in which case they are considered “meta” cells (like EXTENDED2) that should only get accepted if something is waiting for them.

Limitations

This is client-only.

Re-exports

pub use crate::circuit::CircParameters;

Modules

halfcirc 🔒

A “receive-only” view of a circuit, as a placeholder for circuits that have closed.

handshake

Features for manual invocation of Tor’s cryptographic circuit handshakes.

padding 🔒

Definitions for circuit padding.

path 🔒

Tracking for the path of a client circuit.

Structs

CircuitBinding

Cryptographic information used to bind a message to a specific circuit.

CircuitState 🔒

The shared state of a circuit.

ClientCirc

A circuit that we have constructed over the Tor network.

MutableState 🔒

The mutable state of a circuit.

Path

A circuit’s path through the network.

PathEntry

A description of a single hop in a Path.

PendingClientTunnel

A ClientCirc that needs to send a create cell and receive a created* cell.

TunnelMutableState 🔒

The mutable state of a tunnel, shared between ClientCirc and Reactor.

Enums

ClientCircChanMsg 🔒

A subclass of ChanMsg that can correctly arrive on a live client circuit (one where a CREATED* has been received).

Constants

CIRCUIT_BUFFER_SIZE

The size of the buffer for communication between ClientCirc and its reactor.

Traits

TimeoutEstimator

An object used by circuits to compute various timeouts.