Struct tor_proto::circuit::ClientCirc

pub struct ClientCirc { /* private fields */ }

A circuit that we have constructed over the Tor network.

This struct is the interface used by the rest of the code, It is fairly cheaply cloneable. None of the public methods need mutable access, since they all actually communicate with the Reactor which contains the primary mutable state, and does the actual work.

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>

Return a description of all the hops in this circuit.

Note that this method performs a deep copy over the OwnedCircTarget values in the path. This is undesirable for some applications; see ticket #787.

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 send_control_message( &self, msg: AnyRelayCell, reply_handler: impl MsgHandler + Send + 'static ) -> Result<()>

Available on crate feature send-control-msg only.

Send a control message to the final hop on this circuit, and wait for one or more messages in reply.

(These steps are performed atomically, so that incoming messages can be accepted immediately after the outbound message is sent.)

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

For now, only one MsgHandler may be installed on a circuit at a time. If you try to install another MsgHandler, or if try to extend this circuit, before the MsgHandler you provide here returns MetaCellDisposition::UninstallHandler, the circuit will close with an error.

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 ) -> Result<()>

Available on crate feature hs-common only.

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

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, 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) -> Result<DataStream>

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

pub async fn resolve(&self, 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, 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 Clone for ClientCirc

fn clone(&self) -> ClientCirc

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ClientCirc

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

Formats the value using the given formatter.