Update README.md files from rustdoc.
This commit is contained in:
Nick Mathewson
parent
c8f617c85e
commit
5735222691
|
|
@ -5,65 +5,87 @@ High-level functionality for accessing the Tor network as a client.
|
|||
## Overview
|
||||
|
||||
The `arti-client` crate aims to provide a safe, easy-to-use API for
|
||||
applications that want to use Tor network to anonymize their
|
||||
traffic. It hides most of the underlying detail, letting other
|
||||
crates decide how exactly to use the Tor crate.
|
||||
applications that want to use the Tor network to anonymize their traffic.
|
||||
|
||||
This crate is part of
|
||||
[Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to
|
||||
implement [Tor](https://www.torproject.org/) in Rust.
|
||||
It is the highest-level library crate in
|
||||
Arti, and the one that nearly all client-only programs should use.
|
||||
Most of its functionality is provided by lower-level crates in Arti.
|
||||
This crate is part of [Arti](https://gitlab.torproject.org/tpo/core/arti/),
|
||||
a project to implement [Tor](https://www.torproject.org/) in Rust. It is the
|
||||
highest-level library crate in Arti, and the one that nearly all client-only
|
||||
programs should use. Most of its functionality is provided by lower-level
|
||||
crates in Arti.
|
||||
|
||||
### ⚠ Warnings ⚠
|
||||
|
||||
Note that Arti is a work in progress; although we've tried to
|
||||
write all the critical security components, you probably shouldn't
|
||||
use Arti in production until it's a bit more mature.
|
||||
Note that Arti is a work in progress; although we've tried to write all the
|
||||
critical security components, you probably shouldn't use Arti in production
|
||||
until it's a bit more mature. (That said, now is a _great_ time to try
|
||||
our Arti on an experimental basis, so you can tell us what we need
|
||||
to fix between now and the 1.0.0 release.)
|
||||
|
||||
Also note that all of the APIs for this crate, and for Arti in
|
||||
general, are not the least bit stable. If you use this code,
|
||||
please expect your software to break on a regular basis.
|
||||
Also note that the APIs for this crate are not all yet
|
||||
completely stable. We'll try not to break things without good
|
||||
reason, and we'll follow semantic versioning when we do, but
|
||||
please expect a certain amount of breakage between now and 1.0.0.
|
||||
|
||||
The APIs exposed by lower-level crates in Arti are _even more
|
||||
unstable_; they will break more often than those from
|
||||
`arti-client`, for less reason.
|
||||
|
||||
## Using `arti-client`
|
||||
|
||||
The main entry point for this crate is the [`TorClient`], an object that lets you make
|
||||
connections over the Tor network.
|
||||
The main entry point for this crate is the [`TorClient`], an object that
|
||||
lets you make connections over the Tor network.
|
||||
|
||||
Calling [`TorClient::bootstrap`] establishes a connection to the Tor network, pulling in
|
||||
necessary state about network consensus as required. This state gets persisted to the
|
||||
locations specified in the [`TorClientConfig`].
|
||||
### Connecting to Tor
|
||||
|
||||
A client can then be used to make connections over Tor with [`TorClient::connect`], which
|
||||
accepts anything implementing [`IntoTorAddr`]. This returns a [`DataStream`], an anonymized
|
||||
TCP stream type that implements [`AsyncRead`](futures::io::AsyncRead) and
|
||||
[`AsyncWrite`](futures::io::AsyncWrite), as well as the Tokio versions of those traits if
|
||||
the `tokio` crate feature is enabled.
|
||||
Calling [`TorClient::create_bootstrapped`] establishes a connection to the Tor
|
||||
network, pulling in necessary state about network consensus as required.
|
||||
This state gets persisted to the locations specified in the
|
||||
[`TorClientConfig`].
|
||||
|
||||
The [`TorAddr`] type is intended to ensure that DNS lookups are done via the Tor network
|
||||
instead of locally. Doing local DNS resolution can leak information about which hostnames you're
|
||||
connecting to to your local DNS resolver (i.e. your ISP), so it's much better to let Arti
|
||||
do it for you to maintain privacy.
|
||||
|
||||
If you really want to connect to a raw IP address and know what you're doing, take a look at
|
||||
[`TorAddr::dangerously_from`] -- but be careful!
|
||||
|
||||
### Example: making connections over Tor
|
||||
(This method requires you to initialize the client in an `async fn`. Consider
|
||||
using the builder method, below, if that doesn't work for you.)
|
||||
|
||||
```rust
|
||||
// The client configuration describes how to connect to the Tor network,
|
||||
// and what directories to use for storing persistent state.
|
||||
let config = TorClientConfig::default();
|
||||
// Arti needs a handle to an async runtime in order to spawn tasks and use the
|
||||
// network. (See "Multiple runtime support" below.)
|
||||
let rt = tor_rtcompat::tokio::TokioNativeTlsRuntime::current()?;
|
||||
|
||||
// Start the Arti client, and let it bootstrap a connection to the Tor network.
|
||||
// (This takes a while to gather the necessary directory information.
|
||||
// It uses cached information when possible.)
|
||||
let tor_client = TorClient::bootstrap(rt, config).await?;
|
||||
let tor_client = TorClient::create_bootstrapped(config).await?;
|
||||
```
|
||||
|
||||
### Creating a client and connecting later
|
||||
|
||||
You might wish to create a Tor client immediately, without waiting for it to bootstrap (or
|
||||
having to use an `await`). This can be done by making a [`TorClientBuilder`] with
|
||||
[`TorClient::builder`], and calling [`TorClientBuilder::create_unbootstrapped`].
|
||||
|
||||
The returned client can be made to bootstrap when it is first used (the default), or not;
|
||||
see [`BootstrapBehavior`] for more details.
|
||||
|
||||
```rust
|
||||
// Specifying `BootstrapBehavior::OnDemand` means the client will automatically
|
||||
// bootstrap when it is used. `Manual` exists if you'd rather have full control.
|
||||
let tor_client = TorClient::builder()
|
||||
.bootstrap_behavior(BootstrapBehavior::OnDemand)
|
||||
.create_unbootstrapped()?;
|
||||
```
|
||||
|
||||
### Using the client
|
||||
|
||||
A client can then be used to make connections over Tor with
|
||||
[`TorClient::connect`], which accepts anything implementing [`IntoTorAddr`].
|
||||
This returns a [`DataStream`], an anonymized TCP stream type that implements
|
||||
[`AsyncRead`](futures::io::AsyncRead) and
|
||||
[`AsyncWrite`](futures::io::AsyncWrite), as well as the Tokio versions of
|
||||
those traits if the `tokio` crate feature is enabled.
|
||||
|
||||
### Example: making connections over Tor
|
||||
|
||||
```rust
|
||||
#
|
||||
// Initiate a connection over Tor to example.com, port 80.
|
||||
let mut stream = tor_client.connect(("example.com", 80)).await?;
|
||||
|
||||
|
|
@ -88,59 +110,57 @@ println!("{}", String::from_utf8_lossy(&buf));
|
|||
|
||||
### More advanced usage
|
||||
|
||||
This version of Arti includes basic support for "stream isolation": the ability to ensure that
|
||||
different TCP connections ('streams') go over different Tor circuits (and thus different exit
|
||||
nodes, making them originate from different IP addresses).
|
||||
This version of Arti includes basic support for "stream isolation": the
|
||||
ability to ensure that different TCP connections ('streams') go over
|
||||
different Tor circuits (and thus different exit nodes, making them originate
|
||||
from different IP addresses).
|
||||
|
||||
This is useful to avoid deanonymizing
|
||||
users by correlation: for example, you might want a Tor connection to your bank and a Tor
|
||||
connection to an online forum to use different circuits, to avoid the possibility of the two
|
||||
This is useful to avoid deanonymizing users by correlation: for example, you
|
||||
might want a Tor connection to your bank and a Tor connection to an online
|
||||
forum to use different circuits, to avoid the possibility of the two
|
||||
identities being linked by having the same source IP.
|
||||
|
||||
Streams can be isolated in two ways:
|
||||
|
||||
- by calling [`TorClient::isolated_client`], which returns a new [`TorClient`] whose streams
|
||||
will use a different circuit
|
||||
- by generating [`IsolationToken`]s, and passing them in via [`StreamPrefs`] to
|
||||
[`TorClient::connect`].
|
||||
- by calling [`TorClient::isolated_client`], which returns a new
|
||||
[`TorClient`] whose streams will use a different circuit
|
||||
- by generating [`IsolationToken`]s, and passing them in via [`StreamPrefs`]
|
||||
to [`TorClient::connect`].
|
||||
|
||||
## Multiple runtime support
|
||||
|
||||
Arti uses the [`tor_rtcompat`] crate to support multiple asynchronous runtimes; currently,
|
||||
both [Tokio](https://tokio.rs) and [async-std](https://async.rs) are supported.
|
||||
Arti uses the [`tor_rtcompat`] crate to support multiple asynchronous
|
||||
runtimes; currently, both [Tokio](https://tokio.rs) and
|
||||
[async-std](https://async.rs) are supported.
|
||||
|
||||
Functions in this crate, like [`TorClient::bootstrap`],
|
||||
will expect a type that implements [`tor_rtcompat::Runtime`], which can be obtained:
|
||||
|
||||
- for Tokio:
|
||||
- by calling [`tor_rtcompat::tokio::PreferredRuntime::current()`], if a Tokio reactor is already running
|
||||
- by calling [`tor_rtcompat::tokio::PreferredRuntime::create()`], to start a new reactor if one is not
|
||||
already running
|
||||
- as above, but explicitly specifying [`TokioNativeTlsRuntime`](tor_rtcompat::tokio::TokioNativeTlsRuntime)
|
||||
or [`TokioRustlsRuntime`](tor_rtcompat::tokio::TokioRustlsRuntime) in place of `PreferredRuntime`.
|
||||
- for async-std:
|
||||
- by calling [`tor_rtcompat::async_std::PreferredRuntime::current()`], which will create a runtime or
|
||||
retrieve the existing one, if one has already been started
|
||||
- as above, but explicitly specifying [`AsyncStdNativeTlsRuntime`](tor_rtcompat::async_std::AsyncStdNativeTlsRuntime)
|
||||
or [`AsyncStdRustlsRuntime`](tor_rtcompat::async_std::AsyncStdRustlsRuntime) in place of `PreferredRuntime`.
|
||||
The backend Arti uses for TCP connections ([`tor_rtcompat::TcpProvider`]) and for
|
||||
creating TLS sessions ([`tor_rtcompat::TlsProvider`]) is also configurable using
|
||||
this crate. This can be used to embed Arti in custom environments where you want
|
||||
lots of control over how it uses the network.
|
||||
|
||||
[**View the `tor_rtcompat` crate documentation**](tor_rtcompat) for more about these features.
|
||||
|
||||
## Feature flags
|
||||
|
||||
`tokio` -- (Default) Build with support for the Tokio backend.
|
||||
* `tokio` (default) -- build with [Tokio](https://tokio.rs/) support
|
||||
* `native-tls` (default) -- build with the [native-tls](https://github.com/sfackler/rust-native-tls)
|
||||
crate for TLS support
|
||||
* `async-std` -- build with [async-std](https://async.rs/) support
|
||||
* `rustls` -- build with the [rustls](https://github.com/rustls/rustls) crate for TLS support
|
||||
* `static` -- link with static versions of Arti's system dependencies, like SQLite and
|
||||
OpenSSL (⚠ Warning ⚠: this feature will include a dependency on native-tls, even if you weren't
|
||||
planning to use native-tls. If you only want to build with a static sqlite library, enable the
|
||||
`static-sqlite` feature. We'll look for better solutions here in the future.)
|
||||
* `static-sqlite` -- link with a static version of sqlite.
|
||||
* `static-native-tls` -- link with a static version of `native-tls`. Enables `native-tls`.
|
||||
* `experimental-api` -- build with experimental, unstable API support. Note
|
||||
that these APIs are NOT covered by semantic versioning guarantees: we might
|
||||
break them or remove them between patch versions.
|
||||
* `error_detail` -- expose the `arti_client::Error` inner error type. Note
|
||||
that this API is NOT covered by semantic versioning guarantees: we might
|
||||
break it between patch versions.
|
||||
|
||||
`async-std` -- Build with support for the `async_std` backend.
|
||||
|
||||
`native-tls` (default), `rustls` -- Select TLS libraries to support.
|
||||
|
||||
`static` -- Link with static versions of your system dependencies,
|
||||
including sqlite and/or openssl.
|
||||
|
||||
`experimental-api` -- Build with experimental, unstable API support.
|
||||
Note that these APIs are NOT covered by semantic versioning guarantees:
|
||||
we might break them or remove them between patch versions.
|
||||
|
||||
`error_detail` -- Make the `TorError` type transparent, and expose the `Error` within.
|
||||
Note that the resulting APIs are not stable.
|
||||
Note that flags `tokio`, `native-tls`, `async-std`, `rustls` and `static` will enable
|
||||
the flags of the same name on the [`tor_rtcompat`] crate.
|
||||
|
||||
License: MIT OR Apache-2.0
|
||||
|
|
|
|||
|
|
@ -11,4 +11,12 @@ implement [Tor](https://www.torproject.org/) in Rust.
|
|||
It provides a client configuration tool using using `serde` and `config`,
|
||||
plus extra features defined here for convenience.
|
||||
|
||||
## ⚠ Stability Warning ⚠
|
||||
|
||||
The design of this crate, and of the configuration system for
|
||||
Arti, is likely to change significantly before the release of Arti
|
||||
1.0.0. For more information see ticket [#285].
|
||||
|
||||
[#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
|
||||
|
||||
License: MIT OR Apache-2.0
|
||||
|
|
|
|||
|
|
@ -2,13 +2,12 @@
|
|||
|
||||
High-level layer for making http(s) requests the Tor network as a client.
|
||||
|
||||
## Feature flags
|
||||
This can be used by applications which embed Arti,
|
||||
and could also be used as an example of how to build on top of [`arti_client`].
|
||||
|
||||
`experimental-api` -- Build with experimental, unstable API support.
|
||||
Note that these APIs are NOT covered by semantic versioning guarantees:
|
||||
we might break them or remove them between patch versions.
|
||||
There is an example program [`hyper.rs`] which uses `arti-hyper`
|
||||
to connect to Tor and make a single HTTP\[S] request.
|
||||
|
||||
`native-tls` (default), `rustls` -- Select TLS libraries to use for Tor's purposes.
|
||||
(The end-to-end TLS to the origin server is separate, and handled via `tls-api`.)
|
||||
[`hyper.rs`]: <https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/arti-hyper/examples/hyper.rs>
|
||||
|
||||
License: MIT OR Apache-2.0
|
||||
|
|
|
|||
|
|
@ -42,8 +42,22 @@ For an example see [`arti_defaults.toml`](./arti_defaults.toml).
|
|||
`async-std`: Use the async-std runtime library as our backend.
|
||||
This feature has no effect unless building with `--no-default-features`
|
||||
to disable tokio.
|
||||
`native-tls` -- Build with support for the `native_tls` TLS
|
||||
backend. (default)
|
||||
|
||||
`static`: Try to link a single static binary.
|
||||
`rustls` -- Build with support for the `rustls` TLS backend.
|
||||
|
||||
`static` -- Link with static versions of your system dependencies,
|
||||
including sqlite and/or openssl. (⚠ Warning ⚠: this feature will
|
||||
include a dependency on native-tls, even if you weren't planning
|
||||
to use native-tls. If you only want to build with a static sqlite
|
||||
library, enable the `static-sqlite` feature. We'll look for
|
||||
better solutions here in the future.)
|
||||
|
||||
`static-sqlite` -- Link with a static version of sqlite.
|
||||
|
||||
`static-native-tls` -- Link with a static version of `native-tls`.
|
||||
Enables `native-tls`.
|
||||
|
||||
## Limitations
|
||||
|
||||
|
|
|
|||
|
|
@ -10,4 +10,12 @@ implement [Tor](https://www.torproject.org/) in Rust.
|
|||
|
||||
It provides low-level types for handling configuration values.
|
||||
|
||||
## ⚠ Stability Warning ⚠
|
||||
|
||||
The design of this crate, and of the configuration system for
|
||||
Arti, is likely to change significantly before the release of Arti
|
||||
1.0.0. For more information see ticket [#285].
|
||||
|
||||
[#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
|
||||
|
||||
License: MIT OR Apache-2.0
|
||||
|
|
|
|||
|
|
@ -1,22 +1,11 @@
|
|||
# tor-error
|
||||
|
||||
`tor-error`: Support for error handling in Tor and Ari
|
||||
`tor-error` -- Support for error handling in Tor and Ari
|
||||
|
||||
## Overview
|
||||
Primarily, this crate provides the [`ErrorKind`] enum,
|
||||
and associated [`HasKind`] trait.
|
||||
|
||||
This crate is part of
|
||||
[Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to
|
||||
implement [Tor](https://www.torproject.org/) in Rust.
|
||||
|
||||
Primarily, this crate provides the [`tor_error::ErrorKind`] enum,
|
||||
which can be used by an application embedding the Arti/Tor code to
|
||||
categorise errors so as to respond to them.
|
||||
|
||||
You probably don't want to use this separately from the `tor-*` and `arti-*` crates.
|
||||
|
||||
## Compile-time features
|
||||
|
||||
* `backtrace`: Enables the capturing stack backtraces in internal errors,
|
||||
(via a dependency on the `backtrace` crate). Enabled by default.
|
||||
There is also some other miscellany, supporting error handling in
|
||||
crates higher up the dependency stack.
|
||||
|
||||
License: MIT OR Apache-2.0
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# tor-rtcompat
|
||||
|
||||
Compatibility between different async runtimes for Arti
|
||||
Compatibility between different async runtimes for Arti.
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -57,29 +57,52 @@ You can get a [`Runtime`] in several ways:
|
|||
* If you already have an asynchronous backend (for example, one
|
||||
that you built with tokio by running with
|
||||
`#[tokio::main]`), you can wrap it as a [`Runtime`] with
|
||||
[`current_user_runtime()`].
|
||||
[`PreferredRuntime::current()`].
|
||||
|
||||
* If you want to construct a default runtime that you won't be
|
||||
using for anything besides Arti, you can use [`create_runtime()`].
|
||||
using for anything besides Arti, you can use [`PreferredRuntime::create()`].
|
||||
|
||||
Both of the above methods use the "preferred runtime", which is usually Tokio.
|
||||
However, changing the set of Cargo features available can affect this; see
|
||||
[`PreferredRuntime`] for more.
|
||||
|
||||
* If you want to use a runtime with an explicitly chosen backend,
|
||||
name its type directly as [`async_std::AsyncStdNativeTlsRuntime`],
|
||||
[`async_std::AsyncStdRustlsRuntime`], [`tokio::TokioNativeTlsRuntime`],
|
||||
or [`tokio::TokioRustlsRuntime`]. To construct one of these runtimes,
|
||||
call its `create()` method. Or if you have already constructed a
|
||||
tokio runtime that you want to use, you can wrap it as a
|
||||
Tokio runtime that you want to use, you can wrap it as a
|
||||
[`Runtime`] explicitly with `current()`.
|
||||
|
||||
## Advanced usage: implementing runtimes yourself
|
||||
|
||||
You might want to implement some of the traits above (especially [`TcpProvider`] and
|
||||
[`TlsProvider`]) if you're embedding Arti, and want more control over the resources it uses.
|
||||
For example, you might want to perform actions when TCP connections open and close, replace the
|
||||
TLS stack with your own, or proxy TCP connections over your own custom transport.
|
||||
|
||||
This can be more easily accomplished using the [`CompoundRuntime`] type, which lets you
|
||||
create a [`Runtime`] from various implementors of the various traits (which don't all need to
|
||||
be the same).
|
||||
|
||||
See [`arti-client/examples/hook-tcp.rs`](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/arti-client/examples/hook-tcp.rs)
|
||||
for a full example of this.
|
||||
|
||||
## Cargo features
|
||||
|
||||
`tokio` -- (Default) Build with Tokio support.
|
||||
Features supported by this crate:
|
||||
|
||||
`async-std` -- Build with async_std support.
|
||||
* `tokio` -- build with [Tokio](https://tokio.rs/) support
|
||||
* `async-std` -- build with [async-std](https://async.rs/) support
|
||||
* `native-tls` -- build with the [native-tls](https://github.com/sfackler/rust-native-tls)
|
||||
crate for TLS support
|
||||
* `static` -- link the native TLS library statically (enables the `vendored` feature of the
|
||||
`native-tls` crate).
|
||||
* `rustls` -- build with the [rustls](https://github.com/rustls/rustls) crate for TLS support
|
||||
|
||||
`native-tls`, `rustls` -- Select TLS libraries to support.
|
||||
|
||||
`static` -- Try to link with a static copy of our native TLS library,
|
||||
if possible.
|
||||
By default, *this* crate doesn't enable any features. However, you're almost certainly
|
||||
using this as part of the `arti-client` crate, which will enable `tokio` and `native-tls` in
|
||||
its default configuration.
|
||||
|
||||
## Design FAQ
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue