README.md 7.76 KB
Newer Older
1
2
[![Crates.io](https://img.shields.io/crates/v/arti.svg)](https://crates.io/crates/arti)

3
# Arti: reimplementing Tor in Rust
4

5
6
7
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.
8

9
Arti is **not ready for production use**; [see below](#status) for more information.
Nick Mathewson's avatar
Nick Mathewson committed
10

11
## Links:
12

13
   * [Official source repository](https://gitlab.torproject.org/tpo/core/arti)
14

15
   * [API-level developer documentation](https://tpo.pages.torproject.net/core/doc/rust/arti_client/index.html)
16

17
   * [Guidelines for contributors](./CONTRIBUTING.md)
18

19
   * [Architectural overview](./doc/Architecture.md)
20

21
   * [Compatibility guide](./doc/Compatibility.md)
Nick Mathewson's avatar
Nick Mathewson committed
22

23
   * [Frequently Asked Questions](./doc/FAQ.md)
Nick Mathewson's avatar
Nick Mathewson committed
24

25
## Why rewrite Tor in Rust?
Nick Mathewson's avatar
Nick Mathewson committed
26

27
28
29
30
31
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.
Nick Mathewson's avatar
Nick Mathewson committed
32

33
34
35
36
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.
Nick Mathewson's avatar
Nick Mathewson committed
37

38
39
40
41
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.
Nick Mathewson's avatar
Nick Mathewson committed
42

43
44
45
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
46
"spaghetti" relationships between different pieces of code make our software
47
needlessly hard to understand and improve.
Nick Mathewson's avatar
Nick Mathewson committed
48

49

50
## <a name="status"></a>Current status
51

52
53
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.
54

55
56
57
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.
58

59
60
61
62
63
64
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.)
65

66
## Trying it out today
67

68
Arti can act as a SOCKS proxy that uses the Tor network.
Nick Mathewson's avatar
Nick Mathewson committed
69

70
To try it out, compile and run the `arti` binary using the below. It will open a
71
SOCKS proxy on port 9150.
Nick Mathewson's avatar
Nick Mathewson committed
72

73
    $ cargo run -p arti --release -- proxy
74

75
76
Again, do not use this program yet if you seriously need anonymity, privacy,
security, or stability.
Nick Mathewson's avatar
Nick Mathewson committed
77

78
79
80
81
82
83
You can build a binary (but not run it) with:

    $ cargo build -p arti --release

The result can be found as `target/release/arti`.

84
85
86
If you run into any trouble building the program, please have a
look at [the troubleshooting guide](doc/TROUBLESHOOTING.md).

87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
### 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

    $ cargo doc -p arti --open

to view the Arti crate-level docs in your browser, which contain a full list.

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:

    $ 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.

Nick Mathewson's avatar
Nick Mathewson committed
103
104
## Minimum supported Rust Version

Nick Mathewson's avatar
Nick Mathewson committed
105
Our current Minimum Supported Rust Version (MSRV) is 1.56.
Nick Mathewson's avatar
Nick Mathewson committed
106

Nick Mathewson's avatar
Nick Mathewson committed
107
108
109
110
111
112
113
114
115
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.)
Nick Mathewson's avatar
Nick Mathewson committed
116

117
## Helping out
118

119
Have a look at our [contributor guidelines](./CONTRIBUTING.md).
120

121
## Roadmap
Nick Mathewson's avatar
Nick Mathewson committed
122

123
124
125
126
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.
Nick Mathewson's avatar
Nick Mathewson committed
127

128
129
130
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.
Nick Mathewson's avatar
Nick Mathewson committed
131

132
133
 * Arti 0.0.1: Minimal Secure Client (Goal: end of October 2021??)
   * Target audience: **developers**
134
135
136
137
138
   * [x] Guard support
   * [x] Stream Isolation
   * [x] High test coverage
   * [x] Draft APIs for basic usage
   * [x] Code cleanups
139
   * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/6)
Nick Mathewson's avatar
Nick Mathewson committed
140

141
142
 * Arti 0.1.0: Okay for experimental embedding (Goal: Mid March, 2022??)
   * Target audience: **beta testers**
143
144
145
   * [x] Performance: preemptive circuit construction
   * [x] Performance: circuit build timeout inference
   * [x] API support for embedding
146
   * [x] API support for status reporting
147
   * [x] Correct timeout behavior
148
   * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/7)
Nick Mathewson's avatar
Nick Mathewson committed
149

150
151
152
153
154
155
 * Arti 1.0.0: Initial stable release (Goal: Mid September, 2022??)
   * Target audience: **initial users**
   * [ ] Stable API
   * [ ] Stable CLI
   * [ ] Stable configuration format
   * [ ] Automatic detection and response of more kinds of network problems
156
157
   * [ ] At least as secure as C Tor
   * [ ] Client performance similar to C Tor
158
159
   * [ ] More performance work
   * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8)
Nick Mathewson's avatar
Nick Mathewson committed
160

Dimitris Apostolou's avatar
Dimitris Apostolou committed
161
 * Arti 1.1.0: Anti-censorship features (Goal: End of October, 2022?)
162
163
164
165
   * Target audience: **censored users**
   * [ ] Bridges
   * [ ] Pluggable transports
   * [and more...?](https://gitlab.torproject.org/tpo/core/arti/-/milestones/10)
Nick Mathewson's avatar
Nick Mathewson committed
166

167
 * Arti 1.2.0: Onion service support (not funded, timeframe TBD)
Nick Mathewson's avatar
Nick Mathewson committed
168

169
 * Arti 2.0.0: Feature parity with C tor as a client (not funded, timeframe TBD)
170

171
 * Arti ?.?.?: Relay support
Nick Mathewson's avatar
Nick Mathewson committed
172

173
174
175
176
177
178
179
180
## <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/).

181
## How can I help out?
Nick Mathewson's avatar
Nick Mathewson committed
182

183
184
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for a few ideas for how to get
started.
185

Dimitris Apostolou's avatar
Dimitris Apostolou committed
186
## License
187

188
This code is licensed under either of
189

Samanta Navarro's avatar
Samanta Navarro committed
190
191
 * [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
 * [MIT license](https://opensource.org/licenses/MIT)
192
193
194
195
196
197
198
199
200
201
202
203
204

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.)