vincenzopalazzo
/
arti
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'readme' into 'main' 

READMEs: Remove many caveats and general tidying

See merge request tpo/core/arti!717
This commit is contained in:
Nick Mathewson 2022-09-02 16:51:12 +00:00
parent 905aa29a9f f62e2f48d4
commit f5effd320a
7 changed files with 221 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
CONTRIBUTING.md
View File

@ -107,52 +107,6 @@ link to your forked arti repository at:
>
> https://gitlab.torproject.org/_name_/arti/-/merge_requests
## Using Arti with Torbrowser
A good first step to start hacking on arti might be to hook it up with your
Tor Browser. Please note that arti is still a work in progress and hence you
should assume that it **provides no security** at the moment.
To do so, we will launch arti independently from Tor Browser. Build arti with
`cargo build --release`. After that launch it with some basic
configuration parameters:
$ ./target/release/arti proxy -l debug -p 9150
This will ensure that arti sets its SOCKS port on 9150. Now we need to launch
Tor Browser and instruct it to use that SOCKS port.
### Linux
$ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop
### OS X
$ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox
### Windows
Create a shortcut with the `Target` set to:
C:\Windows\System32\cmd.exe /c "SET TOR_SKIP_LAUNCH=1&& SET TOR_SOCKS_PORT=9150&& START /D ^"C:\path\to\Tor Browser\Browser^" firefox.exe"
and `Start in` set to:
"C:\path\to\Tor Browser\Browser"
(You may need to adjust the actual path to wherever you have put your Tor
Browser.)
When you start Tor browser, it will give you a big red error page because
Arti isn't offering it a control port interface. But it will still work!
Try [check.torproject.org](https://check.torproject.org/) to be sure.
The resulting Tor Browser should be using arti. Note that onion services
won't work (Arti doesn't have them yet), and neither will any feature
depending on Tor's control-port protocol.
Enjoy hacking on arti!
## Where are some good places to start hacking?
You might want to begin by looking around the
@ -203,3 +157,5 @@ implementation.
When building the docs with `cargo doc`, use `--all-features`, or you may
find broken links. (We welcome fixes to links broken with `--all-features`.)
Enjoy hacking on arti!

64
README.md
View File

@ -6,8 +6,6 @@ Arti is a project to produce an embeddable, production-quality implementation
of the [Tor](https://www.torproject.org/) anonymity protocols in the
[Rust](https://www.rust-lang.org/) programming language.
Arti is **not ready for production use**; [see below](#status) for more information.
## Links:
* [Official source repository](https://gitlab.torproject.org/tpo/core/arti)
@ -49,32 +47,32 @@ needlessly hard to understand and improve.
## <a name="status"></a>Current status
Arti is a work-in-progress. It can connect to the Tor network, bootstrap a
Arti can connect to the Tor network, bootstrap a
view of the Tor directory, and make anonymized connections over the network.
Now that Arti has reached version 1.0.0, we believe it is suitable for
actual use to anonymise connections.
We're not _aware_ of any critical security features missing in Arti; but
however, since Arti is comparatively new software, you should probably be
cautious about using it in production.
There are a number of areas (especially at the lower layers) where APIs
(especially internal APIs) are not stable,
and are likely to change them.
Right now that includes the command line interface to the `arti` program.
Now that Arti has reached version 0.1.0, we believe it is suitable for
_experimental_ embedding within other Rust applications. We will try to keep
the API as exposed by the top-level `arti_client` crate more or less stable
over time. (We may have to break existing programs from time to time, but we
will try not to do so without a very good reason. Either way, we will try to
follow Rust's semantic versioning best practices.)
And of course it's still very new so there are likely to be bugs.
## Trying it out today
## Building and using Arti
Arti can act as a SOCKS proxy that uses the Tor network.
We expect to be providing official binaries soon.
But, for now, you need to obtain a
[Rust](https://www.rust-lang.org/) development environment,
and build it yourself.
To try it out, compile and run the `arti` binary using the below. It will open a
SOCKS proxy on port 9150.
$ cargo run -p arti --release -- proxy
Again, do not use this program yet if you seriously need anonymity, privacy,
security, or stability.
You can build a binary (but not run it) with:
$ cargo build -p arti --release
@ -86,19 +84,23 @@ look at [the troubleshooting guide](doc/TROUBLESHOOTING.md).
### Custom compile-time options
Arti has a number of configurable [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html) that,
among other things, can affect which asynchronous runtime to use. Use
Arti has a number of configurable
[Cargo features](https://doc.rust-lang.org/cargo/reference/features.html)
that, among other things, can affect which asynchronous runtime to use.
$ cargo doc -p arti --open
See in the
[Arti crate-level docs](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html#compile-time-features)
for details.
to view the Arti crate-level docs in your browser, which contain a full list.
## Using Arti as a library
You can pass these features to Cargo while building with `--features` (note that you might need `--no-default-features`
in order to not use the default runtime choices, too). For example, to use `async-std` instead of Tokio:
The `arti` command line utility is built on top of the
[`arti_client`](https://tpo.pages.torproject.net/core/doc/rust/arti_client/index.html)
library (and its dependencies).
$ cargo run -p arti --no-default-features --features async-std,native-tls -- proxy
Use `target/release/arti --version` to see what features the currently built Arti binary is using.
That library's API will allow you to
make connections over the Tor network,
and obtain streams/sinks useable from async Rust.
## Minimum supported Rust Version
@ -149,13 +151,13 @@ get our project manager to sign off on them.
* Arti 1.0.0: Initial stable release (Goal: Mid September, 2022??)
* Target audience: **initial users**
* [ ] Stable API
* [x] Stable API (mostly)
* [ ] Stable CLI
* [ ] Stable configuration format
* [ ] Automatic detection and response of more kinds of network problems
* [ ] At least as secure as C Tor
* [ ] Client performance similar to C Tor
* [ ] More performance work
* [x] Stable configuration format
* [x] Automatic detection and response of more kinds of network problems
* [x] At least as secure as C Tor
* [x] Client performance similar to C Tor
* [x] More performance work
* [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8)
* Arti 1.1.0: Anti-censorship features (Goal: End of October, 2022?)

23
crates/arti-client/README.md
View File

@ -13,18 +13,27 @@ 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 ⚠
### Shape of the API, and relationship to other crates
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.)
The API here is great if you are building an application in async Rust
and want your Tor connections as async streams (`AsyncRead`/`AsyncWrite`).
If you are wanting to make HTTP requests,
look at [arti_hyper](https://tpo.pages.torproject.net/core/doc/rust/arti_hyper/index.html)).
If you are trying to glue Arti to some other programming language,
right now your best bet is probably to spawn the
[`arti` CLI](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html)
SOCKS proxy,
as a subprocess.
We don't yet offer an API that would be nice to expose via FFI;
we intend to add this in the future.
### ⚠ Warnings ⚠
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.
between now and us declaring `arti-client` 1.x.
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.

9
crates/arti-client/src/config.rs
View File

@ -1,15 +1,6 @@
//! Types and functions to configure a Tor client.
//!
//! Some of these are re-exported from lower-level crates.
//!
//! # ⚠ Stability Warning ⚠
//!
//! The design of this structure, and of the configuration system for
//! Arti, is likely to change significantly before the release of Arti
//! 1.0.0. The layout of options within this structure is also likely
//! to change. For more information see ticket [#285].
//!
//! [#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
use derive_builder::Builder;
use derive_more::AsRef;

23
crates/arti-client/src/lib.rs
View File

@ -12,18 +12,27 @@
//! programs should use. Most of its functionality is provided by lower-level
//! crates in Arti.
//!
//! ## ⚠ Warnings ⚠
//! ## Shape of the API, and relationship to other crates
//!
//! 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.)
//! The API here is great if you are building an application in async Rust
//! and want your Tor connections as async streams (`AsyncRead`/`AsyncWrite`).
//! If you are wanting to make HTTP requests,
//! look at [arti_hyper](https://tpo.pages.torproject.net/core/doc/rust/arti_hyper/index.html)).
//!
//! If you are trying to glue Arti to some other programming language,
//! right now your best bet is probably to spawn the
//! [`arti` CLI](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html)
//! SOCKS proxy,
//! as a subprocess.
//! We don't yet offer an API that would be nice to expose via FFI;
//! we intend to add this in the future.
//!
//! ## ⚠ Warnings ⚠
//!
//! 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.
//! between now and us declaring `arti-client` 1.x.
//!
//! 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.

89
crates/arti/README.md
View File

@ -1,22 +1,26 @@
# arti
A minimal command line program for connecting to the tor network
A minimal command line program for connecting to the Tor network
(If you want a more general Tor client library interface, use
[`arti_client`].)
This crate is the primary command-line interface for
[Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to implement
[Tor](https://www.torproject.org/) in Rust. Many other crates in Arti depend
on it.
[Tor](https://www.torproject.org/) in Rust.
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.
Currently Arti can can run as a simple SOCKS proxy over the Tor network.
It will listen on port 9150 by default,
but you can override this in the configuration.
You can direct programs to connect via that SOCKS port,
and their connections will be anonymized via Tor.
Note: you might not want to run a conventional web browser this way.
Browsers leak much private information.
To browse the web anonymously,
we recommend [using Tor Browser](#using-arti-with-tor-browser).
More documentation will follow as this program improves. For now, just know
that it can run as a simple SOCKS proxy over the Tor network. It will listen
on port 9150 by default, but you can override this in the configuration.
Arti is still advancing rapidly; we are adding features and eventually
we hope it will be able to replace C Tor.
## Command-line interface
@ -39,8 +43,69 @@ location.
| macOS | `~/Library/Application Support/arti/arti.toml` |
| Windows | `\Users\<USERNAME>\AppData\Roaming\arti\arti.toml` |
The configuration file is TOML. (We do not guarantee its stability.) For an
example see [`arti_defaults.toml`](./arti_defaults.toml).
The configuration file is TOML.
For an example see `arti-example-config.toml`
(a copy of which is in the source tree,
and also
[in the Arti repository](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/arti/src/arti-example-config.toml)).
That example config file documents the configuration options.
More detailed information about for the individual fields is available in the documentation
for the Rust APIs [`ApplicationConfigBuilder`] and
[`TorClientConfigBuilder`](arti_client::config::TorClientConfigBuilder).
## Using Arti with Tor Browser
It is possible to hook up Arti with
[Tor Browser](https://www.torproject.org/download/).
To do so, we will launch arti independently from Tor Browser. Build arti with
`cargo build --release`. After that launch it with some basic
configuration parameters:
```
$ ./target/release/arti proxy -l debug -p 9150
```
This will ensure that arti sets its SOCKS port on 9150. Now we need to launch
Tor Browser and instruct it to use that SOCKS port.
#### Linux
```
$ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop
```
#### OS X
```
$ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox
```
#### Windows
Create a shortcut with the `Target` set to:
```
C:\Windows\System32\cmd.exe /c "SET TOR_SKIP_LAUNCH=1&& SET TOR_SOCKS_PORT=9150&& START /D ^"C:\path\to\Tor Browser\Browser^" firefox.exe"
```
and `Start in` set to:
```
"C:\path\to\Tor Browser\Browser"
```
(You may need to adjust the actual path to wherever you have put your Tor
Browser.)
When you start Tor browser, it will give you a big red error page because
Arti isn't offering it a control port interface. But it will still work!
Try [check.torproject.org](https://check.torproject.org/) to be sure.
The resulting Tor Browser should be using arti. Note that onion services
won't work (Arti doesn't have them yet), and neither will any feature
depending on Tor's control-port protocol.
## Compile-time features
@ -113,7 +178,7 @@ There are many missing features. Among them: there's no onion service
support yet. There's no anti-censorship support. You can't be a relay.
There isn't any kind of proxy besides SOCKS.
See the [README
See the [repository README
file](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/README.md) for
a more complete list of missing features.

89
crates/arti/src/lib.rs
View File

@ -1,21 +1,25 @@
#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
//! A minimal command line program for connecting to the tor network
//! A minimal command line program for connecting to the Tor network
//!
//! (If you want a more general Tor client library interface, use
//! [`arti_client`].)
//!
//! This crate is the primary command-line interface for
//! [Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to implement
//! [Tor](https://www.torproject.org/) in Rust. Many other crates in Arti depend
//! on it.
//! [Tor](https://www.torproject.org/) in Rust.
//!
//! 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.
//! Currently Arti can can run as a simple SOCKS proxy over the Tor network.
//! It will listen on port 9150 by default,
//! but you can override this in the configuration.
//! You can direct programs to connect via that SOCKS port,
//! and their connections will be anonymized via Tor.
//! Note: you might not want to run a conventional web browser this way.
//! Browsers leak much private information.
//! To browse the web anonymously,
//! we recommend [using Tor Browser](#using-arti-with-tor-browser).
//!
//! More documentation will follow as this program improves. For now, just know
//! that it can run as a simple SOCKS proxy over the Tor network. It will listen
//! on port 9150 by default, but you can override this in the configuration.
//! Arti is still advancing rapidly; we are adding features and eventually
//! we hope it will be able to replace C Tor.
//!
//! # Command-line interface
//!
@ -38,8 +42,69 @@
//! | macOS | `~/Library/Application Support/arti/arti.toml` |
//! | Windows | `\Users\<USERNAME>\AppData\Roaming\arti\arti.toml` |
//!
//! The configuration file is TOML. (We do not guarantee its stability.) For an
//! example see [`arti_defaults.toml`](./arti_defaults.toml).
//! The configuration file is TOML.
//! For an example see `arti-example-config.toml`
//! (a copy of which is in the source tree,
//! and also
//! [in the Arti repository](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/arti/src/arti-example-config.toml)).
//! That example config file documents the configuration options.
//!
//! More detailed information about for the individual fields is available in the documentation
//! for the Rust APIs [`ApplicationConfigBuilder`] and
//! [`TorClientConfigBuilder`](arti_client::config::TorClientConfigBuilder).
//!
//! # Using Arti with Tor Browser
//!
//! It is possible to hook up Arti with
//! [Tor Browser](https://www.torproject.org/download/).
//!
//! To do so, we will launch arti independently from Tor Browser. Build arti with
//! `cargo build --release`. After that launch it with some basic
//! configuration parameters:
//!
//! ```text
//! $ ./target/release/arti proxy -l debug -p 9150
//! ```
//!
//! This will ensure that arti sets its SOCKS port on 9150. Now we need to launch
//! Tor Browser and instruct it to use that SOCKS port.
//!
//! ### Linux
//!
//! ```text
//! $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop
//! ```
//!
//! ### OS X
//!
//! ```text
//! $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox
//! ```
//!
//! ### Windows
//!
//! Create a shortcut with the `Target` set to:
//!
//! ```text
//! C:\Windows\System32\cmd.exe /c "SET TOR_SKIP_LAUNCH=1&& SET TOR_SOCKS_PORT=9150&& START /D ^"C:\path\to\Tor Browser\Browser^" firefox.exe"
//! ```
//!
//! and `Start in` set to:
//!
//! ```text
//! "C:\path\to\Tor Browser\Browser"
//! ```
//!
//! (You may need to adjust the actual path to wherever you have put your Tor
//! Browser.)
//!
//! When you start Tor browser, it will give you a big red error page because
//! Arti isn't offering it a control port interface. But it will still work!
//! Try [check.torproject.org](https://check.torproject.org/) to be sure.
//!
//! The resulting Tor Browser should be using arti. Note that onion services
//! won't work (Arti doesn't have them yet), and neither will any feature
//! depending on Tor's control-port protocol.
//!
//! # Compile-time features
//!
@ -112,7 +177,7 @@
//! support yet. There's no anti-censorship support. You can't be a relay.
//! There isn't any kind of proxy besides SOCKS.
//!
//! See the [README
//! See the [repository README
//! file](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/README.md) for
//! a more complete list of missing features.
//!