2020-05-08 00:58:10 +01:00
|
|
|
# arti: A Rust Tor Implementation
|
|
|
|
|
|
|
|
(I'm choosing this name for temporary purposes, but with a nod
|
|
|
|
to the fact that temporary names sometimes stick. Its name is
|
|
|
|
a reference to Tor's semi-acronymic origins as "the onion
|
|
|
|
router", and to the Latin dative singular for "art". It is
|
|
|
|
also short for "artifact". It has nothing to do with the
|
|
|
|
"rt" issue tracker or the "rt" media outlet.)
|
|
|
|
|
|
|
|
## What's here and what isn't.
|
|
|
|
|
|
|
|
So far the code has untested or under-tested implementations of:
|
2020-05-08 01:09:11 +01:00
|
|
|
|
|
|
|
* the ntor protocol
|
2020-05-09 21:36:33 +01:00
|
|
|
* the relay crypto algorithm [cruddy vesion]
|
2020-05-08 01:09:11 +01:00
|
|
|
* parsing and encoding all the cell types (except for hs-related
|
2020-05-09 21:36:33 +01:00
|
|
|
ones). [cruddy version]
|
2020-05-08 01:09:11 +01:00
|
|
|
* parsing and validating ed25519 certificates
|
|
|
|
* parsing and validating router descriptors
|
2020-05-08 00:58:10 +01:00
|
|
|
|
|
|
|
Before I share it, I think it needs more work on:
|
2020-05-08 01:09:11 +01:00
|
|
|
|
|
|
|
* parsing the other kinds of network documents
|
|
|
|
* link authentication
|
2020-05-09 21:36:33 +01:00
|
|
|
* refactoring everywhere
|
|
|
|
* lots of tests
|
2020-05-08 01:09:11 +01:00
|
|
|
* a sensible api for cell types
|
|
|
|
* a toy client that builds a circuit through the network
|
2020-05-08 00:58:10 +01:00
|
|
|
and uses it to exit.
|
|
|
|
|
|
|
|
There is no support yet for:
|
2020-05-08 01:09:11 +01:00
|
|
|
|
|
|
|
* Actually connecting to the network in a reasonable way
|
|
|
|
* choosing paths through the network in a reasonable way
|
|
|
|
* doing anything with the network in a reasonable way
|
|
|
|
* actually building circuits
|
|
|
|
* creating network documents
|
|
|
|
* v2 onion service anything
|
|
|
|
* v3 onion service anything
|
|
|
|
* the directory protocol
|
|
|
|
* lots of optimizations that Tor does
|
|
|
|
* working with no_std
|
2020-05-08 00:58:10 +01:00
|
|
|
|
|
|
|
I do not plan to implement full versions of any of those before I
|
|
|
|
share this code for more comment, though I might do a little. Who
|
|
|
|
knows?
|
|
|
|
|
2020-05-09 21:36:33 +01:00
|
|
|
## What can I do with this?
|
2020-05-08 01:09:11 +01:00
|
|
|
|
|
|
|
You can build this all with `cargo build`.
|
|
|
|
|
|
|
|
You can run the tests, such as they are, with `cargo test`.
|
|
|
|
|
|
|
|
You can make documentation with `cargo doc`. I prefer
|
|
|
|
`cargo doc --no-deps --document-private-items`, to include documentation for
|
|
|
|
private members but not for dependencies.
|
|
|
|
|
2020-05-09 21:36:33 +01:00
|
|
|
## I want to help. What _should_ I do with this?
|
|
|
|
|
|
|
|
More tests would be great.
|
|
|
|
|
|
|
|
Parsing more document types would be great.
|
|
|
|
|
|
|
|
More documentation examples would be great.
|
|
|
|
|
|
|
|
Improvements or bugfixes to the existing code would be great.
|
|
|
|
|
|
|
|
Improving the look and feel of the documentation would also rock.
|
|
|
|
|
|
|
|
I've made a bunch of notes throughout the document in comments with strings
|
|
|
|
like "XXX" or "TODO".
|
|
|
|
|
|
|
|
There is a list of features that I wish other crates had in
|
|
|
|
`WANT_FROM_OTHER_CRATES`.
|
|
|
|
|
|
|
|
Please hold off on opening tickets unless you are pretty sure that you're
|
|
|
|
reporting a problem I don't know about. :)
|
|
|
|
|
|
|
|
|
2020-05-08 00:58:10 +01:00
|
|
|
## Caveat haxxor: what to watch out for
|
|
|
|
|
|
|
|
This is a work in progress. It doesn't "do Tor" yet, and what parts
|
|
|
|
of Tor it does "do" it probably doesn't do securely.
|
|
|
|
|
|
|
|
I'm learning Rust here as I go along. There are probably aspects of
|
|
|
|
the language or its ecosystem that I'm getting wrong.
|
|
|
|
|
|
|
|
Almost nothing about this code should be taken as "final" -- I
|
|
|
|
expect that if anybody wants to make this work for real purposes,
|
|
|
|
we'll need to refactor and move around a whole bunch of code, add a
|
|
|
|
bunch of APIs, split crates, merge crates, and so on.
|
|
|
|
|
|
|
|
There are some places where I am deviating from the existing
|
|
|
|
protocol under the assumption that certain proposals will be
|
|
|
|
accepted. I'll try to document those.
|
|
|
|
|
|
|
|
This code does not try to be indistinguishable from the current Tor
|
|
|
|
implementation.
|
|
|
|
|
|
|
|
## Structure
|
|
|
|
|
|
|
|
To try to keep dependency relationships reasonable, and to follow
|
|
|
|
what I imagine to be best practice, I'm splitting this
|
|
|
|
implementation into a bunch of little crates within a workspace.
|
|
|
|
Crates that are tor-specific start with "tor-"; others don't.
|
|
|
|
|
|
|
|
I expect that the list of crates will have to be reorganized quite a
|
|
|
|
lot by the time we're done.
|
|
|
|
|
|
|
|
The current crates are:
|
|
|
|
|
2020-05-08 01:09:11 +01:00
|
|
|
`caret`: A utility for generating enumerations with helpful trait
|
2020-05-08 00:58:10 +01:00
|
|
|
implementations
|
|
|
|
|
2020-05-08 01:09:11 +01:00
|
|
|
`tor-llcrypto`: Wrappers and re-imports of cryptographic code that Tor needs in
|
2020-05-08 00:58:10 +01:00
|
|
|
various ways. Other crates should use this crate, and not actually
|
|
|
|
use any crypto crates directly
|
|
|
|
|
2020-05-08 01:09:11 +01:00
|
|
|
`tor-bytes`: Byte-by-byte encoder and decoder functions and traits. We use
|
2020-05-08 00:58:10 +01:00
|
|
|
this to safely parse cells, certs, and other byte-oriented things.
|
|
|
|
|
2020-05-08 01:09:11 +01:00
|
|
|
`tor-cert`: Decoding and checking signatures on Tor's ed25519 certificates.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2020-05-08 01:09:11 +01:00
|
|
|
`tor-protover`: Minimal implementation of the Tor subprotocol verisoning
|
|
|
|
system. Less complete than the one in Tor's current src/rust, but more
|
2020-05-08 00:58:10 +01:00
|
|
|
simple.
|
|
|
|
|
2020-05-08 01:09:11 +01:00
|
|
|
`tor-netdoc`: Parsing for Tor's network documents. Currently only handles
|
2020-05-08 00:58:10 +01:00
|
|
|
routerdescs. Underdocumented and too big. needs splitting.
|
|
|
|
|
2020-05-08 01:09:11 +01:00
|
|
|
`tor-proto`: Functions to work with cell types, handshakes, and other aspects
|
2020-05-08 00:58:10 +01:00
|
|
|
of the Tor protocol. Underdocumented, too big, needs
|
|
|
|
refactoring.
|
|
|
|
|
2020-05-08 01:05:47 +01:00
|
|
|
## Intended architecture
|
|
|
|
|
|
|
|
I'm hoping to have small, optional, separable pieces here. For everything
|
|
|
|
I'm writing, I'm hoping it can go behind a configuration flag.
|
|
|
|
|
|
|
|
I'm also hoping to focus on everything that _isn't_ the network first. I'd
|
|
|
|
like as little code as possible to actually read and write to the network,
|
|
|
|
and as much code as possible to pretend that the network doesn't exist. I
|
|
|
|
hope this will make everything easier to test.
|
2020-05-08 00:58:10 +01:00
|
|
|
|
2020-05-08 16:38:24 +01:00
|
|
|
## Licence
|
|
|
|
|
|
|
|
As appears to be standard practice in the Rust ecosystem, this code is
|
|
|
|
licensed under either of
|
|
|
|
|
|
|
|
* [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.)
|