commit e1cdca2e4f58c108539fe4c36205b16caca8d44f Author: Nick Mathewson nickm@torproject.org Date: Mon Nov 4 16:28:28 2019 -0500
directory-level doxygen for "src/core" --- doc/HACKING/design/03-modules.md | 89 ------------------------------------- src/core/core.dox | 12 +++++ src/core/crypto/core_crypto.dox | 6 ++- src/core/mainloop/core_mainloop.dox | 10 ++++- src/core/or/core_or.dox | 62 +++++++++++++++++++++++++- src/core/proto/core_proto.dox | 6 ++- 6 files changed, 91 insertions(+), 94 deletions(-)
diff --git a/doc/HACKING/design/03-modules.md b/doc/HACKING/design/03-modules.md index 93eb9d308..9ab2fa7da 100644 --- a/doc/HACKING/design/03-modules.md +++ b/doc/HACKING/design/03-modules.md @@ -1,95 +1,6 @@
## Tor's modules ##
-### Generic modules ### - -`buffers.c` -: Implements the `buf_t` buffered data type for connections, and several -low-level data handling functions to handle network protocols on it. - -`channel.c` -: Generic channel implementation. Channels handle sending and receiving cells -among tor nodes. - -`channeltls.c` -: Channel implementation for TLS-based OR connections. Uses `connection_or.c`. - -`circuitbuild.c` -: Code for constructing circuits and choosing their paths. (*Note*: -this module could plausibly be split into handling the client side, -the server side, and the path generation aspects of circuit building.) - -`circuitlist.c` -: Code for maintaining and navigating the global list of circuits. - -`circuitmux.c` -: Generic circuitmux implementation. A circuitmux handles deciding, for a -particular channel, which circuit should write next. - -`circuitmux_ewma.c` -: A circuitmux implementation based on the EWMA (exponentially -weighted moving average) algorithm. - -`circuituse.c` -: Code to actually send and receive data on circuits. - -`command.c` -: Handles incoming cells on channels. - -`config.c` -: Parses options from torrc, and uses them to configure the rest of Tor. - -`confparse.c` -: Generic torrc-style parser. Used to parse torrc and state files. - -`connection.c` -: Generic and common connection tools, and implementation for the simpler -connection types. - -`connection_edge.c` -: Implementation for entry and exit connections. - -`connection_or.c` -: Implementation for OR connections (the ones that send cells over TLS). - -`main.c` -: Principal entry point, main loops, scheduled events, and network -management for Tor. - -`ntmain.c` -: Implements Tor as a Windows service. (Not very well.) - -`onion.c` -: Generic code for generating and responding to CREATE and CREATED -cells, and performing the appropriate onion handshakes. Also contains -code to manage the server-side onion queue. - -`onion_fast.c` -: Implements the old SHA1-based CREATE_FAST/CREATED_FAST circuit -creation handshake. (Now deprecated.) - -`onion_ntor.c` -: Implements the Curve25519-based NTOR circuit creation handshake. - -`onion_tap.c` -: Implements the old RSA1024/DH1024-based TAP circuit creation handshake. (Now -deprecated.) - -`relay.c` -: Handles particular types of relay cells, and provides code to receive, -encrypt, route, and interpret relay cells. - -`scheduler.c` -: Decides which channel/circuit pair is ready to receive the next cell. - -`statefile.c` -: Handles loading and storing Tor's state file. - -`tor_main.c` -: Contains the actual `main()` function. (This is placed in a separate -file so that the unit tests can have their own `main()`.) - - ### Node-status modules ###
`directory.c` diff --git a/src/core/core.dox b/src/core/core.dox index b37c5e2d8..11bf55cb7 100644 --- a/src/core/core.dox +++ b/src/core/core.dox @@ -5,4 +5,16 @@ The "core" directory has the central protocols for Tor, which every client and relay must implement in order to perform onion routing.
+It is divided into three lower-level pieces: + + - \refdir{core/crypto} -- Tor-specific cryptography. + + - \refdir{core/proto} -- Protocol encoding/decoding. + + - \refdir{core/mainloop} -- A connection-oriented asynchronous mainloop. + +and one high-level piece: + + - \refdir{core/or} -- Implements onion routing itself. + **/ diff --git a/src/core/crypto/core_crypto.dox b/src/core/crypto/core_crypto.dox index 36c12371d..28ece92bb 100644 --- a/src/core/crypto/core_crypto.dox +++ b/src/core/crypto/core_crypto.dox @@ -1,4 +1,8 @@ /** @dir /core/crypto -@brief core/crypto +@brief core/crypto: Tor-specific cryptography + +This module implements Tor's circuit-construction crypto and Tor's +relay crypto. + **/ diff --git a/src/core/mainloop/core_mainloop.dox b/src/core/mainloop/core_mainloop.dox index e97edde94..28cd42bf6 100644 --- a/src/core/mainloop/core_mainloop.dox +++ b/src/core/mainloop/core_mainloop.dox @@ -1,4 +1,12 @@ /** @dir /core/mainloop -@brief core/mainloop +@brief core/mainloop: Non-onion-routing mainloop functionality + +This module uses the event-loop code of \refdir{lib/evloop} to implement an +asynchronous connection-oriented protocol handler. + +The layering here is imperfect: the code here was split from \refdir{core/or} +without refactoring how the two modules call one another. Probably many +functions should be moved and refactored. + **/ diff --git a/src/core/or/core_or.dox b/src/core/or/core_or.dox index 754690e00..705e9b543 100644 --- a/src/core/or/core_or.dox +++ b/src/core/or/core_or.dox @@ -1,4 +1,62 @@ /** @dir /core/or -@brief core/or -**/ +@brief core/or: *Onion routing happens here*. + +This is the central part of Tor that handles the core tasks of onion routing: +building circuit, handling circuits, attaching circuit to streams, moving +data around, and so forth. + +Some aspects of this module should probably be refactored into others. + +Notable files here include: + +`channel.c` +: Generic channel implementation. Channels handle sending and receiving cells +among tor nodes. + +`channeltls.c` +: Channel implementation for TLS-based OR connections. Uses `connection_or.c`. + +`circuitbuild.c` +: Code for constructing circuits and choosing their paths. (*Note*: +this module could plausibly be split into handling the client side, +the server side, and the path generation aspects of circuit building.) + +`circuitlist.c` +: Code for maintaining and navigating the global list of circuits. + +`circuitmux.c` +: Generic circuitmux implementation. A circuitmux handles deciding, for a +particular channel, which circuit should write next. + +`circuitmux_ewma.c` +: A circuitmux implementation based on the EWMA (exponentially +weighted moving average) algorithm. + +`circuituse.c` +: Code to actually send and receive data on circuits. + +`command.c` +: Handles incoming cells on channels. + +`connection.c` +: Generic and common connection tools, and implementation for the simpler +connection types. + +`connection_edge.c` +: Implementation for entry and exit connections. + +`connection_or.c` +: Implementation for OR connections (the ones that send cells over TLS). + +`onion.c` +: Generic code for generating and responding to CREATE and CREATED +cells, and performing the appropriate onion handshakes. Also contains +code to manage the server-side onion queue. + +`relay.c` +: Handles particular types of relay cells, and provides code to receive, +encrypt, route, and interpret relay cells. + +`scheduler.c` +: Decides which channel/circuit pair is ready to receive the next cell. diff --git a/src/core/proto/core_proto.dox b/src/core/proto/core_proto.dox index 2e92a6513..13ce751a7 100644 --- a/src/core/proto/core_proto.dox +++ b/src/core/proto/core_proto.dox @@ -1,4 +1,8 @@ /** @dir /core/proto -@brief core/proto +@brief core/proto: Protocol encoding/decoding + +These functions should (but do not always) exist at a lower level than most +of the rest of core. + **/