/ README.md
README.md
1 2 > [!IMPORTANT] 3 > This is an unofficial mirror of [Arti](https://github.com/zydou/arti). It can be downloaded bia a direct connection to this node over Tor, or through the radicle network. 4 5 6 [](https://crates.io/crates/arti) 7 8 # Arti: reimplementing Tor in Rust 9 10 Arti is a project to produce an embeddable, production-quality implementation 11 of the [Tor](https://www.torproject.org/) anonymity protocols in the 12 [Rust](https://www.rust-lang.org/) programming language. 13 14 ## Links: 15 16 This is the README for the Arti project as a whole. 17 If you want find more practical information 18 you might want to check out these links: 19 20 * [The Arti website](https://arti.torproject.org) 21 22 * [The README for the `arti` binary crate](./crates/arti/README.md), 23 which includes instructions for how to run Arti with Tor Browser. 24 25 * [Official source repository](https://gitlab.torproject.org/tpo/core/arti) 26 27 * [API-level developer documentation](https://tpo.pages.torproject.net/core/doc/rust/arti_client/index.html) 28 29 * [Guidelines for contributors](./CONTRIBUTING.md) 30 31 * [Architectural overview](./doc/dev/Architecture.md) 32 33 * [Compatibility guide](./doc/Compatibility.md) 34 35 * [Frequently Asked Questions](./doc/FAQ.md) 36 37 ## Why rewrite Tor in Rust? 38 39 Rust is *more secure than C*. Despite our efforts, it's all too simple to 40 mess up when using a language that does not enforce memory safety. We 41 estimate that at least half of our tracked security vulnerabilities would 42 have been impossible in Rust, and many of the others would have been very 43 unlikely. 44 45 Rust enables *faster development than C*. Because of Rust's expressiveness 46 and strong guarantees, we've found that we can be far more efficient and 47 confident writing code in Rust. We hope that in the long run this will 48 improve the pace of our software development. 49 50 Arti is *more flexible than our C tor implementation*. Unlike our C `tor`, 51 which was designed as SOCKS proxy originally, and whose integration features 52 were later "bolted on", Arti is designed from the ground up to work as a 53 modular, embeddable library that other applications can use. 54 55 Arti is *cleaner than our C tor implementation*. Although we've tried to 56 develop C tor well, we've learned a lot since we started it back in 2002. 57 There are lots of places in the current C codebase where complicated 58 "spaghetti" relationships between different pieces of code make our software 59 needlessly hard to understand and improve. 60 61 62 ## <a name="status"></a>Current status 63 64 Arti can connect to the Tor network, bootstrap a 65 view of the Tor directory, and make anonymized connections over the network. 66 Now that Arti has reached version 1.0.0, we believe it is suitable for 67 actual use to anonymise connections. 68 69 There are a number of areas (especially at the lower layers) where APIs 70 (especially internal APIs) are not stable, 71 and are likely to change them. 72 Right now that includes the command line interface to the `arti` program. 73 74 And of course it's still very new so there are likely to be bugs. 75 76 ## Building and using Arti 77 78 Arti can act as a SOCKS proxy that uses the Tor network. 79 80 We expect to be providing official binaries soon. 81 But, for now, you need to obtain a 82 [Rust](https://www.rust-lang.org/) development environment, 83 and build it yourself. 84 85 To try it out, compile and run the `arti` binary using the below. It will open a 86 SOCKS proxy on port 9150. 87 88 $ cargo run -p arti --locked --release -- proxy 89 90 You can build a binary (but not run it) with: 91 92 $ cargo build -p arti --locked --release 93 94 The result can be found as `target/release/arti`. 95 96 ⚠ **Safety Note**: if you are using the default build options, 97 the compiler will include filesystem path information in the 98 binary that it generates. If your path is sensitive (for example, 99 because it includes your username), you will want to take steps 100 to prevent this. See [`doc/safer-build.md`](doc/safer-build.md) 101 for more information. 102 103 104 If you run into any trouble building the program, please have a 105 look at [the troubleshooting guide](doc/TROUBLESHOOTING.md). 106 107 ### Custom compile-time options 108 109 Arti has a number of configurable 110 [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html) 111 that, among other things, can affect which asynchronous runtime to use. 112 113 See in the 114 [Arti crate-level docs](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html#compile-time-features) 115 for details. 116 117 ## Using Arti as a library 118 119 The `arti` command line utility is built on top of the 120 [`arti_client`](https://tpo.pages.torproject.net/core/doc/rust/arti_client/index.html) 121 library (and its dependencies). 122 123 That library's API will allow you to 124 make connections over the Tor network, 125 and obtain streams/sinks usable from async Rust. 126 127 We make fairly frequent semver bumps the Arti library API, 128 and to our lower-level crates. 129 However, in practice, we don't often make disruptive changes 130 that aren't easy to sort out in a dependency. 131 When using Arti as a library, you should be prepared to make regular updates, 132 bumping your versions requirement, not just `cargo update`. 133 `cargo upgrade` can help with this. 134 135 See [our version update and API compatibility policy](doc/Semver.md) 136 for more details. 137 138 ## Minimum supported Rust Version 139 140 Our current Minimum Supported Rust Version (MSRV) is 1.77. 141 142 When increasing this MSRV, we won't require any Rust version released in the 143 last six months. (That is, we'll only require Rust versions released at least 144 six months ago.) 145 146 We will not increase MSRV on PATCH releases, though our dependencies might. 147 148 We won't increase MSRV just because we can: we'll only do so when we have a 149 reason. (We don't guarantee that you'll agree with our reasoning; only that 150 it will exist.) 151 152 ## Helping out 153 154 Have a look at our [contributor guidelines](./CONTRIBUTING.md). 155 156 ## Roadmap 157 158 Thanks to a generous grant from 159 [Zcash Open Major Grants (ZOMG)](https://zcashomg.org/), we're able to devote 160 some significant time to Arti in the years 2021-2022. Here is our _rough_ 161 set of plans for what we hope to deliver when. 162 163 The goal times below are complete imagination, based on broad assumptions about 164 developer availability. Please don't take them too seriously until we can 165 get our project manager to sign off on them. 166 167 * Arti 0.0.1: Minimal Secure Client (Goal: end of October 2021??) 168 * Target audience: **developers** 169 * [x] Guard support 170 * [x] Stream Isolation 171 * [x] High test coverage 172 * [x] Draft APIs for basic usage 173 * [x] Code cleanups 174 * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/6) 175 176 * Arti 0.1.0: Okay for experimental embedding (Goal: Mid March, 2022??) 177 * Target audience: **beta testers** 178 * [x] Performance: preemptive circuit construction 179 * [x] Performance: circuit build timeout inference 180 * [x] API support for embedding 181 * [x] API support for status reporting 182 * [x] Correct timeout behavior 183 * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/7) 184 185 * Arti 1.0.0: Initial stable release (Goal: Mid September, 2022??) 186 * Target audience: **initial users** 187 * [x] Stable API (mostly) 188 * [ ] Stable CLI 189 * [x] Stable configuration format 190 * [x] Automatic detection and response of more kinds of network problems 191 * [x] At least as secure as C Tor 192 * [x] Client performance similar to C Tor 193 * [x] More performance work 194 * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8) 195 196 * Arti 1.1.0: Anti-censorship features (Goal: End of October, 2022?) 197 * Target audience: **censored users** 198 * [x] Bridges 199 * [x] Pluggable transports 200 * [and more...?](https://gitlab.torproject.org/tpo/core/arti/-/milestones/10) 201 202 * Arti ~1.2.0: [Onion service]() support (Goal: End of 2023) 203 * [x] [Client support](https://gitlab.torproject.org/tpo/core/arti/-/issues/?label_name%5B%5D=Onion%20Services%3A%20Basic%20Client) (for connecting to onion services) 204 * [x] [Service support](https://gitlab.torproject.org/tpo/core/arti/-/issues/?sort=created_date&state=opened&label_name%5B%5D=Onion%20Services%3A%20Basic%20Service&first_page_size=100) (for running onion services) 205 * [ ] [Full security features](https://gitlab.torproject.org/tpo/core/arti/-/issues/?label_name%5B%5D=Onion%20Services%3A%20Improved%20Security) (for production-ready quality) 206 207 * Arti ~2.0.0: Feature parity with C tor as a client (Goal: Mid 2024) 208 * [some possible details...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/9#tab-issues) 209 210 * Arti ?.?.?: Relay support 211 212 ## <a name="reporting-bugs"></a> How can I report bugs? 213 214 When you find bugs, please report them 215 [on our bugtracker](https://gitlab.torproject.org/tpo/core/arti/). If you 216 don't already have an account there, you can either 217 [request an account](https://gitlab.onionize.space/) or 218 [report a bug anonymously](https://anonticket.torproject.org/). 219 220 ## How can I help out? 221 222 See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for a few ideas for how to get 223 started. 224 225 ## License 226 227 This code is licensed under either of 228 229 * [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) 230 * [MIT license](https://opensource.org/licenses/MIT) 231 232 at your option. 233 234 **However**, some optional parts are licensed under the GNU Lesser General 235 Public License, version 3.0, 236 as indicated in the `Cargo.toml`. 237 This applies to `crates/equix` and `crates/hashx`. 238 See [`LGPL-and-rust.md`](./doc/LGPL-and-rust.md) 239 for discussion of issues concerning redistributing binaries 240 containing these crates. 241 242 243 ## Contribution 244 245 Unless you explicitly state otherwise, any contribution intentionally 246 submitted for inclusion in the work by you, as defined in the Apache-2.0 247 license, shall be dual licensed as above, without any additional terms or 248 conditions. 249 250 >(The above notice, or something like it, seems to be pretty standard in Rust 251 >projects, so I'm using it here too. This instance of it is copied from 252 >the RustCrypto project's README.md file.)