2021-10-29 17:09:43 +01:00
|
|
|
[![Crates.io](https://img.shields.io/crates/v/arti.svg)](https://crates.io/crates/arti)
|
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
# Arti: reimplementing Tor in Rust
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
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.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
## Links:
|
2020-05-09 21:38:12 +01:00
|
|
|
|
2023-05-01 18:33:01 +01:00
|
|
|
This is the README for the Arti project as a whole.
|
|
|
|
If you want find more practical information
|
|
|
|
you might want to check out these links:
|
|
|
|
|
|
|
|
* [The Arti website](https://arti.torproject.org)
|
|
|
|
|
|
|
|
* [The README for the `arti` binary crate](./crates/arti/README.md),
|
|
|
|
which includes instructions for how to run Arti with Tor Browser.
|
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* [Official source repository](https://gitlab.torproject.org/tpo/core/arti)
|
2020-05-09 21:38:12 +01:00
|
|
|
|
2021-10-21 19:15:13 +01:00
|
|
|
* [API-level developer documentation](https://tpo.pages.torproject.net/core/doc/rust/arti_client/index.html)
|
2020-05-09 21:38:12 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* [Guidelines for contributors](./CONTRIBUTING.md)
|
2020-10-18 22:38:28 +01:00
|
|
|
|
2022-12-20 13:04:21 +00:00
|
|
|
* [Architectural overview](./doc/dev/Architecture.md)
|
2020-09-13 02:46:32 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* [Compatibility guide](./doc/Compatibility.md)
|
2020-05-09 21:36:33 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* [Frequently Asked Questions](./doc/FAQ.md)
|
2020-05-09 21:36:33 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
## Why rewrite Tor in Rust?
|
2020-05-09 21:36:33 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
Rust is *more secure than C*. Despite our efforts, it's all too simple to
|
|
|
|
mess up when using a language that does not enforce memory safety. We
|
|
|
|
estimate that at least half of our tracked security vulnerabilities would
|
|
|
|
have been impossible in Rust, and many of the others would have been very
|
|
|
|
unlikely.
|
2020-05-09 21:36:33 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
Rust enables *faster development than C*. Because of Rust's expressiveness
|
|
|
|
and strong guarantees, we've found that we can be far more efficient and
|
|
|
|
confident writing code in Rust. We hope that in the long run this will
|
|
|
|
improve the pace of our software development.
|
2020-05-09 21:36:33 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
Arti is *more flexible than our C tor implementation*. Unlike our C `tor`,
|
|
|
|
which was designed as SOCKS proxy originally, and whose integration features
|
|
|
|
were later "bolted on", Arti is designed from the ground up to work as a
|
|
|
|
modular, embeddable library that other applications can use.
|
2020-05-09 21:36:33 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
Arti is *cleaner than our C tor implementation*. Although we've tried to
|
|
|
|
develop C tor well, we've learned a lot since we started it back in 2002.
|
|
|
|
There are lots of places in the current C codebase where complicated
|
2021-06-17 23:45:05 +01:00
|
|
|
"spaghetti" relationships between different pieces of code make our software
|
2021-06-17 17:18:28 +01:00
|
|
|
needlessly hard to understand and improve.
|
2020-05-09 21:36:33 +01:00
|
|
|
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
## <a name="status"></a>Current status
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
Arti can connect to the Tor network, bootstrap a
|
2021-06-17 17:18:28 +01:00
|
|
|
view of the Tor directory, and make anonymized connections over the network.
|
2022-09-02 14:26:15 +01:00
|
|
|
Now that Arti has reached version 1.0.0, we believe it is suitable for
|
|
|
|
actual use to anonymise connections.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
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.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
And of course it's still very new so there are likely to be bugs.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
## Building and using Arti
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-10-27 16:13:46 +01:00
|
|
|
Arti can act as a SOCKS proxy that uses the Tor network.
|
2020-11-25 15:15:32 +00:00
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
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.
|
|
|
|
|
2022-05-11 13:26:35 +01:00
|
|
|
To try it out, compile and run the `arti` binary using the below. It will open a
|
2021-06-17 17:18:28 +01:00
|
|
|
SOCKS proxy on port 9150.
|
2020-11-25 15:15:32 +00:00
|
|
|
|
2022-05-11 13:26:35 +01:00
|
|
|
$ cargo run -p arti --release -- proxy
|
2020-12-17 15:52:18 +00:00
|
|
|
|
2022-05-11 13:26:35 +01:00
|
|
|
You can build a binary (but not run it) with:
|
|
|
|
|
|
|
|
$ cargo build -p arti --release
|
|
|
|
|
|
|
|
The result can be found as `target/release/arti`.
|
|
|
|
|
2022-01-21 15:51:59 +00:00
|
|
|
If you run into any trouble building the program, please have a
|
|
|
|
look at [the troubleshooting guide](doc/TROUBLESHOOTING.md).
|
|
|
|
|
2022-05-11 13:26:35 +01:00
|
|
|
### Custom compile-time options
|
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
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.
|
2022-05-11 13:26:35 +01:00
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
See in the
|
|
|
|
[Arti crate-level docs](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html#compile-time-features)
|
|
|
|
for details.
|
2022-05-11 13:26:35 +01:00
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
## Using Arti as a library
|
2022-05-11 13:26:35 +01:00
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
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).
|
2022-05-11 13:26:35 +01:00
|
|
|
|
2022-09-02 14:26:15 +01:00
|
|
|
That library's API will allow you to
|
|
|
|
make connections over the Tor network,
|
2023-01-07 18:35:54 +00:00
|
|
|
and obtain streams/sinks usable from async Rust.
|
2022-05-11 13:26:35 +01:00
|
|
|
|
2021-08-24 20:53:43 +01:00
|
|
|
## Minimum supported Rust Version
|
|
|
|
|
2023-04-11 20:33:49 +01:00
|
|
|
Our current Minimum Supported Rust Version (MSRV) is 1.65.
|
2021-08-24 20:53:43 +01:00
|
|
|
|
2022-01-19 14:02:39 +00:00
|
|
|
When increasing this MSRV, we won't require any Rust version released in the
|
|
|
|
last six months. (That is, we'll only require Rust versions released at least
|
|
|
|
six months ago.)
|
|
|
|
|
|
|
|
We will not increase MSRV on PATCH releases, though our dependencies might.
|
|
|
|
|
|
|
|
We won't increase MSRV just because we can: we'll only do so when we have a
|
|
|
|
reason. (We don't guarantee that you'll agree with our reasoning; only that
|
|
|
|
it will exist.)
|
2021-08-24 20:53:43 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
## Helping out
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-06-17 23:45:05 +01:00
|
|
|
Have a look at our [contributor guidelines](./CONTRIBUTING.md).
|
2020-09-26 17:20:46 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
## Roadmap
|
2020-09-10 00:27:47 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
Thanks to a generous grant from
|
|
|
|
[Zcash Open Major Grants (ZOMG)](https://zcashomg.org/), we're able to devote
|
|
|
|
some significant time to Arti in the years 2021-2022. Here is our _rough_
|
|
|
|
set of plans for what we hope to deliver when.
|
2020-11-25 15:15:32 +00:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
The goal times below are complete imagination, based on broad assumptions about
|
|
|
|
developer availability. Please don't take them too seriously until we can
|
|
|
|
get our project manager to sign off on them.
|
2020-11-25 15:15:32 +00:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* Arti 0.0.1: Minimal Secure Client (Goal: end of October 2021??)
|
|
|
|
* Target audience: **developers**
|
2021-10-27 16:13:46 +01:00
|
|
|
* [x] Guard support
|
|
|
|
* [x] Stream Isolation
|
|
|
|
* [x] High test coverage
|
|
|
|
* [x] Draft APIs for basic usage
|
|
|
|
* [x] Code cleanups
|
2021-06-17 17:18:28 +01:00
|
|
|
* [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/6)
|
2020-11-25 15:15:32 +00:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* Arti 0.1.0: Okay for experimental embedding (Goal: Mid March, 2022??)
|
|
|
|
* Target audience: **beta testers**
|
2022-01-11 14:24:07 +00:00
|
|
|
* [x] Performance: preemptive circuit construction
|
|
|
|
* [x] Performance: circuit build timeout inference
|
|
|
|
* [x] API support for embedding
|
2022-02-28 19:25:08 +00:00
|
|
|
* [x] API support for status reporting
|
2022-01-11 14:24:07 +00:00
|
|
|
* [x] Correct timeout behavior
|
2021-06-17 17:18:28 +01:00
|
|
|
* [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/7)
|
2020-11-25 15:15:32 +00:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* Arti 1.0.0: Initial stable release (Goal: Mid September, 2022??)
|
|
|
|
* Target audience: **initial users**
|
2022-09-02 14:26:15 +01:00
|
|
|
* [x] Stable API (mostly)
|
2021-06-17 17:18:28 +01:00
|
|
|
* [ ] Stable CLI
|
2022-09-02 14:26:15 +01:00
|
|
|
* [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
|
2021-06-17 17:18:28 +01:00
|
|
|
* [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8)
|
2020-09-10 00:27:47 +01:00
|
|
|
|
2021-10-25 17:58:42 +01:00
|
|
|
* Arti 1.1.0: Anti-censorship features (Goal: End of October, 2022?)
|
2021-06-17 17:18:28 +01:00
|
|
|
* Target audience: **censored users**
|
2022-11-29 19:51:41 +00:00
|
|
|
* [x] Bridges
|
|
|
|
* [x] Pluggable transports
|
2021-06-17 17:18:28 +01:00
|
|
|
* [and more...?](https://gitlab.torproject.org/tpo/core/arti/-/milestones/10)
|
2021-05-24 17:42:57 +01:00
|
|
|
|
2022-11-29 19:51:41 +00:00
|
|
|
* Arti 1.2.0: Onion service support (timeframe TBD)
|
2021-05-24 17:42:57 +01:00
|
|
|
|
2022-11-29 19:51:41 +00:00
|
|
|
* Arti 2.0.0: Feature parity with C tor as a client (timeframe TBD)
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* Arti ?.?.?: Relay support
|
2020-05-08 01:05:47 +01:00
|
|
|
|
2022-01-21 15:51:59 +00:00
|
|
|
## <a name="reporting-bugs"></a> How can I report bugs?
|
|
|
|
|
|
|
|
When you find bugs, please report them
|
|
|
|
[on our bugtracker](https://gitlab.torproject.org/tpo/core/arti/). If you
|
|
|
|
don't already have an account there, you can either
|
|
|
|
[request an account](https://gitlab.onionize.space/) or
|
|
|
|
[report a bug anonymously](https://anonticket.onionize.space/).
|
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
## How can I help out?
|
2020-05-08 01:05:47 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for a few ideas for how to get
|
|
|
|
started.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-10-25 17:58:42 +01:00
|
|
|
## License
|
2020-05-08 16:38:24 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
This code is licensed under either of
|
2020-05-08 16:38:24 +01:00
|
|
|
|
2022-04-20 12:48:03 +01:00
|
|
|
* [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
|
|
|
|
* [MIT license](https://opensource.org/licenses/MIT)
|
2020-05-08 16:38:24 +01:00
|
|
|
|
|
|
|
at your option.
|
|
|
|
|
|
|
|
## Contribution
|
|
|
|
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally
|
|
|
|
submitted for inclusion in the work by you, as defined in the Apache-2.0
|
|
|
|
license, shall be dual licensed as above, without any additional terms or
|
|
|
|
conditions.
|
|
|
|
|
|
|
|
>(The above notice, or something like it, seems to be pretty standard in Rust
|
|
|
|
>projects, so I'm using it here too. This instance of it is copied from
|
|
|
|
>the RustCrypto project's README.md file.)
|