Struct ClientOnionServiceDataTunnel 

pub struct ClientOnionServiceDataTunnel { /* private fields */ }

A client onion service single path data tunnel.

Implementations

impl ClientOnionServiceDataTunnel

pub fn is_closed(&self) -> bool

Return true if this tunnel is closed and therefore unusable.

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 terminate(&self)

Shutdown the tunnel meaning this sends a shutdown command to the underlying circuit reactor which will stop asynchronously.

Note that it is not necessary to use this method as in if the tunnel reference is dropped, the circuit will close automatically.

pub fn unique_id(&self) -> UniqId

Return a process-unique identifier for this tunnel.

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

Available on crate feature send-control-msg only.

Send raw message.

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.

See ClientTunnel::start_conversation documentation for more details.

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.

impl ClientOnionServiceDataTunnel

pub async fn begin_stream( &self, target: &str, port: u16, params: 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.

impl ClientOnionServiceDataTunnel

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

impl ClientOnionServiceDataTunnel

pub async fn extend<T: CircTarget>( &self, target: &T, params: CircParameters, ) -> Result<()>

Extend the circuit to a new target last hop using the ntor v3 handshake.

TODO: Might want to pass which handshake type as a parameter so this function can be a catch all on all possible handshakes. For now, use ntor v3 for all the things.

pub fn n_hops(&self) -> Result<usize>

Return the number of hops of the underlying circuit.

Trait Implementations

impl AsRef<ClientTunnel> for ClientOnionServiceDataTunnel

fn as_ref(&self) -> &ClientTunnel

Converts this type into a shared reference of the (usually inferred) input type.

impl Debug for ClientOnionServiceDataTunnel

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

Formats the value using the given formatter.

impl From<Arc<ClientTunnel>> for ClientOnionServiceDataTunnel

fn from(tunnel: Arc<ClientTunnel>) -> Self

Converts to this type from the input type.

impl From<ClientTunnel> for ClientOnionServiceDataTunnel

fn from(tunnel: ClientTunnel) -> Self

Converts to this type from the input type.