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 last_hop_num(&self) -> Result<HopNum>

Return the HopNum of the last hop of this circuit.

Returns an error if there is no last 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 fn binding_key(&self, hop: HopNum) -> Option<CircuitBinding>

Return the cryptographic material used to prove knowledge of a shared secret with with hop.

See CircuitBinding for more information on how this is used.

Return None if we have no circuit binding information for the hop, or if the hop does not exist.

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

Available on crate feature send-control-msg only.

Start an ad-hoc protocol exchange to the specified 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. 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, 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.

(If you don’t want to accept any replies at all, it may be simpler to use ClientCirc::send_raw_msg.)

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

👎Deprecated since 0.13.0: Use start_conversation instead.

Available on crate feature send-control-msg only.

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

See the ClientCirc::start_conversation docs for more information.

pub async fn send_raw_msg( &self, msg: AnyRelayMsg, hop_num: HopNum ) -> Result<()>

Available on crate feature send-control-msg only.

Send an ad-hoc message to a given hop on the circuit, without expecting a reply.

(If you want to handle one or more possible replies, see ClientCirc::start_conversation.)

pub async fn allow_stream_requests( self: &Arc<ClientCirc>, allow_commands: &[RelayCmd], hop_num: HopNum, filter: impl IncomingStreamRequestFilter ) -> 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. If a such a Stream already exists, this method will return an error.

After this method has been called on a circuit, the circuit is expected to receive requests of this type indefinitely, until it is finally closed. If the Stream is dropped, the next request on this circuit will cause it to close.

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_ntor_v3<Tg>( &self, target: &Tg, params: &CircParameters ) -> Result<()>

where Tg: CircTarget,

Available on crate feature ntor_v3 only.

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 circuit 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.

pub fn wait_for_close(&self) -> impl Future<Output = ()> + Send + Sync + 'static

Available on crate feature experimental-api only.

Return a future that will resolve once this circuit has closed.

Note that this method does not itself cause the circuit to shut down.

TODO: Perhaps this should return some kind of status indication instead of just ()

Trait Implementations

impl Debug for ClientCirc

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

Formats the value using the given formatter.