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

[tor/master] Move much of 00-overview.md into doxygen.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit 607b1ff776b5a5e5c9ba0197b5768751e5b9c68c Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 12:22:58 2019 -0500 Move much of 00-overview.md into doxygen. --- doc/HACKING/design/00-overview.md | 118 ------------------------------------- src/mainpage.dox | 119 ++++++++++++++++++++++++++++++++++++-- 2 files changed, 115 insertions(+), 122 deletions(-) diff --git a/doc/HACKING/design/00-overview.md b/doc/HACKING/design/00-overview.md index ff40a566b..1c14dc8c1 100644 --- a/doc/HACKING/design/00-overview.md +++ b/doc/HACKING/design/00-overview.md @@ -1,124 +1,6 @@ ## Overview ## -This document describes the general structure of the Tor codebase, how -it fits together, what functionality is available for extending Tor, -and gives some notes on how Tor got that way. - -Tor remains a work in progress: We've been working on it for nearly two -decades, and we've learned a lot about good coding since we first -started. This means, however, that some of the older pieces of Tor will -have some "code smell" in them that could stand a brisk -refactoring. So when I describe a piece of code, I'll sometimes give a -note on how it got that way, and whether I still think that's a good -idea. - -The first drafts of this document were written in the Summer and Fall of -2015, when Tor 0.2.6 was the most recent stable version, and Tor 0.2.7 -was under development. There is a revision in progress (as of late -2019), to bring it up to pace with Tor as of version 0.4.2. If you're -reading this far in the future, some things may have changed. Caveat -haxxor! - -This document is not an overview of the Tor protocol. For that, see the -design paper and the specifications at https://spec.torproject.org/ . - -For more information about Tor's coding standards and some helpful -development tools, see doc/HACKING in the Tor repository. - - -### The very high level ### - -Ultimately, Tor runs as an event-driven network daemon: it responds to -network events, signals, and timers by sending and receiving things over -the network. Clients, relays, and directory authorities all use the -same codebase: the Tor process will run as a client, relay, or authority -depending on its configuration. - -Tor has a few major dependencies, including Libevent (used to tell which -sockets are readable and writable), OpenSSL or NSS (used for many encryption -functions, and to implement the TLS protocol), and zlib (used to -compress and uncompress directory information). - -Most of Tor's work today is done in a single event-driven main thread. -Tor also spawns one or more worker threads to handle CPU-intensive -tasks. (Right now, this only includes circuit encryption and the more -expensive compression algorithms.) - -On startup, Tor initializes its libraries, reads and responds to its -configuration files, and launches a main event loop. At first, the only -events that Tor listens for are a few signals (like TERM and HUP), and -one or more listener sockets (for different kinds of incoming -connections). Tor also configures several timers to handle periodic -events. As Tor runs over time, other events will open, and new events -will be scheduled. - -The codebase is divided into a few top-level subdirectories, each of -which contains several sub-modules. - - * `src/ext` -- Code maintained elsewhere that we include in the Tor - source distribution. - - * src/lib` -- Lower-level utility code, not necessarily tor-specific. - - * `src/trunnel` -- Automatically generated code (from the Trunnel - tool): used to parse and encode binary formats. - - * `src/core` -- Networking code that is implements the central parts of - the Tor protocol and main loop. - - * `src/feature` -- Aspects of Tor (like directory management, running a - relay, running a directory authorities, managing a list of nodes, - running and using onion services) that are built on top of the - mainloop code. - - * `src/app` -- Highest-level functionality; responsible for setting up - and configuring the Tor daemon, making sure all the lower-level - modules start up when required, and so on. - - * `src/tools` -- Binaries other than Tor that we produce. Currently this - is tor-resolve, tor-gencert, and the tor_runner.o helper module. - - * `src/test` -- unit tests, regression tests, and a few integration - tests. - -In theory, the above parts of the codebase are sorted from highest-level to -lowest-level, where high-level code is only allowed to invoke lower-level -code, and lower-level code never includes or depends on code of a higher -level. In practice, this refactoring is incomplete: The modules in `src/lib` -are well-factored, but there are many layer violations ("upward -dependencies") in `src/core` and `src/feature`. We aim to eliminate those -over time. - -### Some key high-level abstractions ### - -The most important abstractions at Tor's high-level are Connections, -Channels, Circuits, and Nodes. - -A 'Connection' represents a stream-based information flow. Most -connections are TCP connections to remote Tor servers and clients. (But -as a shortcut, a relay will sometimes make a connection to itself -without actually using a TCP connection. More details later on.) -Connections exist in different varieties, depending on what -functionality they provide. The principle types of connection are -"edge" (eg a socks connection or a connection from an exit relay to a -destination), "OR" (a TLS stream connecting to a relay), "Directory" (an -HTTP connection to learn about the network), and "Control" (a connection -from a controller). - -A 'Circuit' is persistent tunnel through the Tor network, established -with public-key cryptography, and used to send cells one or more hops. -Clients keep track of multi-hop circuits, and the cryptography -associated with each hop. Relays, on the other hand, keep track only of -their hop of each circuit. - -A 'Channel' is an abstract view of sending cells to and from a Tor -relay. Currently, all channels are implemented using OR connections. -If we switch to other strategies in the future, we'll have more -connection types. - -A 'Node' is a view of a Tor instance's current knowledge and opinions -about a Tor relay or bridge. ### The rest of this document. ### diff --git a/src/mainpage.dox b/src/mainpage.dox index 84eea3c52..7c64e0dff 100644 --- a/src/mainpage.dox +++ b/src/mainpage.dox @@ -3,9 +3,120 @@ @section intro Getting to know Tor -Welcome to the Tor source code documentation! Here we have documentation for -nearly every function, type, and module in the Tor source code. The high-level -documentation is a work in progress. For now, have a look at the source code -overview in doc/HACKING/design. +Welcome! + +This documentation describes the general structure of the Tor codebase, how +it fits together, what functionality is available for extending Tor, and +gives some notes on how Tor got that way. It also includes a reference for +nearly every function, type, file, and module in the Tor source code. The +high-level documentation is a work in progress. + +Tor itself remains a work in progress too: We've been working on it for +nearly two decades, and we've learned a lot about good coding since we first +started. This means, however, that some of the older pieces of Tor will have +some "code smell" in them that could stand a brisk refactoring. So when we +describe a piece of code, we'll sometimes give a note on how it got that way, +and whether we still think that's a good idea. + +This document is not an overview of the Tor protocol. For that, see the +design paper and the specifications at https://spec.torproject.org/ . + +For more information about Tor's coding standards and some helpful +development tools, see doc/HACKING in the Tor repository. + +@section highlevel The very high level + +Ultimately, Tor runs as an event-driven network daemon: it responds to +network events, signals, and timers by sending and receiving things over +the network. Clients, relays, and directory authorities all use the +same codebase: the Tor process will run as a client, relay, or authority +depending on its configuration. + +Tor has a few major dependencies, including Libevent (used to tell which +sockets are readable and writable), OpenSSL or NSS (used for many encryption +functions, and to implement the TLS protocol), and zlib (used to +compress and uncompress directory information). + +Most of Tor's work today is done in a single event-driven main thread. +Tor also spawns one or more worker threads to handle CPU-intensive +tasks. (Right now, this only includes circuit encryption and the more +expensive compression algorithms.) + +On startup, Tor initializes its libraries, reads and responds to its +configuration files, and launches a main event loop. At first, the only +events that Tor listens for are a few signals (like TERM and HUP), and +one or more listener sockets (for different kinds of incoming +connections). Tor also configures several timers to handle periodic +events. As Tor runs over time, other events will open, and new events +will be scheduled. + +The codebase is divided into a few top-level subdirectories, each of +which contains several sub-modules. + + - `ext` -- Code maintained elsewhere that we include in the Tor + source distribution. + + - \refdir{lib} -- Lower-level utility code, not necessarily + tor-specific. + + - `trunnel` -- Automatically generated code (from the Trunnel + tool): used to parse and encode binary formats. + + - \refdir{core} -- Networking code that is implements the central + parts of the Tor protocol and main loop. + + - \refdir{feature} -- Aspects of Tor (like directory management, + running a relay, running a directory authorities, managing a list of + nodes, running and using onion services) that are built on top of the + mainloop code. + + - \refdir{app} -- Highest-level functionality; responsible for setting + up and configuring the Tor daemon, making sure all the lower-level + modules start up when required, and so on. + + - \refdir{tools} -- Binaries other than Tor that we produce. + Currently this is tor-resolve, tor-gencert, and the tor_runner.o helper + module. + + - `test` -- unit tests, regression tests, and a few integration + tests. + +In theory, the above parts of the codebase are sorted from highest-level to +lowest-level, where high-level code is only allowed to invoke lower-level +code, and lower-level code never includes or depends on code of a higher +level. In practice, this refactoring is incomplete: The modules in +\refdir{lib} are well-factored, but there are many layer violations ("upward +dependencies") in \refdir{core} and \refdir{feature}. +We aim to eliminate those over time. + +@section keyabstractions Some key high-level abstractions + +The most important abstractions at Tor's high-level are Connections, +Channels, Circuits, and Nodes. + +A 'Connection' (connection_t) represents a stream-based information flow. +Most connections are TCP connections to remote Tor servers and clients. (But +as a shortcut, a relay will sometimes make a connection to itself without +actually using a TCP connection. More details later on.) Connections exist +in different varieties, depending on what functionality they provide. The +principle types of connection are edge_connection_t (eg a socks connection or +a connection from an exit relay to a destination), or_connection_t (a TLS +stream connecting to a relay), dir_connection_t (an HTTP connection to learn +about the network), and control_connection_t (a connection from a +controller). + +A 'Circuit' (circuit_t) is persistent tunnel through the Tor network, +established with public-key cryptography, and used to send cells one or more +hops. Clients keep track of multi-hop circuits (origin_circuit_t), and the +cryptography associated with each hop. Relays, on the other hand, keep track +only of their hop of each circuit (or_circuit_t). + +A 'Channel' (channel_t) is an abstract view of sending cells to and from a +Tor relay. Currently, all channels are implemented using OR connections +(channel_tls_t). If we switch to other strategies in the future, we'll have +more connection types. + +A 'Node' (node_t) is a view of a Tor instance's current knowledge and opinions +about a Tor relay or bridge. **/

1 0

[tor/master] Move most of crypto overview into doxygen.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit a5085c52d0902c35ae889c68e99d5f2a1422dd30 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 12:09:45 2019 -0500 Move most of crypto overview into doxygen. --- doc/HACKING/design/01d-crypto.md | 142 ------------------------------------ src/lib/crypt_ops/lib_crypt_ops.dox | 127 ++++++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+), 142 deletions(-) diff --git a/doc/HACKING/design/01d-crypto.md b/doc/HACKING/design/01d-crypto.md index d4def947d..3e23a0701 100644 --- a/doc/HACKING/design/01d-crypto.md +++ b/doc/HACKING/design/01d-crypto.md @@ -1,132 +1,4 @@ -## Lower-level cryptography functionality in Tor ## - -Generally speaking, Tor code shouldn't be calling OpenSSL (or any -other crypto library) directly. Instead, we should indirect through -one of the functions in src/common/crypto\*.c or src/common/tortls.c. - -Cryptography functionality that's available is described below. - -### RNG facilities ### - -The most basic RNG capability in Tor is the crypto_rand() family of -functions. These currently use OpenSSL's RAND_() backend, but may use -something faster in the future. - -In addition to crypto_rand(), which fills in a buffer with random -bytes, we also have functions to produce random integers in certain -ranges; to produce random hostnames; to produce random doubles, etc. - -When you're creating a long-term cryptographic secret, you might want -to use crypto_strongest_rand() instead of crypto_rand(). It takes the -operating system's entropy source and combines it with output from -crypto_rand(). This is a pure paranoia measure, but it might help us -someday. - -You can use smartlist_choose() to pick a random element from a smartlist -and smartlist_shuffle() to randomize the order of a smartlist. Both are -potentially a bit slow. - -### Cryptographic digests and related functions ### - -We treat digests as separate types based on the length of their -outputs. We support one 160-bit digest (SHA1), two 256-bit digests -(SHA256 and SHA3-256), and two 512-bit digests (SHA512 and SHA3-512). - -You should not use SHA1 for anything new. - -The crypto_digest\*() family of functions manipulates digests. You -can either compute a digest of a chunk of memory all at once using -crypto_digest(), crypto_digest256(), or crypto_digest512(). Or you -can create a crypto_digest_t object with -crypto_digest{,256,512}_new(), feed information to it in chunks using -crypto_digest_add_bytes(), and then extract the final digest using -crypto_digest_get_digest(). You can copy the state of one of these -objects using crypto_digest_dup() or crypto_digest_assign(). - -We support the HMAC hash-based message authentication code -instantiated using SHA256. See crypto_hmac_sha256. (You should not -add any HMAC users with SHA1, and HMAC is not necessary with SHA3.) - -We also support the SHA3 cousins, SHAKE128 and SHAKE256. Unlike -digests, these are extendable output functions (or XOFs) where you can -get any amount of output. Use the crypto_xof_\*() functions to access -these. - -We have several ways to derive keys from cryptographically strong secret -inputs (like diffie-hellman outputs). The old -crypto_expand_key_material-TAP() performs an ad-hoc KDF based on SHA1 -- you -shouldn't use it for implementing anything but old versions of the Tor -protocol. You can use HKDF-SHA256 (as defined in RFC5869) for more modern -protocols. Also consider SHAKE256. - -If your input is potentially weak, like a password or passphrase, use a salt -along with the secret_to_key() functions as defined in crypto_s2k.c. Prefer -scrypt over other hashing methods when possible. If you're using a password -to encrypt something, see the "boxed file storage" section below. - -Finally, in order to store objects in hash tables, Tor includes the -randomized SipHash 2-4 function. Call it via the siphash24g() function in -src/ext/siphash.h whenever you're creating a hashtable whose keys may be -manipulated by an attacker in order to DoS you with collisions. - - -### Stream ciphers ### - -You can create instances of a stream cipher using crypto_cipher_new(). -These are stateful objects of type crypto_cipher_t. Note that these -objects only support AES-128 right now; a future version should add -support for AES-128 and/or ChaCha20. - -You can encrypt/decrypt with crypto_cipher_encrypt or -crypto_cipher_decrypt. The crypto_cipher_crypt_inplace function performs -an encryption without a copy. - -Note that sensible people should not use raw stream ciphers; they should -probably be using some kind of AEAD. Sorry. - -### Public key functionality ### - -We support four public key algorithms: DH1024, RSA, Curve25519, and -Ed25519. - -We support DH1024 over two prime groups. You access these via the -crypto_dh_\*() family of functions. - -We support RSA in many bit sizes for signing and encryption. You access -it via the crypto_pk_*() family of functions. Note that a crypto_pk_t -may or may not include a private key. See the crypto_pk_* functions in -crypto.c for a full list of functions here. - -For Curve25519 functionality, see the functions and types in -crypto_curve25519.c. Curve25519 is generally suitable for when you need -a secure fast elliptic-curve diffie hellman implementation. When -designing new protocols, prefer it over DH in Z_p. - -For Ed25519 functionality, see the functions and types in -crypto_ed25519.c. Ed25519 is a generally suitable as a secure fast -elliptic curve signature method. For new protocols, prefer it over RSA -signatures. - -### Metaformats for storage ### - -When OpenSSL manages the storage of some object, we use whatever format -OpenSSL provides -- typically, some kind of PEM-wrapped base 64 encoding -that starts with "----- BEGIN CRYPTOGRAPHIC OBJECT ----". - -When we manage the storage of some cryptographic object, we prefix the -object with 32-byte NUL-padded prefix in order to avoid accidental -object confusion; see the crypto_read_tagged_contents_from_file() and -crypto_write_tagged_contents_to_file() functions for manipulating -these. The prefix is "== type: tag ==", where type describes the object -and its encoding, and tag indicates which one it is. - -### Boxed-file storage ### - -When managing keys, you frequently want to have some way to write a -secret object to disk, encrypted with a passphrase. The crypto_pwbox -and crypto_unpwbox functions do so in a way that's likely to be -readable by future versions of Tor. ### Certificates ### @@ -153,17 +25,3 @@ napkin. 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.) - -### TLS ### - -Tor's TLS implementation is more tightly coupled to OpenSSL than we'd -prefer. You can read most of it in tortls.c. - -Unfortunately, TLS's state machine and our requirement for nonblocking -IO support means that using TLS in practice is a bit hairy, since -logical writes can block on a physical reads, and vice versa. - -If you are lucky, you will never have to look at the code here. - - - diff --git a/src/lib/crypt_ops/lib_crypt_ops.dox b/src/lib/crypt_ops/lib_crypt_ops.dox index d856d93be..515c67f1c 100644 --- a/src/lib/crypt_ops/lib_crypt_ops.dox +++ b/src/lib/crypt_ops/lib_crypt_ops.dox @@ -9,4 +9,131 @@ constructions that we use. It wraps our two major cryptographic backends (OpenSSL or NSS, as configured by the user), and also wraps other cryptographic code in src/ext. +Generally speaking, Tor code shouldn't be calling OpenSSL or NSS +(or any other crypto library) directly. Instead, we should indirect through +one of the functions in this directory, or through \refdir{lib/tls}. + +Cryptography functionality that's available is described below. + +### RNG facilities ### + +The most basic RNG capability in Tor is the crypto_rand() family of +functions. These currently use OpenSSL's RAND_() backend, but may use +something faster in the future. + +In addition to crypto_rand(), which fills in a buffer with random +bytes, we also have functions to produce random integers in certain +ranges; to produce random hostnames; to produce random doubles, etc. + +When you're creating a long-term cryptographic secret, you might want +to use crypto_strongest_rand() instead of crypto_rand(). It takes the +operating system's entropy source and combines it with output from +crypto_rand(). This is a pure paranoia measure, but it might help us +someday. + +You can use smartlist_choose() to pick a random element from a smartlist +and smartlist_shuffle() to randomize the order of a smartlist. Both are +potentially a bit slow. + +### Cryptographic digests and related functions ### + +We treat digests as separate types based on the length of their +outputs. We support one 160-bit digest (SHA1), two 256-bit digests +(SHA256 and SHA3-256), and two 512-bit digests (SHA512 and SHA3-512). + +You should not use SHA1 for anything new. + +The crypto_digest\*() family of functions manipulates digests. You +can either compute a digest of a chunk of memory all at once using +crypto_digest(), crypto_digest256(), or crypto_digest512(). Or you +can create a crypto_digest_t object with +crypto_digest{,256,512}_new(), feed information to it in chunks using +crypto_digest_add_bytes(), and then extract the final digest using +crypto_digest_get_digest(). You can copy the state of one of these +objects using crypto_digest_dup() or crypto_digest_assign(). + +We support the HMAC hash-based message authentication code +instantiated using SHA256. See crypto_hmac_sha256. (You should not +add any HMAC users with SHA1, and HMAC is not necessary with SHA3.) + +We also support the SHA3 cousins, SHAKE128 and SHAKE256. Unlike +digests, these are extendable output functions (or XOFs) where you can +get any amount of output. Use the crypto_xof_\*() functions to access +these. + +We have several ways to derive keys from cryptographically strong secret +inputs (like diffie-hellman outputs). The old +crypto_expand_key_material_TAP() performs an ad-hoc KDF based on SHA1 -- you +shouldn't use it for implementing anything but old versions of the Tor +protocol. You can use HKDF-SHA256 (as defined in RFC5869) for more modern +protocols. Also consider SHAKE256. + +If your input is potentially weak, like a password or passphrase, use a salt +along with the secret_to_key() functions as defined in crypto_s2k.c. Prefer +scrypt over other hashing methods when possible. If you're using a password +to encrypt something, see the "boxed file storage" section below. + +Finally, in order to store objects in hash tables, Tor includes the +randomized SipHash 2-4 function. Call it via the siphash24g() function in +src/ext/siphash.h whenever you're creating a hashtable whose keys may be +manipulated by an attacker in order to DoS you with collisions. + + +### Stream ciphers ### + +You can create instances of a stream cipher using crypto_cipher_new(). +These are stateful objects of type crypto_cipher_t. Note that these +objects only support AES-128 right now; a future version should add +support for AES-128 and/or ChaCha20. + +You can encrypt/decrypt with crypto_cipher_encrypt or +crypto_cipher_decrypt. The crypto_cipher_crypt_inplace function performs +an encryption without a copy. + +Note that sensible people should not use raw stream ciphers; they should +probably be using some kind of AEAD. Sorry. + +### Public key functionality ### + +We support four public key algorithms: DH1024, RSA, Curve25519, and +Ed25519. + +We support DH1024 over two prime groups. You access these via the +crypto_dh_\*() family of functions. + +We support RSA in many bit sizes for signing and encryption. You access +it via the crypto_pk_*() family of functions. Note that a crypto_pk_t +may or may not include a private key. See the crypto_pk_* functions in +crypto.c for a full list of functions here. + +For Curve25519 functionality, see the functions and types in +crypto_curve25519.c. Curve25519 is generally suitable for when you need +a secure fast elliptic-curve diffie hellman implementation. When +designing new protocols, prefer it over DH in Z_p. + +For Ed25519 functionality, see the functions and types in +crypto_ed25519.c. Ed25519 is a generally suitable as a secure fast +elliptic curve signature method. For new protocols, prefer it over RSA +signatures. + +### Metaformats for storage ### + +When OpenSSL manages the storage of some object, we use whatever format +OpenSSL provides -- typically, some kind of PEM-wrapped base 64 encoding +that starts with "----- BEGIN CRYPTOGRAPHIC OBJECT ----". + +When we manage the storage of some cryptographic object, we prefix the +object with 32-byte NUL-padded prefix in order to avoid accidental +object confusion; see the crypto_read_tagged_contents_from_file() and +crypto_write_tagged_contents_to_file() functions for manipulating +these. The prefix is "== type: tag ==", where type describes the object +and its encoding, and tag indicates which one it is. + +### Boxed-file storage ### + +When managing keys, you frequently want to have some way to write a +secret object to disk, encrypted with a passphrase. The crypto_pwbox +and crypto_unpwbox functions do so in a way that's likely to be +readable by future versions of Tor. + **/

1 0

[tor/master] Divide 01a-memory.md into doxygen.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit fb20618e281f42aaae11c635ddb08a0420c8e6a7 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 12:04:32 2019 -0500 Divide 01a-memory.md into doxygen. --- doc/HACKING/design/01a-memory.md | 103 --------------------------------------- src/lib/malloc/lib_malloc.dox | 73 +++++++++++++++++++++++++++ src/lib/memarea/lib_memarea.dox | 20 ++++++++ 3 files changed, 93 insertions(+), 103 deletions(-) diff --git a/doc/HACKING/design/01a-memory.md b/doc/HACKING/design/01a-memory.md deleted file mode 100644 index 4c6bb0901..000000000 --- a/doc/HACKING/design/01a-memory.md +++ /dev/null @@ -1,103 +0,0 @@ - -## Memory management - -### Heap-allocation functions: lib/malloc/malloc.h - -Tor imposes a few light wrappers over C's native malloc and free -functions, to improve convenience, and to allow wholescale replacement -of malloc and free as needed. - -You should never use 'malloc', 'calloc', 'realloc, or 'free' on their -own; always use the variants prefixed with 'tor_'. -They are the same as the standard C functions, with the following -exceptions: - - * `tor_free(NULL)` is a no-op. - * `tor_free()` is a macro that takes an lvalue as an argument and sets it to - NULL after freeing it. To avoid this behavior, you can use `tor_free_()` - instead. - * tor_malloc() and friends fail with an assertion if they are asked to - allocate a value so large that it is probably an underflow. - * It is always safe to `tor_malloc(0)`, regardless of whether your libc - allows it. - * `tor_malloc()`, `tor_realloc()`, and friends are never allowed to fail. - Instead, Tor will die with an assertion. This means that you never - need to check their return values. See the next subsection for - information on why we think this is a good idea. - -We define additional general-purpose memory allocation functions as well: - - * `tor_malloc_zero(x)` behaves as `calloc(1, x)`, except the it makes clear - the intent to allocate a single zeroed-out value. - * `tor_reallocarray(x,y)` behaves as the OpenBSD reallocarray function. - Use it for cases when you need to realloc() in a multiplication-safe - way. - -And specific-purpose functions as well: - - * `tor_strdup()` and `tor_strndup()` behaves as the underlying libc - functions, but use `tor_malloc()` instead of the underlying function. - * `tor_memdup()` copies a chunk of memory of a given size. - * `tor_memdup_nulterm()` copies a chunk of memory of a given size, then - NUL-terminates it just to be safe. - -#### Why assert on allocation failure? - -Why don't we allow `tor_malloc()` and its allies to return NULL? - -First, it's error-prone. Many programmers forget to check for NULL return -values, and testing for `malloc()` failures is a major pain. - -Second, it's not necessarily a great way to handle OOM conditions. It's -probably better (we think) to have a memory target where we dynamically free -things ahead of time in order to stay under the target. Trying to respond to -an OOM at the point of `tor_malloc()` failure, on the other hand, would involve -a rare operation invoked from deep in the call stack. (Again, that's -error-prone and hard to debug.) - -Third, thanks to the rise of Linux and other operating systems that allow -memory to be overcommitted, you can't actually ever rely on getting a NULL -from `malloc()` when you're out of memory; instead you have to use an approach -closer to tracking the total memory usage. - -#### Conventions for your own allocation functions. - -Whenever you create a new type, the convention is to give it a pair of -`x_new()` and `x_free_()` functions, named after the type. - -Calling `x_free(NULL)` should always be a no-op. - -There should additionally be an `x_free()` macro, defined in terms of -`x_free_()`. This macro should set its lvalue to NULL. You can define it -using the FREE_AND_NULL macro, as follows: - -``` -#define x_free(ptr) FREE_AND_NULL(x_t, x_free_, (ptr)) -``` - - -### Grow-only memory allocation: lib/memarea - -It's often handy to allocate a large number of tiny objects, all of which -need to disappear at the same time. You can do this in tor using the -memarea.c abstraction, which uses a set of grow-only buffers for allocation, -and only supports a single "free" operation at the end. - -Using memareas also helps you avoid memory fragmentation. You see, some libc -malloc implementations perform badly on the case where a large number of -small temporary objects are allocated at the same time as a few long-lived -objects of similar size. But if you use tor_malloc() for the long-lived ones -and a memarea for the temporary object, the malloc implementation is likelier -to do better. - -To create a new memarea, use `memarea_new()`. To drop all the storage from a -memarea, and invalidate its pointers, use `memarea_drop_all()`. - -The allocation functions `memarea_alloc()`, `memarea_alloc_zero()`, -`memarea_memdup()`, `memarea_strdup()`, and `memarea_strndup()` are analogous -to the similarly-named malloc() functions. There is intentionally no -`memarea_free()` or `memarea_realloc()`. - -### Special allocation: lib/malloc/map_anon.h - -TODO: WRITEME. diff --git a/src/lib/malloc/lib_malloc.dox b/src/lib/malloc/lib_malloc.dox index 2553c82f1..c05e4c647 100644 --- a/src/lib/malloc/lib_malloc.dox +++ b/src/lib/malloc/lib_malloc.dox @@ -2,4 +2,77 @@ @dir /lib/malloc @brief lib/malloc: Wrappers and utilities for memory management. + +Tor imposes a few light wrappers over C's native malloc and free +functions, to improve convenience, and to allow wholescale replacement +of malloc and free as needed. + +You should never use 'malloc', 'calloc', 'realloc, or 'free' on their +own; always use the variants prefixed with 'tor_'. +They are the same as the standard C functions, with the following +exceptions: + + * `tor_free(NULL)` is a no-op. + * `tor_free()` is a macro that takes an lvalue as an argument and sets it to + NULL after freeing it. To avoid this behavior, you can use `tor_free_()` + instead. + * tor_malloc() and friends fail with an assertion if they are asked to + allocate a value so large that it is probably an underflow. + * It is always safe to `tor_malloc(0)`, regardless of whether your libc + allows it. + * `tor_malloc()`, `tor_realloc()`, and friends are never allowed to fail. + Instead, Tor will die with an assertion. This means that you never + need to check their return values. See the next subsection for + information on why we think this is a good idea. + +We define additional general-purpose memory allocation functions as well: + + * `tor_malloc_zero(x)` behaves as `calloc(1, x)`, except the it makes clear + the intent to allocate a single zeroed-out value. + * `tor_reallocarray(x,y)` behaves as the OpenBSD reallocarray function. + Use it for cases when you need to realloc() in a multiplication-safe + way. + +And specific-purpose functions as well: + + * `tor_strdup()` and `tor_strndup()` behaves as the underlying libc + functions, but use `tor_malloc()` instead of the underlying function. + * `tor_memdup()` copies a chunk of memory of a given size. + * `tor_memdup_nulterm()` copies a chunk of memory of a given size, then + NUL-terminates it just to be safe. + +#### Why assert on allocation failure? + +Why don't we allow `tor_malloc()` and its allies to return NULL? + +First, it's error-prone. Many programmers forget to check for NULL return +values, and testing for `malloc()` failures is a major pain. + +Second, it's not necessarily a great way to handle OOM conditions. It's +probably better (we think) to have a memory target where we dynamically free +things ahead of time in order to stay under the target. Trying to respond to +an OOM at the point of `tor_malloc()` failure, on the other hand, would involve +a rare operation invoked from deep in the call stack. (Again, that's +error-prone and hard to debug.) + +Third, thanks to the rise of Linux and other operating systems that allow +memory to be overcommitted, you can't actually ever rely on getting a NULL +from `malloc()` when you're out of memory; instead you have to use an approach +closer to tracking the total memory usage. + +#### Conventions for your own allocation functions. + +Whenever you create a new type, the convention is to give it a pair of +`x_new()` and `x_free_()` functions, named after the type. + +Calling `x_free(NULL)` should always be a no-op. + +There should additionally be an `x_free()` macro, defined in terms of +`x_free_()`. This macro should set its lvalue to NULL. You can define it +using the FREE_AND_NULL macro, as follows: + +``` +#define x_free(ptr) FREE_AND_NULL(x_t, x_free_, (ptr)) +``` + **/ diff --git a/src/lib/memarea/lib_memarea.dox b/src/lib/memarea/lib_memarea.dox index 9a7c8c4b2..041191482 100644 --- a/src/lib/memarea/lib_memarea.dox +++ b/src/lib/memarea/lib_memarea.dox @@ -7,4 +7,24 @@ once. This kind of allocation is very fast and avoids fragmentation, at the expense of requiring all the data to be freed at the same time. We use this for parsing and diff calculations. +It's often handy to allocate a large number of tiny objects, all of which +need to disappear at the same time. You can do this in tor using the +memarea.c abstraction, which uses a set of grow-only buffers for allocation, +and only supports a single "free" operation at the end. + +Using memareas also helps you avoid memory fragmentation. You see, some libc +malloc implementations perform badly on the case where a large number of +small temporary objects are allocated at the same time as a few long-lived +objects of similar size. But if you use tor_malloc() for the long-lived ones +and a memarea for the temporary object, the malloc implementation is likelier +to do better. + +To create a new memarea, use `memarea_new()`. To drop all the storage from a +memarea, and invalidate its pointers, use `memarea_drop_all()`. + +The allocation functions `memarea_alloc()`, `memarea_alloc_zero()`, +`memarea_memdup()`, `memarea_strdup()`, and `memarea_strndup()` are analogous +to the similarly-named malloc() functions. There is intentionally no +`memarea_free()` or `memarea_realloc()`. + **/

1 0

[tor/master] Document directories in "app"
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit db402028102f2c98bc92a85b7f7e919c0edf76a1 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 17:23:50 2019 -0500 Document directories in "app" --- src/app/config/app_config.dox | 6 +++++- src/app/main/app_main.dox | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/src/app/config/app_config.dox b/src/app/config/app_config.dox index d0d2ee363..ef4a87827 100644 --- a/src/app/config/app_config.dox +++ b/src/app/config/app_config.dox @@ -1,4 +1,8 @@ /** @dir /app/config -@brief app/config +@brief app/config: Top-level configuration code + +Refactoring this module is a work in progress, see +[ticket 29211](https://trac.torproject.org/projects/tor/ticket/29211). + **/ diff --git a/src/app/main/app_main.dox b/src/app/main/app_main.dox index 3da20226d..c714ad139 100644 --- a/src/app/main/app_main.dox +++ b/src/app/main/app_main.dox @@ -1,4 +1,4 @@ /** @dir /app/main -@brief app/main +@brief app/main: Entry point for tor. **/

1 0

[tor/master] directory-level doxygen for "src/core"
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit e1cdca2e4f58c108539fe4c36205b16caca8d44f Author: Nick Mathewson <nickm(a)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. + **/

1 0

[tor/master] Remove now-superseded part of doc/HACKING/design.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit 4bf73dfa261a1706659bce42a60f1af804a525f6 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 11:52:49 2019 -0500 Remove now-superseded part of doc/HACKING/design. --- doc/HACKING/design/01.00-lib-overview.md | 171 ------------------------------- 1 file changed, 171 deletions(-) diff --git a/doc/HACKING/design/01.00-lib-overview.md b/doc/HACKING/design/01.00-lib-overview.md deleted file mode 100644 index 58a92f406..000000000 --- a/doc/HACKING/design/01.00-lib-overview.md +++ /dev/null @@ -1,171 +0,0 @@ - -## Library code in Tor. - -Most of Tor's utility code is in modules in the `src/lib` subdirectory. In -general, this code is not necessarily Tor-specific, but is instead possibly -useful for other applications. - -This code includes: - - * Compatibility wrappers, to provide a uniform API across different - platforms. - - * Library wrappers, to provide a tor-like API over different libraries - that Tor uses for things like compression and cryptography. - - * Containers, to implement some general-purpose data container types. - -The modules in `src/lib` are currently well-factored: each one depends -only on lower-level modules. You can see an up-to-date list of the -modules sorted from lowest to highest level by running -`./scripts/maint/practracker/includes.py --toposort`. - -As of this writing, the library modules are (from lowest to highest -level): - - * `lib/cc` -- Macros for managing the C compiler and - language. Includes macros for improving compatibility and clarity - across different C compilers. - - * `lib/version` -- Holds the current version of Tor. - - * `lib/testsupport` -- Helpers for making test-only code and test - mocking support. - - * `lib/defs` -- Lowest-level constants used in many places across the - code. - - * `lib/subsys` -- Types used for declaring a "subsystem". A subsystem - is a module with support for initialization, shutdown, - configuration, and so on. - - * `lib/conf` -- Types and macros used for declaring configuration - options. - - * `lib/arch` -- Compatibility functions and macros for handling - differences in CPU architecture. - - * `lib/err` -- Lowest-level error handling code: responsible for - generating stack traces, handling raw assertion failures, and - otherwise reporting problems that might not be safe to report - via the regular logging module. - - * `lib/malloc` -- Wrappers and utilities for memory management. - - * `lib/intmath` -- Utilities for integer mathematics. - - * `lib/fdio` -- Utilities and compatibility code for reading and - writing data on file descriptors (and on sockets, for platforms - where a socket is not a kind of fd). - - * `lib/lock` -- Compatibility code for declaring and using locks. - Lower-level than the rest of the threading code. - - * `lib/ctime` -- Constant-time implementations for data comparison - and table lookup, used to avoid timing side-channels from standard - implementations of memcmp() and so on. - - * `lib/string` -- Low-level compatibility wrappers and utility - functions for string manipulation. - - * `lib/wallclock` -- Compatibility and utility functions for - inspecting and manipulating the current (UTC) time. - - * `lib/osinfo` -- Functions for inspecting the version and - capabilities of the operating system. - - * `lib/smartlist_core` -- The bare-bones pieces of our dynamic array - ("smartlist") implementation. There are higher-level pieces, but - these ones are used by (and therefore cannot use) the logging code. - - * `lib/log` -- Implements the logging system used by all higher-level - Tor code. You can think of this as the logical "midpoint" of the - library code: much of the higher-level code is higher-level - _because_ it uses the logging module, and much of the lower-level - code is specifically written to avoid having to log, because the - logging module depends on it. - - * `lib/container` -- General purpose containers, including dynamic arrays - ("smartlists"), hashtables, bit arrays, weak-reference-like "handles", - bloom filters, and a bit more. - - * `lib/trace` -- A general-purpose API for introducing - function-tracing functionality into Tor. Currently not much used. - - * `lib/thread` -- Threading compatibility and utility functionality, - other than low-level locks (which are in `lib/lock`) and - workqueue/threadpool code (which belongs in `lib/evloop`). - - * `lib/term` -- Code for terminal manipulation functions (like - reading a password from the user). - - * `lib/memarea` -- A data structure for a fast "arena" style allocator, - where the data is freed all at once. Used for parsing. - - * `lib/encoding` -- Implementations for encoding data in various - formats, datatypes, and transformations. - - * `lib/dispatch` -- A general-purpose in-process message delivery - system. Used by `lib/pubsub` to implement our inter-module - publish/subscribe system. - - * `lib/sandbox` -- Our Linux seccomp2 sandbox implementation. - - * `lib/pubsub` -- Code and macros to implement our publish/subscribe - message passing system. - - * `lib/fs` -- Utility and compatibility code for manipulating files, - filenames, directories, and so on. - - * `lib/confmgt` -- Code to parse, encode, and manipulate our - configuration files, state files, and so forth. - - * `lib/crypt_ops` -- Cryptographic operations. This module contains - wrappers around the cryptographic libraries that we support, - and implementations for some higher-level cryptographic - constructions that we use. - - * `lib/meminfo` -- Functions for inspecting our memory usage, if the - malloc implementation exposes that to us. - - * `lib/time` -- Higher level time functions, including fine-gained and - monotonic timers. - - * `lib/math` -- Floating-point mathematical utilities, including - compatibility code, and probability distributions. - - * `lib/buf` -- A general purpose queued buffer implementation, - similar to the BSD kernel's "mbuf" structure. - - * `lib/net` -- Networking code, including address manipulation, - compatibility wrappers, - - * `lib/compress` -- A compatibility wrapper around several - compression libraries, currently including zlib, zstd, and lzma. - - * `lib/geoip` -- Utilities to manage geoip (IP to country) lookups - and formats. - - * `lib/tls` -- Compatibility wrappers around the library (NSS or - OpenSSL, depending on configuration) that Tor uses to implement the - TLS link security protocol. - - * `lib/evloop` -- Tools to manage the event loop and related - functionality, in order to implement asynchronous networking, - timers, periodic events, and other scheduling tasks. - - * `lib/process` -- Utilities and compatibility code to launch and - manage subprocesses. - -### What belongs in lib? - -In general, if you can imagine some program wanting the functionality -you're writing, even if that program had nothing to do with Tor, your -functionality belongs in lib. - -If it falls into one of the existing "lib" categories, your -functionality belongs in lib. - -If you are using platform-specific `#ifdef`s to manage compatibility -issues among platforms, you should probably consider whether you can -put your code into lib.

1 0

[tor/master] Doxygen: add several missing links.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit aac80a004f91a453733fed0ba62c00d7d1e2b76d Author: Nick Mathewson <nickm(a)torproject.org> Date: Tue Nov 5 08:05:42 2019 -0500 Doxygen: add several missing links. --- src/feature/dirauth/feature_dirauth.dox | 5 +++++ src/feature/hs/feature_hs.dox | 5 +++++ src/feature/rend/feature_rend.dox | 4 ++++ src/mainpage.dox | 8 ++++---- 4 files changed, 18 insertions(+), 4 deletions(-) diff --git a/src/feature/dirauth/feature_dirauth.dox b/src/feature/dirauth/feature_dirauth.dox index 93c680e47..9ee2d0458 100644 --- a/src/feature/dirauth/feature_dirauth.dox +++ b/src/feature/dirauth/feature_dirauth.dox @@ -3,4 +3,9 @@ @brief feature/dirauth: Directory authority implementation. This module handles running Tor as a directory authority. + +The directory protocol is specified in +[dir-spec.txt](https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt). + + **/ diff --git a/src/feature/hs/feature_hs.dox b/src/feature/hs/feature_hs.dox index 35a574d01..32f44d57f 100644 --- a/src/feature/hs/feature_hs.dox +++ b/src/feature/hs/feature_hs.dox @@ -2,4 +2,9 @@ @dir /feature/hs @brief feature/hs: v3 (current) onion service protocol +This directory implements the v3 onion service protocol, +as specified in +[rend-spec-v3.txt](https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt). + + **/ diff --git a/src/feature/rend/feature_rend.dox b/src/feature/rend/feature_rend.dox index e92406804..ed0784521 100644 --- a/src/feature/rend/feature_rend.dox +++ b/src/feature/rend/feature_rend.dox @@ -2,4 +2,8 @@ @dir /feature/rend @brief feature/rend: version 2 (old) hidden services +This directory implements the v2 onion service protocol, +as specified in +[rend-spec-v2.txt](https://gitweb.torproject.org/torspec.git/tree/rend-spec-v2.txt). + **/ diff --git a/src/mainpage.dox b/src/mainpage.dox index 7c64e0dff..02ce8675e 100644 --- a/src/mainpage.dox +++ b/src/mainpage.dox @@ -1,9 +1,7 @@ /** @mainpage Tor source reference -@section intro Getting to know Tor - -Welcome! +@section intro Welcome to Tor This documentation describes the general structure of the Tor codebase, how it fits together, what functionality is available for extending Tor, and @@ -22,7 +20,9 @@ This document is not an overview of the Tor protocol. For that, see the design paper and the specifications at https://spec.torproject.org/ . For more information about Tor's coding standards and some helpful -development tools, see doc/HACKING in the Tor repository. +development tools, see +[doc/HACKING](https://gitweb.torproject.org/tor.git/tree/doc/HACKING) in the +Tor repository. @section highlevel The very high level

1 0

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

05 Nov '19

1 0

[translation/torbirdy_completed] https://gitweb.torproject.org/translation.git/commit/?h=torbirdy_completed
by translation＠torproject.org 05 Nov '19

05 Nov '19

commit 6f0efcab0c0dc06c4bb4a987424a9965fb5c6d51 Author: Translation commit bot <translation(a)torproject.org> Date: Tue Nov 5 11:20:54 2019 +0000 https://gitweb.torproject.org/translation.git/commit/?h=torbirdy_completed --- nl/torbirdy.dtd | 112 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/nl/torbirdy.dtd b/nl/torbirdy.dtd index 93b1dd24c..a73bc0a74 100644 --- a/nl/torbirdy.dtd +++ b/nl/torbirdy.dtd @@ -1,58 +1,58 @@ -<!ENTITY torbirdy.accountprefs.title "Accountinstellingen"> -<!ENTITY torbirdy.accountprefs.startup.label "Op nieuwe berichten controleren bij opstarten"> -<!ENTITY torbirdy.accountprefs.startup.key "C"> -<!ENTITY torbirdy.accountprefs.minutes.label "Op nieuwe berichten controleren elke"> -<!ENTITY torbirdy.accountprefs.minutes.key "y"> -<!ENTITY torbirdy.accountprefs.minutes.trail.label "minuten"> -<!ENTITY torbirdy.accountprefs.cancel.button "Annuleren"> -<!ENTITY torbirdy.accountprefs.save.button "Opslaan"> -<!ENTITY torbirdy.accountprefs.save.key "S"> +<!ENTITY torbirdy.accountprefs.title ""> +<!ENTITY torbirdy.accountprefs.startup.label ""> +<!ENTITY torbirdy.accountprefs.startup.key ""> +<!ENTITY torbirdy.accountprefs.minutes.label ""> +<!ENTITY torbirdy.accountprefs.minutes.key ""> +<!ENTITY torbirdy.accountprefs.minutes.trail.label ""> +<!ENTITY torbirdy.accountprefs.cancel.button ""> +<!ENTITY torbirdy.accountprefs.save.button ""> +<!ENTITY torbirdy.accountprefs.save.key ""> -<!ENTITY torbirdy.prefs.title "TorBirdy configuratie"> -<!ENTITY torbirdy.prefs.save.button "Opslaan"> -<!ENTITY torbirdy.prefs.save.key "s"> -<!ENTITY torbirdy.prefs.cancel.button "Annuleren"> -<!ENTITY torbirdy.prefs.extra2.button "Terugzetten op begintoestand"> -<!ENTITY torbirdy.prefs.extra2.key "d"> -<!ENTITY torbirdy.prefs.testproxy.button "Test Proxy Instellingen"> -<!ENTITY torbirdy.prefs.testproxy.key "n"> -<!ENTITY torbirdy.prefs.proxy.label "Proxy"> -<!ENTITY torbirdy.prefs.privacy.label "Privacy"> -<!ENTITY torbirdy.prefs.enigmail.label "Enigmail"> -<!ENTITY torbirdy.prefs.recommended.text "Aanbevolen configuratie voor TorBirdy (Tor) gebruiken"> -<!ENTITY torbirdy.prefs.recommended.key "r"> -<!ENTITY torbirdy.prefs.anonservice.text "Kies een anonimiseringsdienst"> -<!ENTITY torbirdy.prefs.anonservice.key "a"> -<!ENTITY torbirdy.prefs.customsettings.text "Gebruik een aangepaste proxyconfiguratie"> -<!ENTITY torbirdy.prefs.customsettings.key "c"> -<!ENTITY torbirdy.prefs.socks_host.label "SOCKS Host: "> -<!ENTITY torbirdy.prefs.socks_host.key "h"> -<!ENTITY torbirdy.prefs.socks_port.label "Port: "> -<!ENTITY torbirdy.prefs.socks_port.key "p"> -<!ENTITY torbirdy.prefs.torification.label "Transparant Torification (waarschuwing: vereist custom transproxy of Tor router)"> -<!ENTITY torbirdy.prefs.torification.key "t"> -<!ENTITY torbirdy.prefs.global "Globaal"> -<!ENTITY torbirdy.prefs.imap.label "Ondersteuning voor push e-mail voor IMAP-accounts inschakelen [standaard: uitgeschakeld]"> -<!ENTITY torbirdy.prefs.imap.key "p"> -<!ENTITY torbirdy.prefs.startup_folder.label "Bij opstarten direct naar de laatst bekeken map gaan [standaard: uitgeschakeld]"> -<!ENTITY torbirdy.prefs.startup_folder.key "l"> -<!ENTITY torbirdy.prefs.enigmail_throwkeyid.label "Plaats key ID's van ontvangers niet in versleutelde berichten [standaard: wel plaatsen]"> -<!ENTITY torbirdy.prefs.enigmail_throwkeyid.key "r"> -<!ENTITY torbirdy.prefs.enigmail_protected.label "Uitschakelen gecodeerde email headers [standaard: ingeschakeld]"> -<!ENTITY torbirdy.prefs.enigmail_protected.key "d"> -<!ENTITY torbirdy.prefs.confirmemail.label "Bevestig het versturen van e-mail als Enigmail is ingeschakeld [standaard: bevestig niet]"> -<!ENTITY torbirdy.prefs.confirmemail.key "c"> -<!ENTITY torbirdy.prefs.emailwizard.label "Schakel Thunderbird's automatische e-mail configuratie-wizard in [standaard: uitgeschakeld]"> -<!ENTITY torbirdy.prefs.emailwizard.key "w"> -<!ENTITY torbirdy.prefs.automatic.label "Controleer automatisch op nieuwe berichten voor alle accounts [standaard: uitgeschakeld]"> -<!ENTITY torbirdy.prefs.automatic.key "f"> -<!ENTITY torbirdy.prefs.account_specific "Account-specifiek"> -<!ENTITY torbirdy.prefs.select_account.key "C"> -<!ENTITY torbirdy.prefs.select_account.label "Kies een account: "> -<!ENTITY torbirdy.prefs.enigmail.keyserver.label "Te gebruiken sleutelserver(s):"> -<!ENTITY torbirdy.prefs.enigmail.keyserver.key "k"> +<!ENTITY torbirdy.prefs.title ""> +<!ENTITY torbirdy.prefs.save.button ""> +<!ENTITY torbirdy.prefs.save.key ""> +<!ENTITY torbirdy.prefs.cancel.button ""> +<!ENTITY torbirdy.prefs.extra2.button ""> +<!ENTITY torbirdy.prefs.extra2.key ""> +<!ENTITY torbirdy.prefs.testproxy.button ""> +<!ENTITY torbirdy.prefs.testproxy.key ""> +<!ENTITY torbirdy.prefs.proxy.label ""> +<!ENTITY torbirdy.prefs.privacy.label ""> +<!ENTITY torbirdy.prefs.enigmail.label ""> +<!ENTITY torbirdy.prefs.recommended.text ""> +<!ENTITY torbirdy.prefs.recommended.key ""> +<!ENTITY torbirdy.prefs.anonservice.text ""> +<!ENTITY torbirdy.prefs.anonservice.key ""> +<!ENTITY torbirdy.prefs.customsettings.text ""> +<!ENTITY torbirdy.prefs.customsettings.key ""> +<!ENTITY torbirdy.prefs.socks_host.label ""> +<!ENTITY torbirdy.prefs.socks_host.key ""> +<!ENTITY torbirdy.prefs.socks_port.label ""> +<!ENTITY torbirdy.prefs.socks_port.key ""> +<!ENTITY torbirdy.prefs.torification.label ""> +<!ENTITY torbirdy.prefs.torification.key ""> +<!ENTITY torbirdy.prefs.global ""> +<!ENTITY torbirdy.prefs.imap.label ""> +<!ENTITY torbirdy.prefs.imap.key ""> +<!ENTITY torbirdy.prefs.startup_folder.label ""> +<!ENTITY torbirdy.prefs.startup_folder.key ""> +<!ENTITY torbirdy.prefs.enigmail_throwkeyid.label ""> +<!ENTITY torbirdy.prefs.enigmail_throwkeyid.key ""> +<!ENTITY torbirdy.prefs.enigmail_protected.label ""> +<!ENTITY torbirdy.prefs.enigmail_protected.key ""> +<!ENTITY torbirdy.prefs.confirmemail.label ""> +<!ENTITY torbirdy.prefs.confirmemail.key ""> +<!ENTITY torbirdy.prefs.emailwizard.label ""> +<!ENTITY torbirdy.prefs.emailwizard.key ""> +<!ENTITY torbirdy.prefs.automatic.label ""> +<!ENTITY torbirdy.prefs.automatic.key ""> +<!ENTITY torbirdy.prefs.account_specific ""> +<!ENTITY torbirdy.prefs.select_account.key ""> +<!ENTITY torbirdy.prefs.select_account.label ""> +<!ENTITY torbirdy.prefs.enigmail.keyserver.label ""> +<!ENTITY torbirdy.prefs.enigmail.keyserver.key ""> -<!ENTITY torbirdy.panel.usetor.label "Gebruik Tor Onion Router"> -<!ENTITY torbirdy.panel.usejondo.label "Gebruik JonDo (Premium)"> -<!ENTITY torbirdy.panel.usewhonix.label "Gebruik Whonix"> -<!ENTITY torbirdy.panel.preferences.label "Open TorBirdy voorkeuren"> +<!ENTITY torbirdy.panel.usetor.label ""> +<!ENTITY torbirdy.panel.usejondo.label ""> +<!ENTITY torbirdy.panel.usewhonix.label ""> +<!ENTITY torbirdy.panel.preferences.label "">

1 0

[translation/torbirdy] https://gitweb.torproject.org/translation.git/commit/?h=torbirdy
by translation＠torproject.org 05 Nov '19

05 Nov '19

commit 8d676df4488e9ba8fa06170cea9a2bc0e39e7586 Author: Translation commit bot <translation(a)torproject.org> Date: Tue Nov 5 11:20:48 2019 +0000 https://gitweb.torproject.org/translation.git/commit/?h=torbirdy --- nl/torbirdy.dtd | 70 ++++++++++++++++++++++++++++----------------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/nl/torbirdy.dtd b/nl/torbirdy.dtd index 93b1dd24c..f68a5134a 100644 --- a/nl/torbirdy.dtd +++ b/nl/torbirdy.dtd @@ -1,58 +1,58 @@ -<!ENTITY torbirdy.accountprefs.title "Accountinstellingen"> +<!ENTITY torbirdy.accountprefs.title "Accountconfiguratie"> <!ENTITY torbirdy.accountprefs.startup.label "Op nieuwe berichten controleren bij opstarten"> -<!ENTITY torbirdy.accountprefs.startup.key "C"> -<!ENTITY torbirdy.accountprefs.minutes.label "Op nieuwe berichten controleren elke"> -<!ENTITY torbirdy.accountprefs.minutes.key "y"> +<!ENTITY torbirdy.accountprefs.startup.key "c"> +<!ENTITY torbirdy.accountprefs.minutes.label "Op nieuwe berichten controleren om de"> +<!ENTITY torbirdy.accountprefs.minutes.key "k"> <!ENTITY torbirdy.accountprefs.minutes.trail.label "minuten"> <!ENTITY torbirdy.accountprefs.cancel.button "Annuleren"> <!ENTITY torbirdy.accountprefs.save.button "Opslaan"> -<!ENTITY torbirdy.accountprefs.save.key "S"> +<!ENTITY torbirdy.accountprefs.save.key "s"> -<!ENTITY torbirdy.prefs.title "TorBirdy configuratie"> +<!ENTITY torbirdy.prefs.title "TorBirdy-voorkeuren"> <!ENTITY torbirdy.prefs.save.button "Opslaan"> <!ENTITY torbirdy.prefs.save.key "s"> <!ENTITY torbirdy.prefs.cancel.button "Annuleren"> -<!ENTITY torbirdy.prefs.extra2.button "Terugzetten op begintoestand"> +<!ENTITY torbirdy.prefs.extra2.button "Standaardwaarden herstellen"> <!ENTITY torbirdy.prefs.extra2.key "d"> -<!ENTITY torbirdy.prefs.testproxy.button "Test Proxy Instellingen"> +<!ENTITY torbirdy.prefs.testproxy.button "Proxyinstellingen testen"> <!ENTITY torbirdy.prefs.testproxy.key "n"> <!ENTITY torbirdy.prefs.proxy.label "Proxy"> <!ENTITY torbirdy.prefs.privacy.label "Privacy"> <!ENTITY torbirdy.prefs.enigmail.label "Enigmail"> -<!ENTITY torbirdy.prefs.recommended.text "Aanbevolen configuratie voor TorBirdy (Tor) gebruiken"> +<!ENTITY torbirdy.prefs.recommended.text "Aanbevolen proxyinstellingen voor TorBirdy (Tor) gebruiken"> <!ENTITY torbirdy.prefs.recommended.key "r"> <!ENTITY torbirdy.prefs.anonservice.text "Kies een anonimiseringsdienst"> <!ENTITY torbirdy.prefs.anonservice.key "a"> -<!ENTITY torbirdy.prefs.customsettings.text "Gebruik een aangepaste proxyconfiguratie"> -<!ENTITY torbirdy.prefs.customsettings.key "c"> -<!ENTITY torbirdy.prefs.socks_host.label "SOCKS Host: "> +<!ENTITY torbirdy.prefs.customsettings.text "Aangepaste proxyinstellingen gebruiken"> +<!ENTITY torbirdy.prefs.customsettings.key "A"> +<!ENTITY torbirdy.prefs.socks_host.label "SOCKS-host: "> <!ENTITY torbirdy.prefs.socks_host.key "h"> -<!ENTITY torbirdy.prefs.socks_port.label "Port: "> -<!ENTITY torbirdy.prefs.socks_port.key "p"> -<!ENTITY torbirdy.prefs.torification.label "Transparant Torification (waarschuwing: vereist custom transproxy of Tor router)"> -<!ENTITY torbirdy.prefs.torification.key "t"> +<!ENTITY torbirdy.prefs.socks_port.label "Poort: "> +<!ENTITY torbirdy.prefs.socks_port.key "P"> +<!ENTITY torbirdy.prefs.torification.label "Transparante Torificatie (waarschuwing: vereist aangepaste transproxy of Tor-router)"> +<!ENTITY torbirdy.prefs.torification.key "T"> <!ENTITY torbirdy.prefs.global "Globaal"> -<!ENTITY torbirdy.prefs.imap.label "Ondersteuning voor push e-mail voor IMAP-accounts inschakelen [standaard: uitgeschakeld]"> +<!ENTITY torbirdy.prefs.imap.label "Ondersteuning voor push-e-mail voor IMAP-accounts inschakelen [standaard: uitgeschakeld]"> <!ENTITY torbirdy.prefs.imap.key "p"> -<!ENTITY torbirdy.prefs.startup_folder.label "Bij opstarten direct naar de laatst bekeken map gaan [standaard: uitgeschakeld]"> -<!ENTITY torbirdy.prefs.startup_folder.key "l"> -<!ENTITY torbirdy.prefs.enigmail_throwkeyid.label "Plaats key ID's van ontvangers niet in versleutelde berichten [standaard: wel plaatsen]"> -<!ENTITY torbirdy.prefs.enigmail_throwkeyid.key "r"> -<!ENTITY torbirdy.prefs.enigmail_protected.label "Uitschakelen gecodeerde email headers [standaard: ingeschakeld]"> -<!ENTITY torbirdy.prefs.enigmail_protected.key "d"> -<!ENTITY torbirdy.prefs.confirmemail.label "Bevestig het versturen van e-mail als Enigmail is ingeschakeld [standaard: bevestig niet]"> -<!ENTITY torbirdy.prefs.confirmemail.key "c"> -<!ENTITY torbirdy.prefs.emailwizard.label "Schakel Thunderbird's automatische e-mail configuratie-wizard in [standaard: uitgeschakeld]"> +<!ENTITY torbirdy.prefs.startup_folder.label "Laatst bekeken map selecteren bij opstarten [standaard: uitgeschakeld]"> +<!ENTITY torbirdy.prefs.startup_folder.key "L"> +<!ENTITY torbirdy.prefs.enigmail_throwkeyid.label "Geen sleutel-ID's van ontvangers in versleutelde berichten plaatsen [standaard: wel plaatsen]"> +<!ENTITY torbirdy.prefs.enigmail_throwkeyid.key "o"> +<!ENTITY torbirdy.prefs.enigmail_protected.label "Versleutelde e-mailheaders uitschakelen [standaard: ingeschakeld]"> +<!ENTITY torbirdy.prefs.enigmail_protected.key "u"> +<!ENTITY torbirdy.prefs.confirmemail.label "Voor het verzenden van e-mail bevestigen dat Enigmail is ingeschakeld [standaard: niet bevestigen]"> +<!ENTITY torbirdy.prefs.confirmemail.key "b"> +<!ENTITY torbirdy.prefs.emailwizard.label "Automatische e-mailconfiguratiewizard van Thunderbird inschakelen [standaard: uitgeschakeld]"> <!ENTITY torbirdy.prefs.emailwizard.key "w"> -<!ENTITY torbirdy.prefs.automatic.label "Controleer automatisch op nieuwe berichten voor alle accounts [standaard: uitgeschakeld]"> -<!ENTITY torbirdy.prefs.automatic.key "f"> -<!ENTITY torbirdy.prefs.account_specific "Account-specifiek"> -<!ENTITY torbirdy.prefs.select_account.key "C"> +<!ENTITY torbirdy.prefs.automatic.label "Automatisch op nieuwe berichten controleren voor alle accounts [standaard: uitgeschakeld]"> +<!ENTITY torbirdy.prefs.automatic.key "v"> +<!ENTITY torbirdy.prefs.account_specific "Accountspecifiek"> +<!ENTITY torbirdy.prefs.select_account.key "c"> <!ENTITY torbirdy.prefs.select_account.label "Kies een account: "> <!ENTITY torbirdy.prefs.enigmail.keyserver.label "Te gebruiken sleutelserver(s):"> -<!ENTITY torbirdy.prefs.enigmail.keyserver.key "k"> +<!ENTITY torbirdy.prefs.enigmail.keyserver.key "s"> -<!ENTITY torbirdy.panel.usetor.label "Gebruik Tor Onion Router"> -<!ENTITY torbirdy.panel.usejondo.label "Gebruik JonDo (Premium)"> -<!ENTITY torbirdy.panel.usewhonix.label "Gebruik Whonix"> -<!ENTITY torbirdy.panel.preferences.label "Open TorBirdy voorkeuren"> +<!ENTITY torbirdy.panel.usetor.label "Tor Onion Router gebruiken"> +<!ENTITY torbirdy.panel.usejondo.label "JonDo (Premium) gebruiken"> +<!ENTITY torbirdy.panel.usewhonix.label "Whonix gebruiken"> +<!ENTITY torbirdy.panel.preferences.label "TorBirdy-voorkeuren openen">

1 0