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_circ method. This yields a PendingClientCirc object that won’t become live until you call one of the methods (typically PendingClientCirc::create_firsthop) that extends it to its first hop. After you’ve done that, you can call ClientCirc::extend on the circuit to build it into a multi-hop circuit. Finally, you can use ClientCirc::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::crypto::binding::CircuitBinding;

pub use crate::memquota::StreamAccount;

pub use crate::tunnel::circuit::unique_id::UniqId;

pub use path::Path;

pub use path::PathEntry;

pub use crate::tunnel::reactor::syncview::ClientCircSyncView;

pub use crate::tunnel::msghandler::MsgHandler;send-control-msg

pub use crate::tunnel::reactor::MetaCellDisposition;send-control-msg

Modules

celltypes 🔒

Wrapper types for subsets of ChanMsg and RelayMsg types.

halfcirc 🔒

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

handshakehs-common

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

path 🔒

Tracking for the path of a client circuit.

unique_id 🔒

Unique identifiers for circuits.

Structs

CircParameters

Description of the network’s current rules for building circuits.

CircuitState 🔒

The shared state of a circuit.

ClientCirc

A circuit that we have constructed over the Tor network.

Conversationsend-control-msg

Handle to use during an ongoing protocol exchange with a circuit’s last hop

MutableState 🔒

The mutable state of a circuit.

PendingClientCirc

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.

Constants

CIRCUIT_BUFFER_SIZE

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

Functions

resolvedval_to_result 🔒

Convert a ResolvedVal into a Result, based on whether or not it represents an error.

Type Aliases

CircuitRxReceiver 🔒

MPSC queue for inbound data on its way from channel to circuit, receiver

CircuitRxSender 🔒

MPSC queue for inbound data on its way from channel to circuit, sender

StreamMpscReceiver 🔒

MPSC queue relating to a stream (either inbound or outbound), receiver

StreamMpscSender 🔒

MPSC queue relating to a stream (either inbound or outbound), sender