commit 9c8dbcd0d676e9092da75c7bdae75679c9d753e3 Author: Nick Mathewson nickm@torproject.org Date: Wed Oct 26 12:38:50 2016 -0400

More module documentation (circpathbias, circuitlist) --- src/or/circpathbias.c | 8 ++++++++ src/or/circuitlist.c | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- src/or/entrynodes.h | 9 +++++++++ 3 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/src/or/circpathbias.c b/src/or/circpathbias.c index 9f93e73..6ee69aa 100644 --- a/src/or/circpathbias.c +++ b/src/or/circpathbias.c @@ -11,6 +11,14 @@ * different tor nodes, in an attempt to detect attacks where * an attacker deliberately causes circuits to fail until the client * choses a path they like. + * + * This code is currently configured in a warning-only mode, though false + * positives appear to be rare in practice. There is also support for + * disabling really bad guards, but it's quite experimental and may have bad + * anonymity effects. + * + * The information here is associated with the entry_guard_t object for + * each guard, and stored persistently in the state file. */

#include "or.h" diff --git a/src/or/circuitlist.c b/src/or/circuitlist.c index 2b3c416..a0988c6 100644 --- a/src/or/circuitlist.c +++ b/src/or/circuitlist.c @@ -7,7 +7,48 @@ /** * \file circuitlist.c * - * \brief Manage the global circuit list, and looking up circuits within it. + * \brief Manage global structures that list and index circuits, and + * look up circuits within them. + * + * One of the most frequent operations in Tor occurs every time that + * a relay cell arrives on a channel. When that happens, we need to + * find which circuit it is associated with, based on the channel and the + * circuit ID in the relay cell. + * + * To handle that, we maintain a global list of circuits, and a hashtable + * mapping [channel,circID] pairs to circuits. Circuits are added to and + * removed from this mapping using circuit_set_p_circid_chan() and + * circuit_set_n_circid_chan(). To look up a circuit from this map, most + * callers should use circuit_get_by_circid_channel(), though + * circuit_get_by_circid_channel_even_if_marked() is appropriate under some + * circumstances. + * + * We also need to allow for the possibility that we have blocked use of a + * circuit ID (because we are waiting to send a DESTROY cell), but the + * circuit is not there any more. For that case, we allow placeholder + * entries in the table, using channel_mark_circid_unusable(). + * + * To efficiently handle a channel that has just opened, we also maintain a + * list of the circuits waiting for channels, so we can attach them as + * needed without iterating through the whole list of circuits, using + * circuit_get_all_pending_on_channel(). + * + * In this module, we also handle the list of circuits that have been + * marked for close elsewhere, and close them as needed. (We use this + * "mark now, close later" pattern here and elsewhere to avoid + * unpredictable recursion if we closed every circuit immediately upon + * realizing it needed to close.) See circuit_mark_for_close() for the + * mark function, and circuit_close_all_marked() for the close function. + * + * For hidden services, we need to be able to look up introduction point + * circuits and rendezvous circuits by cookie, key, etc. These are + * currently handled with linear searches in + * circuit_get_ready_rend_circuit_by_rend_data(), + * circuit_get_next_by_pk_and_purpose(), and with hash lookups in + * circuit_get_rendezvous() and circuit_get_intro_point(). + * + * This module is also the entry point for our out-of-memory handler + * logic, which was originally circuit-focused. **/ #define CIRCUITLIST_PRIVATE #include "or.h" @@ -1539,6 +1580,14 @@ circuit_set_intro_point_digest(or_circuit_t *circ, const uint8_t *digest) * cannibalize. * * If !CIRCLAUNCH_NEED_UPTIME, prefer returning non-uptime circuits. + * + * To "cannibalize" a circuit means to extend it an extra hop, and use it + * for some other purpose than we had originally intended. We do this when + * we want to perform some low-bandwidth task at a specific relay, and we + * would like the circuit to complete as soon as possible. (If we were going + * to use a lot of bandwidth, we wouldn't want a circuit with an extra hop. + * If we didn't care about circuit completion latency, we would just build + * a new circuit.) */ origin_circuit_t * circuit_find_to_cannibalize(uint8_t purpose, extend_info_t *info, diff --git a/src/or/entrynodes.h b/src/or/entrynodes.h index eb2fbf7..00f9691 100644 --- a/src/or/entrynodes.h +++ b/src/or/entrynodes.h @@ -56,6 +56,14 @@ typedef struct entry_guard_t { time_t last_attempted; /**< 0 if we can connect to this guard, or the time * at which we last failed to connect to it. */

+ /** + * @name circpathbias fields + * + * These fields are used in circpathbias.c to try to detect entry + * nodes that are failing circuits at a suspicious frequency. + */ + /**@{*/ + double circ_attempts; /**< Number of circuits this guard has "attempted" */ double circ_successes; /**< Number of successfully built circuits using * this guard as first hop. */ @@ -71,6 +79,7 @@ typedef struct entry_guard_t { double use_attempts; /**< Number of circuits we tried to use with streams */ double use_successes; /**< Number of successfully used circuits using * this guard as first hop. */ + /**@}*/ } entry_guard_t;

entry_guard_t *entry_guard_get_by_id_digest_for_guard_selection(