Struct 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_tunnel, which returns a PendingClientTunnel. To get a real (one-hop) tunnel from one of these, you invoke one of its create_firsthop methods (typically create_firsthop_fast() or create_firsthop()). Then, to add more hops to the circuit, you can call extend() 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 ClientTunnel::terminate on the tunnel owning 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 into_tunnel(self) -> Result<ClientTunnel>

Convert this ClientCirc into a single circuit ClientTunnel.

pub fn first_hop(&self) -> Result<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_info(&self) -> Result<Option<OwnedChanTarget>>

Return a description of the last hop of the tunnel.

Return None if the last hop is virtual.

Panics

Panics 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 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.)

NOTE: This function will return the HopNum of the hop that is currently the last. 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 last_hop(&self) -> Result<TargetHop>

Return a TargetHop representing precisely the last hop of the circuit as in set as a HopLocation with its id and hop number.

Return an error if there is no last hop.

pub fn all_paths(&self) -> Vec<Arc<Path>>

Return a list of Path objects describing all the circuits in this tunnel.

Note that these Paths are not automatically updated if the underlying circuits are extended.

pub fn single_path(&self) -> Result<Arc<Path>>

Return a list of Path objects describing the only circuit in this tunnel.

Returns an error if the tunnel has more than one tunnel.

pub async fn first_hop_clock_skew(&self) -> Result<ClockSkew>

Get the clock skew claimed by the first hop of the circuit.

See Channel::clock_skew().

pub fn mq_account(&self) -> &CircuitAccount

Return a reference to this circuit’s memory quota account

pub async fn binding_key( &self, hop: TargetHop, ) -> Result<Option<CircuitBinding>>

Available on crate feature hs-service only.

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

where Tg: CircTarget,

Extend the circuit, via the most appropriate circuit extension handshake, to the chosen target hop.

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,

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, capabilities: &Protocols, ) -> 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 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) -> Result<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 + use<>

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.

impl TryFrom<ClientCirc> for ClientTunnel

type Error = Error

The type returned in the event of a conversion error.

fn try_from(circ: ClientCirc) -> Result<Self, Self::Error>

Performs the conversion.