src/mainpage.md

   1 @mainpage Tor source reference
   2
   3 @tableofcontents
   4
   5 @section welcome Welcome to Tor
   6
   7 (For an up-to-date rendered copy of this documentation, see
   8 https://src-ref.docs.torproject.org/tor/index.html .)
   9
  10 This documentation describes the general structure of the Tor codebase, how
  11 it fits together, what functionality is available for extending Tor, and
  12 gives some notes on how Tor got that way.  It also includes a reference for
  13 nearly every function, type, file, and module in the Tor source code.  The
  14 high-level documentation is a work in progress.
  15
  16 Tor itself remains a work in progress too: We've been working on it for
  17 nearly two decades, and we've learned a lot about good coding since we first
  18 started.  This means, however, that some of the older pieces of Tor will have
  19 some "code smell" in them that could stand a brisk refactoring.  So when we
  20 describe a piece of code, we'll sometimes give a note on how it got that way,
  21 and whether we still think that's a good idea.
  22
  23 This document is not an overview of the Tor protocol.  For that, see the
  24 design paper and the specifications at https://spec.torproject.org/ .
  25
  26 For more information about Tor's coding standards and some helpful
  27 development tools, see
  28 [doc/HACKING](https://gitweb.torproject.org/tor.git/tree/doc/HACKING) in the
  29 Tor repository.
  30
  31 @section topics Topic-related documentation
  32
  33 @subpage intro
  34
  35 @subpage arch_goals
  36
  37 @subpage initialization
  38
  39 @subpage dataflow
  40
  41 @subpage certificates
  42
  43 @subpage threading
  44
  45 @subpage strings
  46
  47 @subpage time_periodic
  48
  49 @subpage configuration
  50
  51 @subpage publish_subscribe
  52
  53 @page intro A high-level overview
  54
  55 @tableofcontents
  56
  57 @section highlevel The very high level
  58
  59 Ultimately, Tor runs as an event-driven network daemon: it responds to
  60 network events, signals, and timers by sending and receiving things over
  61 the network.  Clients, relays, and directory authorities all use the
  62 same codebase: the Tor process will run as a client, relay, or authority
  63 depending on its configuration.
  64
  65 Tor has a few major dependencies, including Libevent (used to tell which
  66 sockets are readable and writable), OpenSSL or NSS (used for many encryption
  67 functions, and to implement the TLS protocol), and zlib (used to
  68 compress and uncompress directory information).
  69
  70 Most of Tor's work today is done in a single event-driven main thread.
  71 Tor also spawns one or more worker threads to handle CPU-intensive
  72 tasks.  (Right now, this only includes circuit encryption and the more
  73 expensive compression algorithms.)
  74
  75 On startup, Tor initializes its libraries, reads and responds to its
  76 configuration files, and launches a main event loop.  At first, the only
  77 events that Tor listens for are a few signals (like TERM and HUP), and
  78 one or more listener sockets (for different kinds of incoming
  79 connections).  Tor also configures several timers to handle periodic
  80 events.  As Tor runs over time, other events will open, and new events
  81 will be scheduled.
  82
  83 The codebase is divided into a few top-level subdirectories, each of
  84 which contains several sub-modules.
  85
  86    - \refdir{ext} -- Code maintained elsewhere that we include in the Tor
  87      source distribution.  You should not edit this code if you can
  88      avoid it: we try to keep it identical to the upstream versions.
  89
  90    - \refdir{lib} -- Lower-level utility code, not necessarily
  91      tor-specific.
  92
  93    - `trunnel` -- Automatically generated code (from the Trunnel
  94      tool): used to parse and encode binary formats.
  95
  96    - \refdir{core} -- Networking code that is implements the central
  97      parts of the Tor protocol and main loop.
  98
  99    - \refdir{feature} -- Aspects of Tor (like directory management,
 100      running a relay, running a directory authorities, managing a list of
 101      nodes, running and using onion services) that are built on top of the
 102      mainloop code.
 103
 104    - \refdir{app} -- Highest-level functionality; responsible for setting
 105      up and configuring the Tor daemon, making sure all the lower-level
 106      modules start up when required, and so on.
 107
 108    - \refdir{tools} -- Binaries other than Tor that we produce.
 109       Currently this is tor-resolve, tor-gencert, and the tor_runner.o helper
 110       module.
 111
 112    - `test` -- unit tests, regression tests, and a few integration
 113      tests.
 114
 115 In theory, the above parts of the codebase are sorted from highest-level to
 116 lowest-level, where high-level code is only allowed to invoke lower-level
 117 code, and lower-level code never includes or depends on code of a higher
 118 level.  In practice, this refactoring is incomplete: The modules in
 119 \refdir{lib} are well-factored, but there are many layer violations ("upward
 120 dependencies") in \refdir{core} and \refdir{feature}.
 121 We aim to eliminate those over time.
 122
 123 @section keyabstractions Some key high-level abstractions
 124
 125 The most important abstractions at Tor's high-level are Connections,
 126 Channels, Circuits, and Nodes.
 127
 128 A 'Connection' (connection_t) represents a stream-based information flow.
 129 Most connections are TCP connections to remote Tor servers and clients. (But
 130 as a shortcut, a relay will sometimes make a connection to itself without
 131 actually using a TCP connection.  More details later on.)  Connections exist
 132 in different varieties, depending on what functionality they provide.  The
 133 principle types of connection are edge_connection_t (eg a socks connection or
 134 a connection from an exit relay to a destination), or_connection_t (a TLS
 135 stream connecting to a relay), dir_connection_t (an HTTP connection to learn
 136 about the network), and control_connection_t (a connection from a
 137 controller).
 138
 139 A 'Circuit' (circuit_t) is persistent tunnel through the Tor network,
 140 established with public-key cryptography, and used to send cells one or more
 141 hops.  Clients keep track of multi-hop circuits (origin_circuit_t), and the
 142 cryptography associated with each hop.  Relays, on the other hand, keep track
 143 only of their hop of each circuit (or_circuit_t).
 144
 145 A 'Channel' (channel_t) is an abstract view of sending cells to and from a
 146 Tor relay.  Currently, all channels are implemented using OR connections
 147 (channel_tls_t).  If we switch to other strategies in the future, we'll have
 148 more connection types.
 149
 150 A 'Node' (node_t) is a view of a Tor instance's current knowledge and opinions
 151 about a Tor relay or bridge.