README.md 7.45 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
## Links:
10

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

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

15
   * [Guidelines for contributors](./CONTRIBUTING.md)
16

17
   * [Architectural overview](./doc/Architecture.md)
18

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

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

23
## Why rewrite Tor in Rust?
Nick Mathewson's avatar
Nick Mathewson committed
24

25
26
27
28
29
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
30

31
32
33
34
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
35

36
37
38
39
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
40

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

47

48
## <a name="status"></a>Current status
49

50
Arti can connect to the Tor network, bootstrap a
51
view of the Tor directory, and make anonymized connections over the network.
52
53
Now that Arti has reached version 1.0.0, we believe it is suitable for
actual use to anonymise connections.
54

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

60
And of course it's still very new so there are likely to be bugs.
61

62
## Building and using Arti
63

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

66
67
68
69
70
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.

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

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

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

    $ cargo build -p arti --release

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

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

85
86
### Custom compile-time options

87
88
89
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.
90

91
92
93
See in the
[Arti crate-level docs](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html#compile-time-features)
for details.
94

95
## Using Arti as a library
96

97
98
99
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).
100

101
102
103
That library's API will allow you to
make connections over the Tor network,
and obtain streams/sinks useable from async Rust.
104

Nick Mathewson's avatar
Nick Mathewson committed
105
106
## Minimum supported Rust Version

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

Nick Mathewson's avatar
Nick Mathewson committed
109
110
111
112
113
114
115
116
117
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
118

119
## Helping out
120

121
Have a look at our [contributor guidelines](./CONTRIBUTING.md).
122

123
## Roadmap
Nick Mathewson's avatar
Nick Mathewson committed
124

125
126
127
128
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
129

130
131
132
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
133

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

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

152
153
 * Arti 1.0.0: Initial stable release (Goal: Mid September, 2022??)
   * Target audience: **initial users**
154
   * [x] Stable API (mostly)
155
   * [ ] Stable CLI
156
157
158
159
160
   * [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
161
   * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8)
Nick Mathewson's avatar
Nick Mathewson committed
162

Dimitris Apostolou's avatar
Dimitris Apostolou committed
163
 * Arti 1.1.0: Anti-censorship features (Goal: End of October, 2022?)
164
165
166
167
   * 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
168

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

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

173
 * Arti ?.?.?: Relay support
Nick Mathewson's avatar
Nick Mathewson committed
174

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

183
## How can I help out?
Nick Mathewson's avatar
Nick Mathewson committed
184

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

Dimitris Apostolou's avatar
Dimitris Apostolou committed
188
## License
189

190
This code is licensed under either of
191

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

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