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::memquota::StreamAccount;

Modules

handshakehs-common

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

Structs

CircParameters

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

CircuitBinding

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

ClientCirc

A circuit that we have constructed over the Tor network.

ClientCircSyncView

A view of a ClientCirc’s internals, usable in a synchronous callback.

Conversationsend-control-msg

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

Path

A circuit’s path through the network.

PathEntry

A description of a single hop in a Path.

PendingClientCirc

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

UniqId

Process-unique identifier for a circuit.

Enums

MetaCellDispositionsend-control-msg

A possible successful outcome of giving a message to a MsgHandler.

Constants

CIRCUIT_BUFFER_SIZE

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

Traits

MsgHandlersend-control-msg

An object that checks whether incoming control messages are acceptable on a circuit, and delivers them to a client if so.