November 2019 - tor-commits - lists.torproject.org

[tor/master] Document --dump-config.
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit 6d9db29ddae9e4086e878ed049c5fc91304db761 Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 12 07:45:53 2019 -0500 Document --dump-config. Closes ticket 32467. --- changes/ticket32467 | 3 +++ doc/tor.1.txt | 7 +++++++ 2 files changed, 10 insertions(+) diff --git a/changes/ticket32467 b/changes/ticket32467 new file mode 100644 index 000000000..8cbb23812 --- /dev/null +++ b/changes/ticket32467 @@ -0,0 +1,3 @@ + o Documentation: + - Describe the --dump-config command in the manual page. Closes ticket + 32467. diff --git a/doc/tor.1.txt b/doc/tor.1.txt index a3c05961e..b2f6f59ca 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -96,6 +96,13 @@ The following options in this section are only recognized on the [[opt-verify-config]] **`--verify-config`**:: Verify whether the configuration file is valid. +[[opt-dump-config]] **`--dump-config`** **`short`**|**`full`**|**`non-builtin`**:: + Write a complete list of Tor's configured options to standard output. + When the `short` flag is selected, only write the options that + are different from their default values. When `non-builtin` is selected, + write options that are not zero or the empty string. + When `full` is selected, write every option. + [[opt-serviceinstall]] **`--service install`** [**`--options`** __command-line options__]:: Install an instance of Tor as a Windows service, with the provided command-line options. Current instructions can be found at

1 0

[tor/master] Merge branch 'ticket32467'
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit fc1316b559a387710201649395593680bcaa242f Merge: f221a7aaf 6d9db29dd Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 12 13:19:12 2019 -0500 Merge branch 'ticket32467' changes/ticket32467 | 3 +++ doc/tor.1.txt | 7 +++++++ 2 files changed, 10 insertions(+)

1 0

[tor/master] Fold remainder of this-not-that.md into CodingStandards.md
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit f221a7aaf6f05670f0d19f66c792d3b96f385f43 Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 12 12:28:14 2019 -0500 Fold remainder of this-not-that.md into CodingStandards.md --- doc/HACKING/CodingStandards.md | 30 +++++++++++++++++----- doc/HACKING/design/this-not-that.md | 51 ------------------------------------- 2 files changed, 24 insertions(+), 57 deletions(-) diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index 966a2b810..34d1dd52b 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -212,7 +212,8 @@ deviations from our C whitespace style. Generally, we use: - No space between a function name and an opening paren. `puts(x)`, not `puts (x)`. - Function declarations at the start of the line. - - Use `void foo(void)` to declare a function with no arguments. + - Use `void foo(void)` to declare a function with no arguments. Saying + `void foo()` is C++ syntax. - Use `const` for new APIs. If you use an editor that has plugins for editorconfig.org, the file @@ -230,22 +231,32 @@ We have some wrapper functions like `tor_malloc`, `tor_free`, `tor_strdup`, and `tor_gettimeofday;` use them instead of their generic equivalents. (They always succeed or exit.) +Specifically, Don't use `malloc`, `realloc`, `calloc`, `free`, or +`strdup`. Use `tor_malloc`, `tor_realloc`, `tor_calloc`, `tor_free`, or +`tor_strdup`. + +Don't use `tor_realloc(x, y\*z)`. Use `tor_reallocarray(x, y, z)` instead.; + You can get a full list of the compatibility functions that Tor provides by looking through `src/lib/*/*.h`. You can see the available containers in `src/lib/containers/*.h`. You should probably familiarize yourself with these modules before you write too much code, or else you'll wind up reinventing the wheel. -We don't use `strcat` or `strcpy` or `sprintf` of any of those notoriously broken -old C functions. Use `strlcat`, `strlcpy`, or `tor_snprintf/tor_asprintf` instead. + +We don't use `strcat` or `strcpy` or `sprintf` of any of those notoriously +broken old C functions. We also avoid `strncat` and `strncpy`. Use +`strlcat`, `strlcpy`, or `tor_snprintf/tor_asprintf` instead. We don't call `memcmp()` directly. Use `fast_memeq()`, `fast_memneq()`, -`tor_memeq()`, or `tor_memneq()` for most purposes. +`tor_memeq()`, or `tor_memneq()` for most purposes. If you really need a +tristate return value, use `tor_memcmp()` or `fast_memcmp()`. Don't call `assert()` directly. For hard asserts, use `tor_assert()`. For soft asserts, use `tor_assert_nonfatal()` or `BUG()`. If you need to print debug information in assert error message, consider using `tor_assertf()` and -`tor_assertf_nonfatal()`. +`tor_assertf_nonfatal()`. If you are writing code that is too low-level to +use the logging subsystem, use `raw_assert()`. Don't use `toupper()` and `tolower()` functions. Use `TOR_TOUPPER` and `TOR_TOLOWER` macros instead. Similarly, use `TOR_ISALPHA`, `TOR_ISALNUM` et. @@ -258,6 +269,12 @@ Avoid calling BSD socket functions directly. Use portable wrappers to work with sockets and socket addresses. Also, sockets should be of type `tor_socket_t`. +Don't use any of these functions: they aren't portable. Use the +version prefixed with `tor_` instead: strtok_r, memmem, memstr, +asprintf, localtime_r, gmtime_r, inet_aton, inet_ntop, inet_pton, +getpass, ntohll, htonll. (This list is incomplete.) + + What code can use what other code? ---------------------------------- @@ -350,7 +367,8 @@ Binary data and wire formats ---------------------------- Use pointer to `char` when representing NUL-terminated string. To represent -arbitrary binary data, use pointer to `uint8_t`. +arbitrary binary data, use pointer to `uint8_t`. (Many older Tor APIs ignore +this rule.) Refrain from attempting to encode integers by casting their pointers to byte arrays. Use something like `set_uint32()`/`get_uint32()` instead and don't diff --git a/doc/HACKING/design/this-not-that.md b/doc/HACKING/design/this-not-that.md deleted file mode 100644 index 815c7b2fb..000000000 --- a/doc/HACKING/design/this-not-that.md +++ /dev/null @@ -1,51 +0,0 @@ - -Don't use memcmp. Use {tor,fast}_{memeq,memneq,memcmp}. - -Don't use assert. Use tor_assert or tor_assert_nonfatal or BUG. Prefer -nonfatal assertions or BUG()s. - -Don't use sprintf or snprintf. Use tor_asprintf or tor_snprintf. - -Don't write hand-written binary parsers. Use trunnel. - -Don't use malloc, realloc, calloc, free, strdup, etc. Use tor_malloc, -tor_realloc, tor_calloc, tor_free, tor_strdup, etc. - -Don't use tor_realloc(x, y\*z). Use tor_reallocarray(x, y, z); - -Don't say "if (x) foo_free(x)". Just foo_free(x) and make sure that -foo_free(NULL) is a no-op. - -Don't use toupper or tolower; use TOR_TOUPPER and TOR_TOLOWER. - -Don't use isalpha, isalnum, etc. Instead use TOR_ISALPHA, TOR_ISALNUM, etc. - -Don't use strcat, strcpy, strncat, or strncpy. Use strlcat and strlcpy -instead. - -Don't use tor_asprintf then smartlist_add; use smartlist_add_asprintf. - -Don't use any of these functions: they aren't portable. Use the -version prefixed with `tor_` instead: strtok_r, memmem, memstr, -asprintf, localtime_r, gmtime_r, inet_aton, inet_ntop, inet_pton, -getpass, ntohll, htonll, strdup, (This list is incomplete.) - -Don't create or close sockets directly. Instead use the wrappers in -compat.h. - -When creating new APIs, only use 'char \*' to represent 'pointer to a -nul-terminated string'. Represent 'pointer to a chunk of memory' as -'uint8_t \*'. (Many older Tor APIs ignore this rule.) - -Don't encode/decode u32, u64, or u16 to byte arrays by casting -pointers. That can crash if the pointers aren't aligned, and can cause -endianness problems. Instead say something more like set_uint32(ptr, -htonl(foo)) to encode, and ntohl(get_uint32(ptr)) to decode. - -Don't declare a 0-argument function with "void foo()". That's C++ -syntax. In C you say "void foo(void)". - -When creating new APIs, use const everywhere you reasonably can. - -Sockets should have type tor_socket_t, not int. -

1 0

[tor/master] Merge advice from this_not_that.md in torguts repo into our main coding standard doc
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit b4aeeb77ba97436a220cfce2fa42b9717a6facea Author: rl1987 <rl1987(a)sdf.lonestar.org> Date: Wed Sep 25 17:15:12 2019 +0300 Merge advice from this_not_that.md in torguts repo into our main coding standard doc --- changes/doc31853 | 3 +++ doc/HACKING/CodingStandards.md | 33 +++++++++++++++++++++++++++++---- 2 files changed, 32 insertions(+), 4 deletions(-) diff --git a/changes/doc31853 b/changes/doc31853 new file mode 100644 index 000000000..9118a4f8b --- /dev/null +++ b/changes/doc31853 @@ -0,0 +1,3 @@ + o Documentation: + - Unite coding advice from this_not_that.md in torguts repo into our + coding standards document. Resolves ticket 31853. diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index 74db2a39a..966a2b810 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -212,6 +212,8 @@ deviations from our C whitespace style. Generally, we use: - No space between a function name and an opening paren. `puts(x)`, not `puts (x)`. - Function declarations at the start of the line. + - Use `void foo(void)` to declare a function with no arguments. + - Use `const` for new APIs. If you use an editor that has plugins for editorconfig.org, the file `.editorconfig` will help you to conform this coding style. @@ -240,8 +242,21 @@ old C functions. Use `strlcat`, `strlcpy`, or `tor_snprintf/tor_asprintf` inste We don't call `memcmp()` directly. Use `fast_memeq()`, `fast_memneq()`, `tor_memeq()`, or `tor_memneq()` for most purposes. -Also see a longer list of functions to avoid in: -https://people.torproject.org/~nickm/tor-auto/internal/this-not-that.html +Don't call `assert()` directly. For hard asserts, use `tor_assert()`. For +soft asserts, use `tor_assert_nonfatal()` or `BUG()`. If you need to print +debug information in assert error message, consider using `tor_assertf()` and +`tor_assertf_nonfatal()`. + +Don't use `toupper()` and `tolower()` functions. Use `TOR_TOUPPER` and +`TOR_TOLOWER` macros instead. Similarly, use `TOR_ISALPHA`, `TOR_ISALNUM` et. +al. instead of `isalpha()`, `isalnum()`, etc. + +When allocating new string to be added to a smartlist, use +`smartlist_add_asprintf()` to do both at once. + +Avoid calling BSD socket functions directly. Use portable wrappers to work +with sockets and socket addresses. Also, sockets should be of type +`tor_socket_t`. What code can use what other code? ---------------------------------- @@ -331,8 +346,15 @@ definitions when necessary.) Assignment operators shouldn't nest inside other expressions. (You can ignore this inside macro definitions when necessary.) -Functions not to write ----------------------- +Binary data and wire formats +---------------------------- + +Use pointer to `char` when representing NUL-terminated string. To represent +arbitrary binary data, use pointer to `uint8_t`. + +Refrain from attempting to encode integers by casting their pointers to byte +arrays. Use something like `set_uint32()`/`get_uint32()` instead and don't +forget about endianness. Try to never hand-write new code to parse or generate binary formats. Instead, use trunnel if at all possible. See @@ -451,6 +473,9 @@ to use it as a function callback), define it with a name like abc_free_(obj); } +When deallocating, don't say e.g. `if (x) tor_free(x)`. The convention is to +have deallocators do nothing when NULL pointer is passed. + Doxygen comment conventions ---------------------------

1 0

[tor/master] Merge remote-tracking branch 'tor-github/pr/1367'
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit c11c1d06234151c79a77ef6fdd2f34679cf6d64e Merge: e39423c78 b4aeeb77b Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 12 12:18:14 2019 -0500 Merge remote-tracking branch 'tor-github/pr/1367' changes/doc31853 | 3 +++ doc/HACKING/CodingStandards.md | 33 +++++++++++++++++++++++++++++---- 2 files changed, 32 insertions(+), 4 deletions(-)

1 0

[tor/master] HACKING/design: move 01c-time.md into doxygen.
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit 6744f6b6bba2af2d3d3712825a28e75b0304d7b8 Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 12 12:14:14 2019 -0500 HACKING/design: move 01c-time.md into doxygen. --- .../lib/evloop/time_periodic.dox | 29 ++++++++++++---------- src/mainpage.dox | 2 ++ 2 files changed, 18 insertions(+), 13 deletions(-) diff --git a/doc/HACKING/design/01c-time.md b/src/lib/evloop/time_periodic.dox similarity index 75% rename from doc/HACKING/design/01c-time.md rename to src/lib/evloop/time_periodic.dox index 5cd0b354f..b12ae63bd 100644 --- a/doc/HACKING/design/01c-time.md +++ b/src/lib/evloop/time_periodic.dox @@ -1,5 +1,6 @@ +/** -## Time in tor ## +@page time_periodic Time and periodic events in Tor ### What time is it? ### @@ -33,28 +34,28 @@ tor_gettimeofday_cached(). Tor has functions to parse and format time in these formats: - * RFC1123 format. ("Fri, 29 Sep 2006 15:54:20 GMT"). For this, - use format_rfc1123_time() and parse_rfc1123_time. + - RFC1123 format. ("Fri, 29 Sep 2006 15:54:20 GMT"). For this, + use format_rfc1123_time() and parse_rfc1123_time. - * ISO8601 format. ("2006-10-29 10:57:20") For this, use - format_local_iso_time and format_iso_time. We also support the - variant format "2006-10-29T10:57:20" with format_iso_time_nospace, and - "2006-10-29T10:57:20.123456" with format_iso_time_nospace_usec. + - ISO8601 format. ("2006-10-29 10:57:20") For this, use + format_local_iso_time() and format_iso_time(). We also support the + variant format "2006-10-29T10:57:20" with format_iso_time_nospace(), and + "2006-10-29T10:57:20.123456" with format_iso_time_nospace_usec(). - * HTTP format collections (preferably "Mon, 25 Jul 2016 04:01:11 - GMT" or possibly "Wed Jun 30 21:49:08 1993" or even "25-Jul-16 - 04:01:11 GMT"). For this, use parse_http_time. Don't generate anything - but the first format. + - HTTP format collections (preferably "Mon, 25 Jul 2016 04:01:11 + GMT" or possibly "Wed Jun 30 21:49:08 1993" or even "25-Jul-16 + 04:01:11 GMT"). For this, use parse_http_time(). Don't generate anything + but the first format. Some of these functions use struct tm. You can use the standard -tor_localtime_r and tor_gmtime_r() to wrap these in a safe way. We +tor_localtime_r() and tor_gmtime_r() to wrap these in a safe way. We also have a tor_timegm() function. ### Scheduling events ### The main way to schedule a not-too-frequent periodic event with respect to the Tor mainloop is via the mechanism in periodic.c. -There's a big table of periodic_events in main.c, each of which gets +There's a big table of periodic_events in mainloop.c, each of which gets invoked on its own schedule. You should not expect more than about one second of accuracy with these timers. @@ -73,3 +74,5 @@ accurate within a handful of milliseconds -- possibly better on some platforms. (The timers.c module uses William Ahern's timeout.c implementation as its backend, which is based on a hierarchical timing wheel algorithm. It's cool stuff; check it out.) + +**/ diff --git a/src/mainpage.dox b/src/mainpage.dox index 4f565cf6e..1da074951 100644 --- a/src/mainpage.dox +++ b/src/mainpage.dox @@ -38,6 +38,8 @@ Tor repository. @subpage strings +@subpage time_periodic + **/ /**

1 0

[tor/master] Remove 01e-os-compat: the module docs cover this much better.
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit e39423c78c6c66e08ed65a162e2a6d1a21606881 Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 12 12:14:56 2019 -0500 Remove 01e-os-compat: the module docs cover this much better. --- doc/HACKING/design/01e-os-compat.md | 50 ------------------------------------- 1 file changed, 50 deletions(-) diff --git a/doc/HACKING/design/01e-os-compat.md b/doc/HACKING/design/01e-os-compat.md deleted file mode 100644 index 072e95bc8..000000000 --- a/doc/HACKING/design/01e-os-compat.md +++ /dev/null @@ -1,50 +0,0 @@ - -## OS compatibility functions ## - -We've got a bunch of functions to wrap differences between various -operating systems where we run. - -### The filesystem ### - -We wrap the most important filesystem functions with load-file, -save-file, and map-file abstractions declared in util.c or compat.c. If -you're messing about with file descriptors yourself, you might be doing -things wrong. Most of the time, write_str_to_file() and -read_str_from_file() are all you need. - -Use the check_private_directory() function to create or verify the -presence of directories, and tor_listdir() to list the files in a -directory. - -Those modules also have functions for manipulating paths a bit. - -### Networking ### - -Nearly all the world is on a Berkeley sockets API, except for -windows, whose version of the Berkeley API was corrupted by late-90s -insistence on backward compatibility with the -sort-of-berkeley-sort-of-not add-on *thing* that was WinSocks. - -What's more, everybody who implemented sockets realized that select() -wasn't a very good way to do nonblocking IO... and then the various -implementations all decided to so something different. - -You can forget about most of these differences, fortunately: We use -libevent to hide most of the differences between the various networking -backends, and we add a few of our own functions to hide the differences -that Libevent doesn't. - -To create a network connection, the right level of abstraction to look -at is probably the connection_t system in connection.c. Most of the -lower level work has already been done for you. If you need to -instantiate something that doesn't fit well with connection_t, you -should see whether you can instantiate it with connection_t anyway -- or -you might need to refactor connection.c a little. - -Whenever possible, represent network addresses as tor_addr_t. - -### Process launch and monitoring ### - -Launching and/or monitoring a process is tricky business. You can use -the mechanisms in procmon.c and tor_spawn_background(), but they're both -a bit wonky. A refactoring would not be out of order.

1 0

[tor/master] HACKING/design: turn the remaining parts of crypto into a certs doc
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit 91f377deec9d2d65f8bebe1ac7ea01974b90d376 Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 12 12:01:33 2019 -0500 HACKING/design: turn the remaining parts of crypto into a certs doc --- .../design/01d-crypto.md => src/lib/crypt_ops/certs.dox | 11 ++++++++--- src/mainpage.dox | 2 ++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/doc/HACKING/design/01d-crypto.md b/src/lib/crypt_ops/certs.dox similarity index 84% rename from doc/HACKING/design/01d-crypto.md rename to src/lib/crypt_ops/certs.dox index 3e23a0701..4703f07bc 100644 --- a/doc/HACKING/design/01d-crypto.md +++ b/src/lib/crypt_ops/certs.dox @@ -1,6 +1,6 @@ +/** - -### Certificates ### +@page certificates Certificates in Tor. We have, alas, several certificate types in Tor. @@ -9,6 +9,8 @@ won't explain X.509 to you -- possibly, no document can. (OTOH, Peter Gutmann's "x.509 style guide", though severely dated, does a good job of explaining how awful x.509 can be.) Do not introduce any new usages of X.509. Right now we only use it in places where TLS forces us to do so. +See x509.c for more information about using this type. + The authority_cert_t type is used only for directory authority keys. It has a medium-term signing key (which the authorities actually keep @@ -19,9 +21,12 @@ certificate. For new places where you need a certificate, consider tor_cert_t: it represents a typed and dated _something_ signed by an Ed25519 key. The format is described in tor-spec. Unlike x.509, you can write it on a -napkin. +napkin. The torcert.c file is used for manipulating these certificates and +their associated keys. (Additionally, the Tor directory design uses a fairly wide variety of documents that include keys and which are signed by keys. You can consider these documents to be an additional kind of certificate if you want.) + +**/ diff --git a/src/mainpage.dox b/src/mainpage.dox index eb29eb5fa..a5988aecf 100644 --- a/src/mainpage.dox +++ b/src/mainpage.dox @@ -31,6 +31,8 @@ Tor repository. @subpage intro @subpage dataflow + +@subpage certificates **/ /**

1 0

[tor/master] HACKING/design: remove 03-modules as superseded.
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit 89396bc72636903d380543c3effe24c7709d750e Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 12 11:56:53 2019 -0500 HACKING/design: remove 03-modules as superseded. The src/feature directory documentation now covers this better. --- doc/HACKING/design/03-modules.md | 158 --------------------------------------- 1 file changed, 158 deletions(-) diff --git a/doc/HACKING/design/03-modules.md b/doc/HACKING/design/03-modules.md deleted file mode 100644 index 9ab2fa7da..000000000 --- a/doc/HACKING/design/03-modules.md +++ /dev/null @@ -1,158 +0,0 @@ - -## Tor's modules ## - -### Node-status modules ### - -`directory.c` -: Implements the HTTP-based directory protocol, including sending, -receiving, and handling most request types. (*Note*: The client parts -of this, and the generic-HTTP parts of this, could plausibly be split -off.) - -`microdesc.c` -: Implements the compact "microdescriptor" format for keeping track of -what we know about a router. - -`networkstatus.c` -: Code for fetching, storing, and interpreting consensus vote documents. - -`nodelist.c` -: Higher-level view of our knowledge of which Tor servers exist. Each -`node_t` corresponds to a router we know about. - -`routerlist.c` -: Code for storing and retrieving router descriptors and extrainfo -documents. - -`routerparse.c` -: Generic and specific code for parsing all Tor directory information -types. - -`routerset.c` -: Parses and interprets a specification for a set of routers (by IP -range, fingerprint, nickname (deprecated), or country). - - -### Client modules ### - -`addressmap.c` -: Handles client-side associations between one address and another. -These are used to implement client-side DNS caching (NOT RECOMMENDED), -MapAddress directives, Automapping, and more. - -`circpathbias.c` -: Path bias attack detection for circuits: tracks whether -connections made through a particular guard have an unusually high failure rate. - -`circuitstats.c` -: Code to track circuit performance statistics in order to adapt our behavior. -Notably includes an algorithm to track circuit build times. - -`dnsserv.c` -: Implements DNSPort for clients. (Note that in spite of the word -"server" in this module's name, it is used for Tor clients. It -implements a DNS server, not DNS for servers.) - -`entrynodes.c` -: Chooses, monitors, and remembers guard nodes. Also contains some -bridge-related code. - -`torcert.c` -: Code to interpret and generate Ed25519-based certificates. - -### Server modules ### - -`dns.c` -: Server-side DNS code. Handles sending and receiving DNS requests on -exit nodes, and implements the server-side DNS cache. - -`dirserv.c` -: Implements part of directory caches that handles responding to -client requests. - -`ext_orport.c` -: Implements the extended ORPort protocol for communication between -server-side pluggable transports and Tor servers. - -`hibernate.c` -: Performs bandwidth accounting, and puts Tor relays into hibernation -when their bandwidth is exhausted. - -`router.c` -: Management code for running a Tor server. In charge of RSA key -maintenance, descriptor generation and uploading. - -`routerkeys.c` -: Key handling code for a Tor server. (Currently handles only the -Ed25519 keys, but the RSA keys could be moved here too.) - - -### Onion service modules ### - -`rendcache.c` -: Stores onion service descriptors. - -`rendclient.c` -: Client-side implementation of the onion service protocol. - -`rendcommon.c` -: Parts of the onion service protocol that are shared by clients, -services, and/or Tor servers. - -`rendmid.c` -: Tor-server-side implementation of the onion service protocol. (Handles -acting as an introduction point or a rendezvous point.) - -`rendservice.c` -: Service-side implementation of the onion service protocol. - -`replaycache.c` -: Backend to check introduce2 requests for replay attempts. - - -### Authority modules ### - -`dircollate.c` -: Helper for `dirvote.c`: Given a set of votes, each containing a list -of Tor nodes, determines which entries across all the votes correspond -to the same nodes, and yields them in a useful order. - -`dirvote.c` -: Implements the directory voting algorithms that authorities use. - -`keypin.c` -: Implements a persistent key-pinning mechanism to tie RSA1024 -identities to ed25519 identities. - -### Miscellaneous modules ### - -`control.c` -: Implements the Tor controller protocol. - -`cpuworker.c` -: Implements the inner work queue function. We use this to move the -work of circuit creation (on server-side) to other CPUs. - -`fp_pair.c` -: Types for handling 2-tuples of 20-byte fingerprints. - -`geoip.c` -: Parses geoip files (which map IP addresses to country codes), and -performs lookups on the internal geoip table. Also stores some -geoip-related statistics. - -`policies.c` -: Parses and implements Tor exit policies. - -`reasons.c` -: Maps internal reason-codes to human-readable strings. - -`rephist.c` -: Tracks Tor servers' performance over time. - -`status.c` -: Writes periodic "heartbeat" status messages about the state of the Tor -process. - -`transports.c` -: Implements management for the pluggable transports subsystem.

1 0

[tor/master] 01f-threads.md becomes threading.dox.
by nickm＠torproject.org 12 Nov '19

12 Nov '19

commit d1a1631a05521279041a9ed41383d886e5580250 Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 12 12:05:05 2019 -0500 01f-threads.md becomes threading.dox. --- .../01f-threads.md => src/lib/thread/threading.dox | 22 ++++++++++++---------- src/mainpage.dox | 3 +++ 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/doc/HACKING/design/01f-threads.md b/src/lib/thread/threading.dox similarity index 56% rename from doc/HACKING/design/01f-threads.md rename to src/lib/thread/threading.dox index a0dfa2d40..e15d58440 100644 --- a/doc/HACKING/design/01f-threads.md +++ b/src/lib/thread/threading.dox @@ -1,26 +1,28 @@ +/** -## Threads in Tor ## +@page threading Threading in Tor Tor is based around a single main thread and one or more worker threads. We aim (with middling success) to use worker threads for CPU-intensive activities and the main thread for our networking. -Fortunately (?) we have enough cryptography that moving what we can of the -cryptographic processes to the workers should achieve good parallelism under most -loads. Unfortunately, we only have a small fraction of our -cryptography done in our worker threads right now. +Fortunately (?) we have enough cryptography that moving what we can +of the cryptographic processes to the workers should achieve good +parallelism under most loads. Unfortunately, we only have a small +fraction of our cryptography done in our worker threads right now. Our threads-and-workers abstraction is defined in workqueue.c, which combines a work queue with a thread pool, and integrates the -signalling with libevent. Tor main instance of a work queue is +signalling with libevent. Tor's main instance of a work queue is instantiated in cpuworker.c. It will probably need some refactoring as more types of work are added. -On a lower level, we provide locks with tor_mutex_t, conditions with -tor_cond_t, and thread-local storage with tor_threadlocal_t, all of -which are specified in compat_threads.h and implemented in an OS- -specific compat_\*threads.h module. +On a lower level, we provide locks with tor_mutex_t in \refdir{lib/lock}, and +higher-level locking/threading tools in \refdir{lib/thread}, including +conditions (tor_cond_t), thread-local storage (tor_threadlocal_t), and more. + Try to minimize sharing between threads: it is usually best to simply make the worker "own" all the data it needs while the work is in progress, and to give up ownership when it's complete. +**/ diff --git a/src/mainpage.dox b/src/mainpage.dox index a5988aecf..a568d52fc 100644 --- a/src/mainpage.dox +++ b/src/mainpage.dox @@ -33,6 +33,9 @@ Tor repository. @subpage dataflow @subpage certificates + +@subpage threading + **/ /**

1 0