arti/doc/dev/Architecture.md

Arti: Architectural notes and outline.

Guidelines

I'm hoping to have small, optional, separable pieces here.

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.

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:

• arti-bench -- A simple benchmarking utility for Arti.
• arti-client -- High-level functionality for accessing the Tor network as a client.
• arti-config -- Removed crate. (Tools for configuration management in Arti)
• arti-hyper -- High-level layer for making http(s) requests the Tor network as a client.
• arti -- A minimal command line program for connecting to the Tor network
• arti-testing -- Tool for running an Arti client with unusual behavior or limitations.
• caret -- Integers with some named values.
• fs-mistrust -- Check whether file permissions are private.
• retry-error -- An error attempt to represent multiple failures.
• safelog -- Mark data as sensitive for logging purposes.
• tor-basic-utils -- Utilities (low-level) for Tor
• tor-bytes -- Utilities to decode/encode things into bytes.
• tor-cell -- Coding and decoding for the cell types that make up Tor's protocol
• tor-cert -- Implementation for Tor certificates
• tor-chanmgr -- Manage a set of channels on the Tor network.
• tor-checkable -- Traits for wrapping up signed and/or time-bound objects
• tor-circmgr -- circuits through the Tor network on demand.
• tor-config -- Tools for configuration management in Arti
• tor-congestion -- Algorithms for congestion control on the Tor network
• tor-consdiff -- Restricted ed diff and patch formats for Tor.
• tor-dirclient -- Implements a minimal directory client for Tor.
• tor-dirmgr -- Code to fetch, store, and update Tor directory information.
• tor-error -- Support for error handling in Tor and Arti
• tor-events -- Tools for generating a stream of structured events, similar to C tor's ControlPort.
• tor-guardmgr -- Guard node selection for Tor network clients.
• tor-linkspec -- Descriptions of Tor relays, as used to connect to them.
• tor-llcrypto -- Low-level cryptographic implementations for Tor.
• tor-netdir -- Represents a clients'-eye view of the Tor network.
• tor-netdoc -- Parse and represent directory objects used in Tor.
• tor-persist -- Persistent data storage for use with Tor.
• tor-proto -- Implementations for the core Tor protocol
• tor-protover -- Implementation of Tor's "subprotocol versioning" feature.
• tor-ptmgr -- Manage a set of anti-censorship pluggable transports.
• tor-rtcompat -- Compatibility between different async runtimes for Arti.
• tor-rtmock -- Support for mocking with tor-rtcompat asynchronous runtimes.
• tor-socksproto -- Implements SOCKS in the flavors provided by Tor.
• tor-units -- Safe wrappers for primitive numeric types.

Design considerations, privacy considerations.

As we build the APIs for Arti, we've been aiming for simplicity and safety: we want it to be as easy as possible to use arti-client, while trying to make certain kinds of privacy or security violation hard to write accidentally.

The lower-level we get, however, the more safety we lose. If we need to allow a piece of functionality that isn't safe for general purposes, we usually put it at a more low-level crate.

Privacy isn't just a drop-in feature, however. There are still plenty of ways to accidentally leak information, even if you're anonymizing your connections over Tor. We'll try to document those in a user's guide at some point as Arti becomes more mature.