Struct tor_proto::circuit::ClientCirc

pub struct ClientCirc { /* private fields */ }

A circuit that we have constructed over the Tor network.

Circuit life cycle

ClientCircs are created in an initially unusable state using Channel::new_circ, which returns a PendingClientCirc. To get a real (one-hop) circuit from one of these, you invoke one of its create_firsthop methods (currently create_firsthop_fast() or create_firsthop_ntor()). Then, to add more hops to the circuit, you can call extend_ntor() on it.

For higher-level APIs, see the tor-circmgr crate: the ones here in tor-proto are probably not what you need.

After a circuit is created, it will persist until it is closed in one of five ways:

1. A remote error occurs.
2. Some hop on the circuit sends a DESTROY message to tear down the circuit.
3. The circuit’s channel is closed.
4. Someone calls ClientCirc::terminate on the circuit.
5. The last reference to the ClientCirc is dropped. (Note that every stream on a ClientCirc keeps a reference to it, which will in turn keep the circuit from closing until all those streams have gone away.)

Note that in cases 1-4 the ClientCirc object itself will still exist: it will just be unusable for most purposes. Most operations on it will fail with an error.

Implementations

impl ClientCirc

pub fn first_hop(&self) -> OwnedChanTarget

Return a description of the first hop of this circuit.

Panics

Panics if there is no first hop. (This should be impossible outside of the tor-proto crate, but within the crate it’s possible to have a circuit with no hops.)

pub fn path(&self) -> Vec<OwnedChanTarget>

👎Deprecated since 0.11.1: Use path_ref() instead.

Return a description of all the hops in this circuit.

This method is deprecated for several reasons:

• It performs a deep copy.
• It ignores virtual hops.
• It’s not so extensible.

Use ClientCirc::path_ref() instead.

pub fn path_ref(&self) -> Arc<Path>

Return a Path object describing all the hops in this circuit.

Note that this Path is not automatically updated if the circuit is extended.

pub fn channel(&self) -> &Channel

Return a reference to the channel that this circuit is connected to.

A client circuit is always connected to some relay via a Channel. That relay has to be the same relay as the first hop in the client’s path.

pub async fn start_conversation_last_hop( &self, msg: Option<AnyRelayMsg>, reply_handler: impl MsgHandler + Send + 'static ) -> Result<Conversation<'_>>

Available on crate feature send-control-msg only.

Start an ad-hoc protocol exchange to the final hop on this circuit

To use this:

0. Create an inter-task channel you’ll use to receive the outcome of your conversation, and bundle it into a MsgHandler.

1. Call start_conversation_last_hop. This will install a your handler, for incoming messages, and send the outgoing message (if you provided one). After that, each message on the circuit that isn’t handled by the core machinery is passed to your provided reply_handler.

2. Possibly call send_msg on the Conversation, from the call site of start_conversation_last_hop, possibly multiple times, from time to time, to send further desired messages to the peer.

3. In your MsgHandler, process the incoming messages. You may respond by sending additional messages (using the ConversationInHandler provided to MsgHandler::handle_msg, or, outside the handler using the Conversation) When the protocol exchange is finished, MsgHandler::handle_msg should return ConversationFinished.

If you don’t need the Conversation to send followup messages, you may simply drop it, and rely on the responses you get from your handler, on the channel from step 0 above. Your handler will remain installed and able to process incoming messages until it returns ConversationFinished.

Note that it is quite possible to use this function to violate the tor protocol; most users of this API will not need to call it. It is used to implement most of the onion service handshake.

Limitations

Only one conversation may be active at any one time, for any one circuit. This generally means that this function should not be called on a circuit which might be shared with anyone else.

Likewise, it is forbidden to try to extend the circuit, while the conversation is in progress.

After the conversation has finished, the circuit may be extended. Or, start_conversation_last_hop may be called again; but, in that case there will be a gap between the two conversations, during which no MsgHandler is installed, and unexpected incoming messages would close the circuit.

If these restrictions are violated, the circuit will be closed with an error.

Precise definition of the lifetime of a conversation

A conversation is in progress from entry to start_conversation_last_hop, until entry to the body of the MsgHandler::handle_msg call which returns ConversationFinished. (Entry since handle_msg is synchronously embedded into the incoming message processing.) So you may start a new conversation as soon as you have the final response via your inter-task channel from (0) above.

The lifetime relationship of the Conversation, vs the handler returning ConversationFinished is not enforced by the type system.

pub fn allow_stream_requests( &self, allow_commands: &[RelayCmd] ) -> Result<impl Stream<Item = IncomingStream>>

Available on crate feature hs-service only.

Tell this circuit to begin allowing the final hop of the circuit to try to create new Tor streams, and to return those pending requests in an asynchronous stream.

Ordinarily, these requests are rejected.

There can only be one stream of this type created on a given circuit at a time. If a such a stream already exists, this method will return an error.

(This function is not yet implemented; right now, it will always panic.)

Only onion services (and eventually) exit relays should call this method.

pub async fn extend_ntor<Tg>( &self, target: &Tg, params: &CircParameters ) -> Result<()>where Tg: CircTarget,

Extend the circuit via the ntor handshake to a new target last hop.

pub async fn extend_virtual( &self, protocol: RelayProtocol, role: HandshakeRole, seed: impl KeyGenerator, params: CircParameters ) -> Result<()>

Available on crate feature hs-common only.

Extend this circuit by a single, “virtual” hop.

A virtual hop is one for which we do not add an actual network connection between separate hosts (such as Relays). We only add a layer of cryptography.

This is used to implement onion services: the client and the service both build a circuit to a single rendezvous point, and tell the rendezvous point to relay traffic between their two circuits. Having completed a handshake out of band¹, the parties each extend their circuits by a single “virtual” encryption hop that represents their shared cryptographic context.

Once a circuit has been extended in this way, it is an error to try to extend it in any other way.

---

1. Technically, the handshake is only mostly out of band: the client sends their half of the handshake in an message, and the service's response is inline in itsRENDEZVOUS2` message. ↩

pub async fn begin_stream( self: &Arc<ClientCirc>, target: &str, port: u16, parameters: Option<StreamParameters> ) -> Result<DataStream>

Start a stream to the given address and port, using a BEGIN cell.

The use of a string for the address is intentional: you should let the remote Tor relay do the hostname lookup for you.

pub async fn begin_dir_stream(self: Arc<ClientCirc>) -> Result<DataStream>

Start a new stream to the last relay in the circuit, using a BEGIN_DIR cell.

pub async fn resolve( self: &Arc<ClientCirc>, hostname: &str ) -> Result<Vec<IpAddr>>

Perform a DNS lookup, using a RESOLVE cell with the last relay in this circuit.

Note that this function does not check for timeouts; that’s the caller’s responsibility.

pub async fn resolve_ptr( self: &Arc<ClientCirc>, addr: IpAddr ) -> Result<Vec<String>>

Perform a reverse DNS lookup, by sending a RESOLVE cell with the last relay on this circuit.

Note that this function does not check for timeouts; that’s the caller’s responsibility.

pub fn terminate(&self)

Shut down this circuit, along with all streams that are using it. Happens asynchronously (i.e. the circuit won’t necessarily be done shutting down immediately after this function returns!).

Note that other references to this circuit may exist. If they do, they will stop working after you call this function.

It’s not necessary to call this method if you’re just done with a circuit: the channel should close on its own once nothing is using it any more.

pub fn is_closing(&self) -> bool

Return true if this circuit is closed and therefore unusable.

pub fn unique_id(&self) -> UniqId

Return a process-unique identifier for this circuit.

pub fn n_hops(&self) -> usize

Return the number of hops in this circuit.

NOTE: This function will currently return only the number of hops currently in the circuit. If there is an extend operation in progress, the currently pending hop may or may not be counted, depending on whether the extend operation finishes before this call is done.

Trait Implementations

impl Debug for ClientCirc

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.