Struct TorClient

pub struct TorClient<R: Runtime> { /* private fields */ }

An active client session on the Tor network.

While it’s running, it will fetch directory information, build circuits, and make connections for you.

Cloning this object makes a new reference to the same underlying handles: it’s usually better to clone the TorClient than it is to create a new one.

In the Arti RPC System

An open client on the Tor network.

A TorClient can be used to open anonymous connections, and (eventually) perform other activities.

You can use an RpcSession as a TorClient, or use the isolated_client method to create a new TorClient whose stream will not share circuits with any other Tor client.

This ObjectID for this object can be used as the target of a SOCKS stream.

Implementations

impl TorClient<PreferredRuntime>

pub async fn create_bootstrapped(config: TorClientConfig) -> Result<Self>

Available on (crate features native-tls or rustls) and (crate features async-std or tokio) only.

Bootstrap a connection to the Tor network, using the provided config.

Returns a client once there is enough directory material to connect safely over the Tor network.

Consider using TorClient::builder for more fine-grained control.

Panics

If Tokio is being used (the default), panics if created outside the context of a currently running Tokio runtime. See the documentation for PreferredRuntime::current for more information.

If using async-std, either take care to ensure Arti is not compiled with Tokio support, or manually create an async-std runtime using tor_rtcompat and use it with TorClient::with_runtime.

Do not fork

The process may not fork (except, very carefully, before exec) after calling this function, because it creates a PreferredRuntime.

pub fn builder() -> TorClientBuilder<PreferredRuntime>

Available on (crate features native-tls or rustls) and (crate features async-std or tokio) only.

Return a new builder for creating TorClient objects.

If you want to make a TorClient synchronously, this is what you want; call TorClientBuilder::create_unbootstrapped on the returned builder.

Panics

If Tokio is being used (the default), panics if created outside the context of a currently running Tokio runtime. See the documentation for tokio::runtime::Handle::current for more information.

If using async-std, either take care to ensure Arti is not compiled with Tokio support, or manually create an async-std runtime using tor_rtcompat and use it with TorClient::with_runtime.

Do not fork

The process may not fork (except, very carefully, before exec) after calling this function, because it creates a PreferredRuntime.

impl<R: Runtime> TorClient<R>

pub fn with_runtime(runtime: R) -> TorClientBuilder<R>

Return a new builder for creating TorClient objects, with a custom provided Runtime.

See the tor_rtcompat crate for more information on custom runtimes.

pub async fn bootstrap(&self) -> Result<()>

Bootstrap a connection to the Tor network, with a client created by create_unbootstrapped.

Since cloned copies of a TorClient share internal state, you can bootstrap a client by cloning it and running this function in a background task (or similar). This function only needs to be called on one client in order to bootstrap all of its clones.

Returns once there is enough directory material to connect safely over the Tor network. If the client or one of its clones has already been bootstrapped, returns immediately with success. If a bootstrap is in progress, waits for it to finish, then retries it if it failed (returning success if it succeeded).

Bootstrap progress can be tracked by listening to the event receiver returned by bootstrap_events.

Failures

If the bootstrapping process fails, returns an error. This function can safely be called again later to attempt to bootstrap another time.

pub fn reconfigure( &self, new_config: &TorClientConfig, how: Reconfigure, ) -> Result<()>

Change the configuration of this TorClient to new_config.

The how describes whether to perform an all-or-nothing reconfiguration: either all of the configuration changes will be applied, or none will. If you have disabled all-or-nothing changes, then only fatal errors will be reported in this function’s return value.

This function applies its changes to all TorClient instances derived from the same call to TorClient::create_*: even ones whose circuits are isolated from this handle.

Limitations

Although most options are reconfigurable, there are some whose values can’t be changed on an a running TorClient. Those options (or their sections) are explicitly documented not to be changeable. NOTE: Currently, not all of these non-reconfigurable options are documented. See arti#1721.

Changing some options do not take effect immediately on all open streams and circuits, but rather affect only future streams and circuits. Those are also explicitly documented.

pub fn isolated_client(&self) -> TorClient<R>

Return a new isolated TorClient handle.

The two TorClients will share internal state and configuration, but their streams will never share circuits with one another.

Use this function when you want separate parts of your program to each have a TorClient handle, but where you don’t want their activities to be linkable to one another over the Tor network.

Calling this function is usually preferable to creating a completely separate TorClient instance, since it can share its internals with the existing TorClient.

(Connections made with clones of the returned TorClient may share circuits with each other.)

pub async fn connect<A: IntoTorAddr>(&self, target: A) -> Result<DataStream>

Launch an anonymized connection to the provided address and port over the Tor network.

Note that because Tor prefers to do DNS resolution on the remote side of the network, this function takes its address as a string:

// The most usual way to connect is via an address-port tuple.
let socket = tor_client.connect(("www.example.com", 443)).await?;

// You can also specify an address and port as a colon-separated string.
let socket = tor_client.connect("www.example.com:443").await?;

Hostnames are strongly preferred here: if this function allowed the caller here to provide an IPAddr or IpAddr or SocketAddr address, then

// BAD: We're about to leak our target address to the local resolver!
let address = "www.example.com:443".to_socket_addrs().unwrap().next().unwrap();
// 🤯 Oh no! Now any eavesdropper can tell where we're about to connect! 🤯

// Fortunately, this won't compile, since SocketAddr doesn't implement IntoTorAddr.
// let socket = tor_client.connect(address).await?;
//                                 ^^^^^^^ the trait `IntoTorAddr` is not implemented for `std::net::SocketAddr`

If you really do need to connect to an IP address rather than a hostname, and if you’re sure that the IP address came from a safe location, there are a few ways to do so.

// ⚠️This is risky code!⚠️
// (Make sure your addresses came from somewhere safe...)

// If we have a fixed address, we can just provide it as a string.
let socket = tor_client.connect("192.0.2.22:443").await?;
let socket = tor_client.connect(("192.0.2.22", 443)).await?;

// If we have a SocketAddr or an IpAddr, we can use the
// DangerouslyIntoTorAddr trait.
use arti_client::DangerouslyIntoTorAddr;
let sockaddr = SocketAddr::from(([192, 0, 2, 22], 443));
let ipaddr = IpAddr::from([192, 0, 2, 22]);
let socket = tor_client.connect(sockaddr.into_tor_addr_dangerously().unwrap()).await?;
let socket = tor_client.connect((ipaddr, 443).into_tor_addr_dangerously().unwrap()).await?;

pub async fn connect_with_prefs<A: IntoTorAddr>( &self, target: A, prefs: &StreamPrefs, ) -> Result<DataStream>

Launch an anonymized connection to the provided address and port over the Tor network, with explicit connection preferences.

Note that because Tor prefers to do DNS resolution on the remote side of the network, this function takes its address as a string. (See TorClient::connect() for more information.)

pub fn set_stream_prefs(&mut self, connect_prefs: StreamPrefs)

Sets the default preferences for future connections made with this client.

The preferences set with this function will be inherited by clones of this client, but updates to the preferences in those clones will not propagate back to the original. I.e., the preferences are copied by clone.

Connection preferences always override configuration, even configuration set later (eg, by a config reload).

pub fn clone_with_prefs(&self, connect_prefs: StreamPrefs) -> Self

Provides a new handle on this client, but with adjusted default preferences.

Connections made with e.g. connect on the returned handle will use connect_prefs. This is a convenience wrapper for clone and set_connect_prefs.

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

On success, return a list of IP addresses.

pub async fn resolve_with_prefs( &self, hostname: &str, prefs: &StreamPrefs, ) -> Result<Vec<IpAddr>>

On success, return a list of IP addresses, but use prefs.

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

Perform a remote DNS reverse lookup with the provided IP address.

On success, return a list of hostnames.

pub async fn resolve_ptr_with_prefs( &self, addr: IpAddr, prefs: &StreamPrefs, ) -> Result<Vec<String>>

Perform a remote DNS reverse lookup with the provided IP address.

On success, return a list of hostnames.

pub fn dirmgr(&self) -> &Arc<dyn DirProvider>

Available on crate feature experimental-api only.

Return a reference to this client’s directory manager.

This function is unstable. It is only enabled if the crate was built with the experimental-api feature.

pub fn circmgr(&self) -> &Arc<CircMgr<R>>

Available on crate feature experimental-api only.

Return a reference to this client’s circuit manager.

This function is unstable. It is only enabled if the crate was built with the experimental-api feature.

pub fn chanmgr(&self) -> &Arc<ChanMgr<R>>

Available on crate feature experimental-api only.

Return a reference to this client’s channel manager.

This function is unstable. It is only enabled if the crate was built with the experimental-api feature.

pub fn hs_circ_pool(&self) -> &Arc<HsCircPool<R>>

Available on crate feature experimental-api and (crate features onion-service-client or onion-service-service) only.

Return a reference to this client’s circuit pool.

This function is unstable. It is only enabled if the crate was built with the experimental-api feature and any of onion-service-client or onion-service-service features. This method is required to invoke tor_hsservice::OnionService::launch()

pub fn runtime(&self) -> &R

Return a reference to the runtime being used by this client.

pub fn launch_onion_service( &self, config: OnionServiceConfig, ) -> Result<(Arc<RunningOnionService>, impl Stream<Item = RendRequest>)>

Available on crate feature onion-service-service only.

Try to launch an onion service with a given configuration.

This onion service will not actually handle any requests on its own: you will need to pull RendRequest objects from the returned stream, accept the ones that you want to answer, and then wait for them to give you StreamRequests.

You may find the tor_hsservice::handle_rend_requests API helpful for translating RendRequests into StreamRequests.

If you want to forward all the requests from an onion service to a set of local ports, you may want to use the tor-hsrproxy crate.

pub fn launch_onion_service_with_hsid( &self, config: OnionServiceConfig, id_keypair: HsIdKeypair, ) -> Result<(Arc<RunningOnionService>, impl Stream<Item = RendRequest>)>

Available on crate features onion-service-service and experimental-api only.

Try to launch an onion service with a given configuration and provided HsIdKeypair. If an onion service with the given nickname already has an associated HsIdKeypair in this TorClient’s KeyMgr, then this operation fails rather than overwriting the existing key.

The specified HsIdKeypair will be inserted in the primary keystore.

Important: depending on the configuration of your primary keystore, the HsIdKeypair may get persisted to disk. By default, Arti’s primary keystore is the native, disk-based keystore.

This onion service will not actually handle any requests on its own: you will need to pull RendRequest objects from the returned stream, accept the ones that you want to answer, and then wait for them to give you StreamRequests.

You may find the tor_hsservice::handle_rend_requests API helpful for translating RendRequests into StreamRequests.

If you want to forward all the requests from an onion service to a set of local ports, you may want to use the tor-hsrproxy crate.

pub fn generate_service_discovery_key( &self, selector: KeystoreSelector<'_>, hsid: HsId, ) -> Result<HsClientDescEncKey>

Available on crate features onion-service-client and experimental-api and keymgr only.

Generate a service discovery keypair for connecting to a hidden service running in “restricted discovery” mode.

The selector argument is used for choosing the keystore in which to generate the keypair. While most users will want to write to the Primary, if you have configured this TorClient with a non-default keystore and wish to generate the keypair in it, you can do so by calling this function with a KeystoreSelector::Id specifying the keystore ID of your keystore.

Returns an error if the key already exists in the specified key store.

Important: the public part of the generated keypair must be shared with the service, and the service needs to be configured to allow the owner of its private counterpart to discover its introduction points. The caller is responsible for sharing the public part of the key with the hidden service.

This function does not require the TorClient to be running or bootstrapped.

pub fn rotate_service_discovery_key( &self, selector: KeystoreSelector<'_>, hsid: HsId, ) -> Result<HsClientDescEncKey>

Available on crate features onion-service-client and experimental-api and keymgr only.

Rotate the service discovery keypair for connecting to a hidden service running in “restricted discovery” mode.

If the specified keystore already contains a restricted discovery keypair for the service, it will be overwritten. Otherwise, a new keypair is generated.

The selector argument is used for choosing the keystore in which to generate the keypair. While most users will want to write to the Primary, if you have configured this TorClient with a non-default keystore and wish to generate the keypair in it, you can do so by calling this function with a KeystoreSelector::Id specifying the keystore ID of your keystore.

Important: the public part of the generated keypair must be shared with the service, and the service needs to be configured to allow the owner of its private counterpart to discover its introduction points. The caller is responsible for sharing the public part of the key with the hidden service.

This function does not require the TorClient to be running or bootstrapped.

pub fn insert_service_discovery_key( &self, selector: KeystoreSelector<'_>, hsid: HsId, hs_client_desc_enc_secret_key: HsClientDescEncSecretKey, ) -> Result<HsClientDescEncKey>

Available on crate features onion-service-client and experimental-api and keymgr only.

Insert a service discovery secret key for connecting to a hidden service running in “restricted discovery” mode

The selector argument is used for choosing the keystore in which to generate the keypair. While most users will want to write to the Primary, if you have configured this TorClient with a non-default keystore and wish to insert the key in it, you can do so by calling this function with a KeystoreSelector::Id

Returns an error if the key already exists in the specified key store.

Important: the public part of the generated keypair must be shared with the service, and the service needs to be configured to allow the owner of its private counterpart to discover its introduction points. The caller is responsible for sharing the public part of the key with the hidden service.

This function does not require the TorClient to be running or bootstrapped.

pub fn get_service_discovery_key( &self, hsid: HsId, ) -> Result<Option<HsClientDescEncKey>>

Available on crate features onion-service-client and experimental-api only.

Return the service discovery public key for the service with the specified hsid.

Returns Ok(None) if no such key exists.

This function does not require the TorClient to be running or bootstrapped.

pub fn remove_service_discovery_key( &self, selector: KeystoreSelector<'_>, hsid: HsId, ) -> Result<Option<()>>

Available on crate features onion-service-client and experimental-api and keymgr only.

Removes the service discovery keypair for the service with the specified hsid.

Returns an error if the selected keystore is not the default keystore or one of the configured secondary stores.

Returns Ok(None) if no such keypair exists whereas `Ok(Some()) means the keypair was successfully removed.

Returns Err if an error occurred while trying to remove the key.

pub fn create_onion_service( config: &TorClientConfig, svc_config: OnionServiceConfig, ) -> Result<OnionService>

Available on crate feature onion-service-service only.

Create (but do not launch) a new OnionService using the given configuration.

The returned OnionService can be launched using OnionService::launch().

pub fn bootstrap_status(&self) -> BootstrapStatus

Return a current status::BootstrapStatus describing how close this client is to being ready for user traffic.

pub fn bootstrap_events(&self) -> BootstrapEvents

Return a stream of status::BootstrapStatus events that will be updated whenever the client’s status changes.

The receiver might not receive every update sent to this stream, though when it does poll the stream it should get the most recent one.

pub fn set_dormant(&self, mode: DormantMode)

Change the client’s current dormant mode, putting background tasks to sleep or waking them up as appropriate.

This can be used to conserve CPU usage if you aren’t planning on using the client for a while, especially on mobile platforms.

See the DormantMode documentation for more details.

pub fn wait_for_stop(&self) -> impl Future<Output = ()> + Send + Sync + 'static

Available on crate feature experimental-api only.

Return a Future which resolves once this TorClient has stopped.

impl<R: Runtime> TorClient<R>

pub fn rpc_methods() -> Vec<InvokerEnt>

Available on crate feature rpc only.

Ensure that every RPC method is registered for this instantiation of TorClient.

We can’t use rpc::static_rpc_invoke_fn for these, since TorClient is parameterized.

Trait Implementations

impl<R: Clone + Runtime> Clone for TorClient<R>

fn clone(&self) -> TorClient<R>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<R: Runtime> Object for TorClient<R>

where TorClient<R>: Send + Sync + 'static,

fn expose_outside_of_session(&self) -> bool

Return true if this object should be given an identifier that allows it to be used outside of the session that generated it.

fn get_cast_table(&self) -> &CastTable

Return a CastTable that can be used to downcast a dyn Object of this type into various kinds of dyn Trait references.

fn delegate(&self) -> Option<Arc<dyn Object>>

Optionally, return a delegation target for this `Object``.