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.

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

Available on crate feature experimental-api only.

Send a control message to the final hop on this circuit.

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.

(This function is not yet implemented. Right now it will always panic.)

pub fn receive_control_messages( &self ) -> Result<impl Stream<Item = Box<RawCellBody>>>

Available on crate feature experimental-api only.

Begin accepting ‘control’ messages from the final hop on this circuit, and return an asynchronous stream of any such messages that arrive.

A “control” message is a message without a stream ID that tor-proto does not handle on its own. (The messages that tor-proto can handle are DESTROY, DATA, SENDME, …) Ordinarily, any unexpected control message will cause the circuit to exit with an error.

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.

The caller should be sure to close the circuit if a command that it doesn’t recognize shows up.

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

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.

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.