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
|
|
|
Arti is **not ready for production use**; [see below](#status) for more information.
|
2021-06-09 19:36:59 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
## Links:
|
2020-05-09 21:38:12 +01:00
|
|
|
|
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
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* [Architectural overview](./doc/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
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
Arti is a work-in-progress. It can connect to the Tor network, bootstrap a
|
|
|
|
view of the Tor directory, and make anonymized connections over the network.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-10-27 16:13:46 +01:00
|
|
|
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.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-10-27 16:13:46 +01:00
|
|
|
There are no guarantees about API stability yet: if you write code
|
|
|
|
that uses Arti, you should expect it to break with future versions. If you
|
|
|
|
write an a configuration file for Arti, it might stop working in the future.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
## Trying it out today
|
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.
|
|
|
|
It knows how to download directory
|
2021-06-17 17:18:28 +01:00
|
|
|
information and how to load it from cache, but it doesn't try to
|
|
|
|
download more than one directory per run.
|
2020-11-25 15:15:32 +00:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
To try it out, run the demo program in `arti` as follows. It will open a
|
|
|
|
SOCKS proxy on port 9150.
|
2020-11-25 15:15:32 +00:00
|
|
|
|
Improve and future-proof the `arti` CLI
This switches out `arti`'s argument-parsing library with `clap`, which
is a lot more featureful (and very widely used within the Rust
ecosystem). We also now use a lot of `clap`'s features to improve the
CLI experience:
- The CLI now expects a subcommand (currently, either "help", or "proxy"
for the existing SOCKS proxy behaviour). This should let us add
additional non-SOCKS-proxy features to arti in future.
- `clap` supports default values determined at runtime, so the way the
default config file is loaded was changed: now, we determine the
OS-specific path for said file before invoking `clap`, so the help
command can show it properly.
- The behaviour of `tor_config` was also changed; now, one simply
specifies a list of configuration files to load, together with
whether they're required.
- That function also way overused generics; this has been fixed.
- Instead of using the ARTI_LOG environment variable to configure
logging, one now uses the `-l, --log-level` CLI option.
(The intent is for this option to be more discoverable by users.)
- The `proxy` subcommand allows the user to override the SOCKS port used
on the CLI without editing the config file.
2021-10-27 17:40:00 +01:00
|
|
|
% cargo run --release -- proxy
|
2020-12-17 15:52:18 +00:00
|
|
|
|
2021-10-27 16:13:46 +01:00
|
|
|
Again, do not use this program yet if you seriously need anonymity, privacy,
|
|
|
|
security, or stability.
|
2020-09-10 00:27:47 +01:00
|
|
|
|
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).
|
|
|
|
|
2021-08-24 20:53:43 +01:00
|
|
|
## Minimum supported Rust Version
|
|
|
|
|
2022-01-19 14:02:39 +00:00
|
|
|
Our current Minimum Supported Rust Version (MSRV) is 1.53.
|
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
|
2021-06-17 17:18:28 +01:00
|
|
|
* [ ] 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**
|
|
|
|
* [ ] Security audit
|
|
|
|
* [ ] Stable API
|
|
|
|
* [ ] Stable CLI
|
|
|
|
* [ ] Stable configuration format
|
|
|
|
* [ ] Automatic detection and response of more kinds of network problems
|
|
|
|
* [ ] More performance work
|
|
|
|
* [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**
|
|
|
|
* [ ] Bridges
|
|
|
|
* [ ] Pluggable transports
|
|
|
|
* [and more...?](https://gitlab.torproject.org/tpo/core/arti/-/milestones/10)
|
2021-05-24 17:42:57 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* Arti 1.2.0: Onion service support (not funded, timeframe TBD)
|
2021-05-24 17:42:57 +01:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
* Arti 2.0.0: Feature parity with C tor as a client (not funded, 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
|
|
|
|
|
|
|
* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
|
|
|
|
* [MIT license](http://opensource.org/licenses/MIT)
|
|
|
|
|
|
|
|
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.)
|