Struct ClientTunnel 

pub struct ClientTunnel {
    circ: ClientCirc,
}

A low-level client tunnel API.

This is a communication channel to the tunnel reactor, which manages 1 or more circuits.

Note: the tor-circmgr crates wrap this type in specialized *Tunnel types exposing only the desired subset of functionality depending on purpose and path size.

Some API calls are for single path and some for multi path. A check with the underlying reactor is done preventing for instance multi path calls to be used on a single path. Top level types should prevent this and thus this object should never be used directly.

Fields

circ: ClientCirc

The underlying handle to the reactor.

Implementations

impl ClientTunnel

pub fn as_single_circ(&self) -> Result<&ClientCirc>

Return a handle to the ClientCirc of this ClientTunnel, if the tunnel is a single circuit tunnel.

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

pub fn first_hop(&self) -> Result<OwnedChanTarget>

Return the channel target of the first hop.

Can only be used for single path tunnel.

pub fn is_closed(&self) -> bool

Return true if the circuit reactor is closed meaning the circuit is unusable for both receiving or sending.

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 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; return an error if the tunnel has no circuits, or all of its circuits are zero length.

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 n_hops(&self) -> Result<usize>

Return the number of hops this tunnel as. Fail for a multi path.

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

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

pub fn unique_id(&self) -> UniqId

Return a process-unique identifier for this tunnel.

Returns the reactor unique ID of the main reactor.

pub async fn disused_since(&self) -> Result<Option<Instant>>

Return the time at which this tunnel last had any open streams.

Returns None if this tunnel has never had any open streams, or if it currently has open streams.

NOTE that the Instant returned by this method is not affected by any runtime mocking; it is the output of an ordinary call to Instant::now().

pub fn wait_for_close( self: &Arc<Self>, ) -> impl Future<Output = ()> + Send + Sync + 'static + use<>

Return a future that will resolve once the underlying circuit reactor has closed.

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

pub async fn allow_stream_requests<'a, FILT>( self: &Arc<Self>, allow_commands: &'a [RelayCmd], hop: TargetHop, filter: FILT, ) -> Result<impl Stream<Item = IncomingStream> + use<'a, FILT>>

where FILT: IncomingStreamRequestFilter + 'a,

Available on crate feature hs-service only.

Single-path tunnel only. Multi path onion service is not supported yet.

Tell this tunnel to begin allowing the final hop of the tunnel 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 tunnel. If a such a Stream already exists, this method will return an error.

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

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

async fn begin_stream_impl( self: &Arc<Self>, begin_msg: AnyRelayMsg, cmd_checker: Box<dyn CmdChecker + Send + 'static>, ) -> Result<StreamComponents>

Single and Multi path helper, used to begin a stream.

This function allocates a stream ID, and sends the message (like a BEGIN or RESOLVE), but doesn’t wait for a response.

The caller will typically want to see the first cell in response, to see whether it is e.g. an END or a CONNECTED.

pub async fn start_padding_at_hop( self: &Arc<Self>, hop: HopLocation, padder: CircuitPadder, ) -> Result<()>

Available on crate feature circ-padding-manual only.

Install a CircuitPadder at the listed hop.

Replaces any previous padder installed at that hop.

pub async fn stop_padding_at_hop( self: &Arc<Self>, hop: HopLocation, ) -> Result<()>

Available on crate feature circ-padding-manual only.

Remove any CircuitPadder at the listed hop.

Does nothing if there was not a padder installed there.

async fn begin_data_stream( self: &Arc<Self>, msg: AnyRelayMsg, optimistic: bool, ) -> Result<DataStream>

Start a DataStream (anonymized connection) to the given address and port, using a BEGIN cell.

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

Single and multi path helper.

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

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

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

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

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

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

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

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

pub async fn send_raw_msg(&self, msg: AnyRelayMsg, hop: TargetHop) -> 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 ClientTunnel::start_conversation.)

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

Available on crate feature send-control-msg only.

Start an ad-hoc protocol exchange to the specified hop on this tunnel.

To use this:

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

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 UserMsgHandler, process the incoming messages. You may respond by sending additional messages When the protocol exchange is finished, UserMsgHandler::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 ClientTunnel::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 tunnel which might be shared with anyone else.

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

After the conversation has finished, the tunnel 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 UserMsgHandler is installed, and unexpected incoming messages would close the tunnel.

If these restrictions are violated, the tunnel 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 UserMsgHandler::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 terminate(&self)

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

Note that other references to this tunnel 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 tunnel: the tunnel should close on its own once nothing is using it any more.

async fn try_resolve(self: &Arc<Self>, msg: Resolve) -> Result<Resolved>

Helper: Send the resolve message, and read resolved message from resolve stream.

impl ClientTunnel

pub(crate) fn close_pending( &self, stream_id: StreamId, hop: Option<HopLocation>, message: CloseStreamBehavior, ) -> Result<Receiver<Result<()>>>

Available on crate feature hs-service only.

Close the pending stream that owns this StreamTarget, delivering the specified END message (if any)

See StreamTarget::close_pending.

pub(crate) fn send_sendme( &self, stream_id: StreamId, hop: Option<HopLocation>, ) -> Result<()>

Request to send a SENDME cell for this stream.

See StreamTarget::send_sendme.

pub(crate) fn drain_rate_update( &self, stream_id: StreamId, hop: Option<HopLocation>, rate: XonKbpsEwma, ) -> Result<()>

Inform the circuit reactor that there has been a change in the drain rate for this stream.

See StreamTarget::drain_rate_update.

Trait Implementations

impl Debug for ClientTunnel

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.