Module tor_proto::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 that extends it to its first hop. After you’ve done that, you can call ClientCirc::extend_ntor 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.

There’s one big mutex on the whole circuit: the reactor needs to hold it to process a cell, and streams need to hold it to send.

There is no flow-control or rate-limiting or fairness.

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
• ConversationInHandlersend-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.