1 /* Copyright (c) 2001 Matej Pfajfar.
2 * Copyright (c) 2001-2004, Roger Dingledine.
3 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4 * Copyright (c) 2007-2020, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
9 * \brief Code to manage our fixed first nodes for various functions.
11 * Entry nodes can be guards (for general use) or bridges (for censorship
14 * In general, we use entry guards to prevent traffic-sampling attacks:
15 * if we chose every circuit independently, an adversary controlling
16 * some fraction of paths on the network would observe a sample of every
17 * user's traffic. Using guards gives users a chance of not being
20 * The current entry guard selection code is designed to try to avoid
21 * _ever_ trying every guard on the network, to try to stick to guards
22 * that we've used before, to handle hostile/broken networks, and
23 * to behave sanely when the network goes up and down.
25 * Our algorithm works as follows: First, we maintain a SAMPLE of guards
26 * we've seen in the networkstatus consensus. We maintain this sample
27 * over time, and store it persistently; it is chosen without reference
28 * to our configuration or firewall rules. Guards remain in the sample
29 * as they enter and leave the consensus. We expand this sample as
30 * needed, up to a maximum size.
32 * As a subset of the sample, we maintain a FILTERED SET of the guards
33 * that we would be willing to use if we could connect to them. The
34 * filter removes all the guards that we're excluding because they're
35 * bridges (or not bridges), because we have restrictive firewall rules,
36 * because of ExcludeNodes, because we of path bias restrictions,
37 * because they're absent from the network at present, and so on.
39 * As a subset of the filtered set, we keep a REACHABLE FILTERED SET
40 * (also called a "usable filtered set") of those guards that we call
41 * "reachable" or "maybe reachable". A guard is reachable if we've
42 * connected to it more recently than we've failed. A guard is "maybe
43 * reachable" if we have never tried to connect to it, or if we
44 * failed to connect to it so long ago that we no longer think our
45 * failure means it's down.
47 * As a persistent ordered list whose elements are taken from the
48 * sampled set, we track a CONFIRMED GUARDS LIST. A guard becomes
49 * confirmed when we successfully build a circuit through it, and decide
50 * to use that circuit. We order the guards on this list by the order
51 * in which they became confirmed.
53 * And as a final group, we have an ordered list of PRIMARY GUARDS,
54 * whose elements are taken from the filtered set. We prefer
55 * confirmed guards to non-confirmed guards for this list, and place
56 * other restrictions on it. The primary guards are the ones that we
57 * connect to "when nothing is wrong" -- circuits through them can be used
60 * To build circuits, we take a primary guard if possible -- or a
61 * reachable filtered confirmed guard if no primary guard is possible --
62 * or a random reachable filtered guard otherwise. If the guard is
63 * primary, we can use the circuit immediately on success. Otherwise,
64 * the guard is now "pending" -- we won't use its circuit unless all
65 * of the circuits we're trying to build through better guards have
68 * While we're building circuits, we track a little "guard state" for
69 * each circuit. We use this to keep track of whether the circuit is
70 * one that we can use as soon as it's done, or whether it's one that
71 * we should keep around to see if we can do better. In the latter case,
72 * a periodic call to entry_guards_upgrade_waiting_circuits() will
73 * eventually upgrade it.
75 /* DOCDOC -- expand this.
77 * Information invariants:
79 * [x] whenever a guard becomes unreachable, clear its usable_filtered flag.
81 * [x] Whenever a guard becomes reachable or maybe-reachable, if its filtered
82 * flag is set, set its usable_filtered flag.
84 * [x] Whenever we get a new consensus, call update_from_consensus(). (LATER.)
86 * [x] Whenever the configuration changes in a relevant way, update the
87 * filtered/usable flags. (LATER.)
89 * [x] Whenever we add a guard to the sample, make sure its filtered/usable
90 * flags are set as possible.
92 * [x] Whenever we remove a guard from the sample, remove it from the primary
93 * and confirmed lists.
95 * [x] When we make a guard confirmed, update the primary list.
97 * [x] When we make a guard filtered or unfiltered, update the primary list.
99 * [x] When we are about to pick a guard, make sure that the primary list is
102 * [x] Before calling sample_reachable_filtered_entry_guards(), make sure
103 * that the filtered, primary, and confirmed flags are up-to-date.
105 * [x] Call entry_guard_consider_retry every time we are about to check
106 * is_usable_filtered or is_reachable, and every time we set
109 * [x] Call entry_guards_changed_for_guard_selection() whenever we update
110 * a persistent field.
113 #define ENTRYNODES_PRIVATE
115 #include "core/or/or.h"
116 #include "app/config/config.h"
117 #include "lib/confmgt/confmgt.h"
118 #include "app/config/statefile.h"
119 #include "core/mainloop/connection.h"
120 #include "core/mainloop/mainloop.h"
121 #include "core/or/channel.h"
122 #include "core/or/circuitbuild.h"
123 #include "core/or/circuitlist.h"
124 #include "core/or/circuitstats.h"
125 #include "core/or/circuituse.h"
126 #include "core/or/policies.h"
127 #include "feature/client/bridges.h"
128 #include "feature/client/circpathbias.h"
129 #include "feature/client/entrynodes.h"
130 #include "feature/client/transports.h"
131 #include "feature/control/control_events.h"
132 #include "feature/dircommon/directory.h"
133 #include "feature/nodelist/describe.h"
134 #include "feature/nodelist/microdesc.h"
135 #include "feature/nodelist/networkstatus.h"
136 #include "feature/nodelist/nickname.h"
137 #include "feature/nodelist/nodelist.h"
138 #include "feature/nodelist/node_select.h"
139 #include "feature/nodelist/routerset.h"
140 #include "feature/relay/router.h"
141 #include "lib/crypt_ops/crypto_rand.h"
142 #include "lib/crypt_ops/digestset.h"
143 #include "lib/encoding/confline.h"
144 #include "lib/math/fp.h"
146 #include "feature/nodelist/node_st.h"
147 #include "core/or/origin_circuit_st.h"
148 #include "app/config/or_state_st.h"
150 /** A list of existing guard selection contexts. */
151 static smartlist_t
*guard_contexts
= NULL
;
152 /** The currently enabled guard selection context. */
153 static guard_selection_t
*curr_guard_context
= NULL
;
155 /** A value of 1 means that at least one context has changed,
156 * and those changes need to be flushed to disk. */
157 static int entry_guards_dirty
= 0;
159 static void entry_guard_set_filtered_flags(const or_options_t
*options
,
160 guard_selection_t
*gs
,
161 entry_guard_t
*guard
);
162 static void pathbias_check_use_success_count(entry_guard_t
*guard
);
163 static void pathbias_check_close_success_count(entry_guard_t
*guard
);
164 static int node_is_possible_guard(const node_t
*node
);
165 static int node_passes_guard_filter(const or_options_t
*options
,
167 static entry_guard_t
*entry_guard_add_to_sample_impl(guard_selection_t
*gs
,
168 const uint8_t *rsa_id_digest
,
169 const char *nickname
,
170 const tor_addr_port_t
*bridge_addrport
);
171 static entry_guard_t
*get_sampled_guard_by_bridge_addr(guard_selection_t
*gs
,
172 const tor_addr_port_t
*addrport
);
173 static int entry_guard_obeys_restriction(const entry_guard_t
*guard
,
174 const entry_guard_restriction_t
*rst
);
176 /** Return 0 if we should apply guardfraction information found in the
177 * consensus. A specific consensus can be specified with the
178 * <b>ns</b> argument, if NULL the most recent one will be picked.*/
180 should_apply_guardfraction(const networkstatus_t
*ns
)
182 /* We need to check the corresponding torrc option and the consensus
183 * parameter if we need to. */
184 const or_options_t
*options
= get_options();
186 /* If UseGuardFraction is 'auto' then check the same-named consensus
187 * parameter. If the consensus parameter is not present, default to
189 if (options
->UseGuardFraction
== -1) {
190 return networkstatus_get_param(ns
, "UseGuardFraction",
191 0, /* default to "off" */
195 return options
->UseGuardFraction
;
198 /** Return true iff we know a preferred descriptor for <b>guard</b> */
200 guard_has_descriptor(const entry_guard_t
*guard
)
202 const node_t
*node
= node_get_by_id(guard
->identity
);
205 return node_has_preferred_descriptor(node
, 1);
209 * Try to determine the correct type for a selection named "name",
210 * if <b>type</b> is GS_TYPE_INFER.
212 STATIC guard_selection_type_t
213 guard_selection_infer_type(guard_selection_type_t type
,
216 if (type
== GS_TYPE_INFER
) {
217 if (!strcmp(name
, "bridges"))
218 type
= GS_TYPE_BRIDGE
;
219 else if (!strcmp(name
, "restricted"))
220 type
= GS_TYPE_RESTRICTED
;
222 type
= GS_TYPE_NORMAL
;
228 * Allocate and return a new guard_selection_t, with the name <b>name</b>.
230 STATIC guard_selection_t
*
231 guard_selection_new(const char *name
,
232 guard_selection_type_t type
)
234 guard_selection_t
*gs
;
236 type
= guard_selection_infer_type(type
, name
);
238 gs
= tor_malloc_zero(sizeof(*gs
));
239 gs
->name
= tor_strdup(name
);
241 gs
->sampled_entry_guards
= smartlist_new();
242 gs
->confirmed_entry_guards
= smartlist_new();
243 gs
->primary_entry_guards
= smartlist_new();
249 * Return the guard selection called <b>name</b>. If there is none, and
250 * <b>create_if_absent</b> is true, then create and return it. If there
251 * is none, and <b>create_if_absent</b> is false, then return NULL.
253 STATIC guard_selection_t
*
254 get_guard_selection_by_name(const char *name
,
255 guard_selection_type_t type
,
256 int create_if_absent
)
258 if (!guard_contexts
) {
259 guard_contexts
= smartlist_new();
261 SMARTLIST_FOREACH_BEGIN(guard_contexts
, guard_selection_t
*, gs
) {
262 if (!strcmp(gs
->name
, name
))
264 } SMARTLIST_FOREACH_END(gs
);
266 if (! create_if_absent
)
269 log_debug(LD_GUARD
, "Creating a guard selection called %s", name
);
270 guard_selection_t
*new_selection
= guard_selection_new(name
, type
);
271 smartlist_add(guard_contexts
, new_selection
);
273 return new_selection
;
277 * Allocate the first guard context that we're planning to use,
278 * and make it the current context.
281 create_initial_guard_context(void)
283 tor_assert(! curr_guard_context
);
284 if (!guard_contexts
) {
285 guard_contexts
= smartlist_new();
287 guard_selection_type_t type
= GS_TYPE_INFER
;
288 const char *name
= choose_guard_selection(
290 networkstatus_get_reasonably_live_consensus(
292 usable_consensus_flavor()),
295 tor_assert(name
); // "name" can only be NULL if we had an old name.
296 tor_assert(type
!= GS_TYPE_INFER
);
297 log_notice(LD_GUARD
, "Starting with guard context \"%s\"", name
);
298 curr_guard_context
= get_guard_selection_by_name(name
, type
, 1);
301 /** Get current default guard_selection_t, creating it if necessary */
303 get_guard_selection_info(void)
305 if (!curr_guard_context
) {
306 create_initial_guard_context();
309 return curr_guard_context
;
312 /** Return a statically allocated human-readable description of <b>guard</b>
315 entry_guard_describe(const entry_guard_t
*guard
)
317 static char buf
[256];
318 tor_snprintf(buf
, sizeof(buf
),
320 strlen(guard
->nickname
) ? guard
->nickname
: "[bridge]",
321 hex_str(guard
->identity
, DIGEST_LEN
));
325 /** Return <b>guard</b>'s 20-byte RSA identity digest */
327 entry_guard_get_rsa_id_digest(const entry_guard_t
*guard
)
329 return guard
->identity
;
332 /** Return the pathbias state associated with <b>guard</b>. */
334 entry_guard_get_pathbias_state(entry_guard_t
*guard
)
339 HANDLE_IMPL(entry_guard
, entry_guard_t
, ATTR_UNUSED STATIC
)
341 /** Return an interval betweeen 'now' and 'max_backdate' seconds in the past,
342 * chosen uniformly at random. We use this before recording persistent
343 * dates, so that we aren't leaking exactly when we recorded it.
345 MOCK_IMPL(STATIC
time_t,
346 randomize_time
,(time_t now
, time_t max_backdate
))
348 tor_assert(max_backdate
> 0);
350 time_t earliest
= now
- max_backdate
;
354 if (latest
<= earliest
)
355 latest
= earliest
+ 1;
357 return crypto_rand_time_range(earliest
, latest
);
361 * @name parameters for networkstatus algorithm
363 * These parameters are taken from the consensus; some are overrideable in
368 * We never let our sampled guard set grow larger than this fraction
369 * of the guards on the network.
372 get_max_sample_threshold(void)
375 networkstatus_get_param(NULL
, "guard-max-sample-threshold-percent",
376 DFLT_MAX_SAMPLE_THRESHOLD_PERCENT
,
381 * We never let our sampled guard set grow larger than this number.
384 get_max_sample_size_absolute(void)
386 return (int) networkstatus_get_param(NULL
, "guard-max-sample-size",
387 DFLT_MAX_SAMPLE_SIZE
,
391 * We always try to make our sample contain at least this many guards.
394 get_min_filtered_sample_size(void)
396 return networkstatus_get_param(NULL
, "guard-min-filtered-sample-size",
397 DFLT_MIN_FILTERED_SAMPLE_SIZE
,
401 * If a guard is unlisted for this many days in a row, we remove it.
404 get_remove_unlisted_guards_after_days(void)
406 return networkstatus_get_param(NULL
,
407 "guard-remove-unlisted-guards-after-days",
408 DFLT_REMOVE_UNLISTED_GUARDS_AFTER_DAYS
,
413 * Return number of seconds that will make a guard no longer eligible
414 * for selection if unlisted for this long.
417 get_remove_unlisted_guards_after_seconds(void)
419 return get_remove_unlisted_guards_after_days() * 24 * 60 * 60;
423 * We remove unconfirmed guards from the sample after this many days,
424 * regardless of whether they are listed or unlisted.
427 get_guard_lifetime(void)
429 if (get_options()->GuardLifetime
>= 86400)
430 return get_options()->GuardLifetime
;
432 days
= networkstatus_get_param(NULL
,
433 "guard-lifetime-days",
434 DFLT_GUARD_LIFETIME_DAYS
, 1, 365*10);
438 * We remove confirmed guards from the sample if they were sampled
439 * GUARD_LIFETIME_DAYS ago and confirmed this many days ago.
442 get_guard_confirmed_min_lifetime(void)
444 if (get_options()->GuardLifetime
>= 86400)
445 return get_options()->GuardLifetime
;
447 days
= networkstatus_get_param(NULL
, "guard-confirmed-min-lifetime-days",
448 DFLT_GUARD_CONFIRMED_MIN_LIFETIME_DAYS
,
453 * How many guards do we try to keep on our primary guard list?
456 get_n_primary_guards(void)
458 /* If the user has explicitly configured the number of primary guards, do
459 * what the user wishes to do */
460 const int configured_primaries
= get_options()->NumPrimaryGuards
;
461 if (configured_primaries
) {
462 return configured_primaries
;
465 /* otherwise check for consensus parameter and if that's not set either, just
466 * use the default value. */
467 return networkstatus_get_param(NULL
,
468 "guard-n-primary-guards",
469 DFLT_N_PRIMARY_GUARDS
, 1, INT32_MAX
);
472 * Return the number of the live primary guards we should look at when
476 get_n_primary_guards_to_use(guard_usage_t usage
)
479 const char *param_name
;
482 /* If the user has explicitly configured the amount of guards, use
483 that. Otherwise, fall back to the default value. */
484 if (usage
== GUARD_USAGE_DIRGUARD
) {
485 configured
= get_options()->NumDirectoryGuards
;
486 param_name
= "guard-n-primary-dir-guards-to-use";
487 param_default
= DFLT_N_PRIMARY_DIR_GUARDS_TO_USE
;
489 configured
= get_options()->NumEntryGuards
;
490 param_name
= "guard-n-primary-guards-to-use";
491 param_default
= DFLT_N_PRIMARY_GUARDS_TO_USE
;
493 if (configured
>= 1) {
496 return networkstatus_get_param(NULL
,
497 param_name
, param_default
, 1, INT32_MAX
);
500 * If we haven't successfully built or used a circuit in this long, then
501 * consider that the internet is probably down.
504 get_internet_likely_down_interval(void)
506 return networkstatus_get_param(NULL
, "guard-internet-likely-down-interval",
507 DFLT_INTERNET_LIKELY_DOWN_INTERVAL
,
511 * If we're trying to connect to a nonprimary guard for at least this
512 * many seconds, and we haven't gotten the connection to work, we will treat
513 * lower-priority guards as usable.
516 get_nonprimary_guard_connect_timeout(void)
518 return networkstatus_get_param(NULL
,
519 "guard-nonprimary-guard-connect-timeout",
520 DFLT_NONPRIMARY_GUARD_CONNECT_TIMEOUT
,
524 * If a circuit has been sitting around in 'waiting for better guard' state
525 * for at least this long, we'll expire it.
528 get_nonprimary_guard_idle_timeout(void)
530 return networkstatus_get_param(NULL
,
531 "guard-nonprimary-guard-idle-timeout",
532 DFLT_NONPRIMARY_GUARD_IDLE_TIMEOUT
,
536 * If our configuration retains fewer than this fraction of guards from the
537 * torrc, we are in a restricted setting.
540 get_meaningful_restriction_threshold(void)
542 int32_t pct
= networkstatus_get_param(NULL
,
543 "guard-meaningful-restriction-percent",
544 DFLT_MEANINGFUL_RESTRICTION_PERCENT
,
549 * If our configuration retains fewer than this fraction of guards from the
550 * torrc, we are in an extremely restricted setting, and should warn.
553 get_extreme_restriction_threshold(void)
555 int32_t pct
= networkstatus_get_param(NULL
,
556 "guard-extreme-restriction-percent",
557 DFLT_EXTREME_RESTRICTION_PERCENT
,
562 /* Mark <b>guard</b> as maybe reachable again. */
564 mark_guard_maybe_reachable(entry_guard_t
*guard
)
566 if (guard
->is_reachable
!= GUARD_REACHABLE_NO
) {
570 /* Note that we do not clear failing_since: this guard is now only
571 * _maybe-reachable_. */
572 guard
->is_reachable
= GUARD_REACHABLE_MAYBE
;
573 if (guard
->is_filtered_guard
)
574 guard
->is_usable_filtered_guard
= 1;
578 * Called when the network comes up after having seemed to be down for
579 * a while: Mark the primary guards as maybe-reachable so that we'll
583 mark_primary_guards_maybe_reachable(guard_selection_t
*gs
)
587 if (!gs
->primary_guards_up_to_date
)
588 entry_guards_update_primary(gs
);
590 SMARTLIST_FOREACH_BEGIN(gs
->primary_entry_guards
, entry_guard_t
*, guard
) {
591 mark_guard_maybe_reachable(guard
);
592 } SMARTLIST_FOREACH_END(guard
);
595 /* Called when we exhaust all guards in our sampled set: Marks all guards as
596 maybe-reachable so that we 'll try them again. */
598 mark_all_guards_maybe_reachable(guard_selection_t
*gs
)
602 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
603 mark_guard_maybe_reachable(guard
);
604 } SMARTLIST_FOREACH_END(guard
);
610 * Given our options and our list of nodes, return the name of the
611 * guard selection that we should use. Return NULL for "use the
612 * same selection you were using before.
615 choose_guard_selection(const or_options_t
*options
,
616 const networkstatus_t
*live_ns
,
617 const guard_selection_t
*old_selection
,
618 guard_selection_type_t
*type_out
)
621 tor_assert(type_out
);
623 if (options
->UseBridges
) {
624 *type_out
= GS_TYPE_BRIDGE
;
629 /* without a networkstatus, we can't tell any more than that. */
630 *type_out
= GS_TYPE_NORMAL
;
634 const smartlist_t
*nodes
= nodelist_get_list();
635 int n_guards
= 0, n_passing_filter
= 0;
636 SMARTLIST_FOREACH_BEGIN(nodes
, const node_t
*, node
) {
637 if (node_is_possible_guard(node
)) {
639 if (node_passes_guard_filter(options
, node
)) {
643 } SMARTLIST_FOREACH_END(node
);
645 /* We use separate 'high' and 'low' thresholds here to prevent flapping
647 const int meaningful_threshold_high
=
648 (int)(n_guards
* get_meaningful_restriction_threshold() * 1.05);
649 const int meaningful_threshold_mid
=
650 (int)(n_guards
* get_meaningful_restriction_threshold());
651 const int meaningful_threshold_low
=
652 (int)(n_guards
* get_meaningful_restriction_threshold() * .95);
653 const int extreme_threshold
=
654 (int)(n_guards
* get_extreme_restriction_threshold());
657 If we have no previous selection, then we're "restricted" iff we are
658 below the meaningful restriction threshold. That's easy enough.
660 But if we _do_ have a previous selection, we make it a little
661 "sticky": we only move from "restricted" to "default" when we find
662 that we're above the threshold plus 5%, and we only move from
663 "default" to "restricted" when we're below the threshold minus 5%.
664 That should prevent us from flapping back and forth if we happen to
665 be hovering very close to the default.
667 The extreme threshold is for warning only.
670 static int have_warned_extreme_threshold
= 0;
672 n_passing_filter
< extreme_threshold
&&
673 ! have_warned_extreme_threshold
) {
674 have_warned_extreme_threshold
= 1;
675 const double exclude_frac
=
676 (n_guards
- n_passing_filter
) / (double)n_guards
;
677 log_warn(LD_GUARD
, "Your configuration excludes %d%% of all possible "
678 "guards. That's likely to make you stand out from the "
679 "rest of the world.", (int)(exclude_frac
* 100));
682 /* Easy case: no previous selection. Just check if we are in restricted or
683 normal guard selection. */
684 if (old_selection
== NULL
) {
685 if (n_passing_filter
>= meaningful_threshold_mid
) {
686 *type_out
= GS_TYPE_NORMAL
;
689 *type_out
= GS_TYPE_RESTRICTED
;
694 /* Trickier case: we do have a previous guard selection context. */
695 tor_assert(old_selection
);
697 /* Use high and low thresholds to decide guard selection, and if we fall in
698 the middle then keep the current guard selection context. */
699 if (n_passing_filter
>= meaningful_threshold_high
) {
700 *type_out
= GS_TYPE_NORMAL
;
702 } else if (n_passing_filter
< meaningful_threshold_low
) {
703 *type_out
= GS_TYPE_RESTRICTED
;
706 /* we are in the middle: maintain previous guard selection */
707 *type_out
= old_selection
->type
;
708 return old_selection
->name
;
713 * Check whether we should switch from our current guard selection to a
714 * different one. If so, switch and return 1. Return 0 otherwise.
716 * On a 1 return, the caller should mark all currently live circuits unusable
717 * for new streams, by calling circuit_mark_all_unused_circs() and
718 * circuit_mark_all_dirty_circs_as_unusable().
721 update_guard_selection_choice(const or_options_t
*options
)
723 if (!curr_guard_context
) {
724 create_initial_guard_context();
728 guard_selection_type_t type
= GS_TYPE_INFER
;
729 const char *new_name
= choose_guard_selection(
731 networkstatus_get_reasonably_live_consensus(
733 usable_consensus_flavor()),
736 tor_assert(new_name
);
737 tor_assert(type
!= GS_TYPE_INFER
);
739 const char *cur_name
= curr_guard_context
->name
;
740 if (! strcmp(cur_name
, new_name
)) {
742 "Staying with guard context \"%s\" (no change)", new_name
);
743 return 0; // No change
746 log_notice(LD_GUARD
, "Switching to guard context \"%s\" (was using \"%s\")",
748 guard_selection_t
*new_guard_context
;
749 new_guard_context
= get_guard_selection_by_name(new_name
, type
, 1);
750 tor_assert(new_guard_context
);
751 tor_assert(new_guard_context
!= curr_guard_context
);
752 curr_guard_context
= new_guard_context
;
758 * Return true iff <b>node</b> has all the flags needed for us to consider it
759 * a possible guard when sampling guards.
762 node_is_possible_guard(const node_t
*node
)
764 /* The "GUARDS" set is all nodes in the nodelist for which this predicate
768 return (node
->is_possible_guard
&&
773 !router_digest_is_me(node
->identity
));
777 * Return the sampled guard with the RSA identity digest <b>rsa_id</b>, or
778 * NULL if we don't have one. */
779 STATIC entry_guard_t
*
780 get_sampled_guard_with_id(guard_selection_t
*gs
,
781 const uint8_t *rsa_id
)
785 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
786 if (tor_memeq(guard
->identity
, rsa_id
, DIGEST_LEN
))
788 } SMARTLIST_FOREACH_END(guard
);
792 /** If <b>gs</b> contains a sampled entry guard matching <b>bridge</b>,
793 * return that guard. Otherwise return NULL. */
794 static entry_guard_t
*
795 get_sampled_guard_for_bridge(guard_selection_t
*gs
,
796 const bridge_info_t
*bridge
)
798 const uint8_t *id
= bridge_get_rsa_id_digest(bridge
);
799 const tor_addr_port_t
*addrport
= bridge_get_addr_port(bridge
);
800 entry_guard_t
*guard
;
802 return NULL
; // LCOV_EXCL_LINE
803 guard
= get_sampled_guard_by_bridge_addr(gs
, addrport
);
804 if (! guard
|| (id
&& tor_memneq(id
, guard
->identity
, DIGEST_LEN
)))
810 /** If we know a bridge_info_t matching <b>guard</b>, return that
811 * bridge. Otherwise return NULL. */
812 static bridge_info_t
*
813 get_bridge_info_for_guard(const entry_guard_t
*guard
)
815 const uint8_t *identity
= NULL
;
816 if (! tor_digest_is_zero(guard
->identity
)) {
817 identity
= (const uint8_t *)guard
->identity
;
819 if (BUG(guard
->bridge_addr
== NULL
))
822 return get_configured_bridge_by_exact_addr_port_digest(
823 &guard
->bridge_addr
->addr
,
824 guard
->bridge_addr
->port
,
825 (const char*)identity
);
829 * Return true iff we have a sampled guard with the RSA identity digest
832 have_sampled_guard_with_id(guard_selection_t
*gs
, const uint8_t *rsa_id
)
834 return get_sampled_guard_with_id(gs
, rsa_id
) != NULL
;
838 * Allocate a new entry_guard_t object for <b>node</b>, add it to the
839 * sampled entry guards in <b>gs</b>, and return it. <b>node</b> must
840 * not currently be a sampled guard in <b>gs</b>.
842 STATIC entry_guard_t
*
843 entry_guard_add_to_sample(guard_selection_t
*gs
,
846 log_info(LD_GUARD
, "Adding %s to the entry guard sample set.",
847 node_describe(node
));
849 /* make sure that the guard is not already sampled. */
850 if (BUG(have_sampled_guard_with_id(gs
, (const uint8_t*)node
->identity
)))
851 return NULL
; // LCOV_EXCL_LINE
853 return entry_guard_add_to_sample_impl(gs
,
854 (const uint8_t*)node
->identity
,
855 node_get_nickname(node
),
860 * Backend: adds a new sampled guard to <b>gs</b>, with given identity,
861 * nickname, and ORPort. rsa_id_digest and bridge_addrport are optional, but
862 * we need one of them. nickname is optional. The caller is responsible for
863 * maintaining the size limit of the SAMPLED_GUARDS set.
865 static entry_guard_t
*
866 entry_guard_add_to_sample_impl(guard_selection_t
*gs
,
867 const uint8_t *rsa_id_digest
,
868 const char *nickname
,
869 const tor_addr_port_t
*bridge_addrport
)
871 const int GUARD_LIFETIME
= get_guard_lifetime();
874 // XXXX #20827 take ed25519 identity here too.
876 /* Make sure we can actually identify the guard. */
877 if (BUG(!rsa_id_digest
&& !bridge_addrport
))
878 return NULL
; // LCOV_EXCL_LINE
880 entry_guard_t
*guard
= tor_malloc_zero(sizeof(entry_guard_t
));
882 /* persistent fields */
883 guard
->is_persistent
= (rsa_id_digest
!= NULL
);
884 guard
->selection_name
= tor_strdup(gs
->name
);
886 memcpy(guard
->identity
, rsa_id_digest
, DIGEST_LEN
);
888 strlcpy(guard
->nickname
, nickname
, sizeof(guard
->nickname
));
889 guard
->sampled_on_date
= randomize_time(approx_time(), GUARD_LIFETIME
/10);
890 tor_free(guard
->sampled_by_version
);
891 guard
->sampled_by_version
= tor_strdup(VERSION
);
892 guard
->currently_listed
= 1;
893 guard
->confirmed_idx
= -1;
895 /* non-persistent fields */
896 guard
->is_reachable
= GUARD_REACHABLE_MAYBE
;
898 guard
->bridge_addr
= tor_memdup(bridge_addrport
, sizeof(*bridge_addrport
));
900 smartlist_add(gs
->sampled_entry_guards
, guard
);
901 guard
->in_selection
= gs
;
902 entry_guard_set_filtered_flags(get_options(), gs
, guard
);
903 entry_guards_changed_for_guard_selection(gs
);
908 * Add an entry guard to the "bridges" guard selection sample, with
909 * information taken from <b>bridge</b>. Return that entry guard.
911 static entry_guard_t
*
912 entry_guard_add_bridge_to_sample(guard_selection_t
*gs
,
913 const bridge_info_t
*bridge
)
915 const uint8_t *id_digest
= bridge_get_rsa_id_digest(bridge
);
916 const tor_addr_port_t
*addrport
= bridge_get_addr_port(bridge
);
918 tor_assert(addrport
);
920 /* make sure that the guard is not already sampled. */
921 if (BUG(get_sampled_guard_for_bridge(gs
, bridge
)))
922 return NULL
; // LCOV_EXCL_LINE
924 return entry_guard_add_to_sample_impl(gs
, id_digest
, NULL
, addrport
);
928 * Return the entry_guard_t in <b>gs</b> whose address is <b>addrport</b>,
929 * or NULL if none exists.
931 static entry_guard_t
*
932 get_sampled_guard_by_bridge_addr(guard_selection_t
*gs
,
933 const tor_addr_port_t
*addrport
)
939 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, g
) {
940 if (g
->bridge_addr
&& tor_addr_port_eq(addrport
, g
->bridge_addr
))
942 } SMARTLIST_FOREACH_END(g
);
946 /** Update the guard subsystem's knowledge of the identity of the bridge
947 * at <b>addrport</b>. Idempotent.
950 entry_guard_learned_bridge_identity(const tor_addr_port_t
*addrport
,
951 const uint8_t *rsa_id_digest
)
953 guard_selection_t
*gs
= get_guard_selection_by_name("bridges",
959 entry_guard_t
*g
= get_sampled_guard_by_bridge_addr(gs
, addrport
);
963 int make_persistent
= 0;
965 if (tor_digest_is_zero(g
->identity
)) {
966 memcpy(g
->identity
, rsa_id_digest
, DIGEST_LEN
);
968 } else if (tor_memeq(g
->identity
, rsa_id_digest
, DIGEST_LEN
)) {
969 /* Nothing to see here; we learned something we already knew. */
970 if (BUG(! g
->is_persistent
))
973 char old_id
[HEX_DIGEST_LEN
+1];
974 base16_encode(old_id
, sizeof(old_id
), g
->identity
, sizeof(g
->identity
));
975 log_warn(LD_BUG
, "We 'learned' an identity %s for a bridge at %s:%d, but "
976 "we already knew a different one (%s). Ignoring the new info as "
978 hex_str((const char *)rsa_id_digest
, DIGEST_LEN
),
979 fmt_and_decorate_addr(&addrport
->addr
), addrport
->port
,
981 return; // redundant, but let's be clear: we're not making this persistent.
984 if (make_persistent
) {
985 g
->is_persistent
= 1;
986 entry_guards_changed_for_guard_selection(gs
);
991 * Return the number of sampled guards in <b>gs</b> that are "filtered"
992 * (that is, we're willing to connect to them) and that are "usable"
993 * (that is, either "reachable" or "maybe reachable").
995 * If a restriction is provided in <b>rst</b>, do not count any guards that
999 num_reachable_filtered_guards(const guard_selection_t
*gs
,
1000 const entry_guard_restriction_t
*rst
)
1002 int n_reachable_filtered_guards
= 0;
1003 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
1004 entry_guard_consider_retry(guard
);
1005 if (! entry_guard_obeys_restriction(guard
, rst
))
1007 if (guard
->is_usable_filtered_guard
)
1008 ++n_reachable_filtered_guards
;
1009 } SMARTLIST_FOREACH_END(guard
);
1010 return n_reachable_filtered_guards
;
1013 /** Return the actual maximum size for the sample in <b>gs</b>,
1014 * given that we know about <b>n_guards</b> total. */
1016 get_max_sample_size(guard_selection_t
*gs
,
1019 const int using_bridges
= (gs
->type
== GS_TYPE_BRIDGE
);
1020 const int min_sample
= get_min_filtered_sample_size();
1022 /* If we are in bridge mode, expand our sample set as needed without worrying
1023 * about max size. We should respect the user's wishes to use many bridges if
1024 * that's what they have specified in their configuration file. */
1028 const int max_sample_by_pct
= (int)(n_guards
* get_max_sample_threshold());
1029 const int max_sample_absolute
= get_max_sample_size_absolute();
1030 const int max_sample
= MIN(max_sample_by_pct
, max_sample_absolute
);
1031 if (max_sample
< min_sample
)
1038 * Return a smartlist of the all the guards that are not currently
1039 * members of the sample (GUARDS - SAMPLED_GUARDS). The elements of
1040 * this list are node_t pointers in the non-bridge case, and
1041 * bridge_info_t pointers in the bridge case. Set *<b>n_guards_out</b>
1042 * to the number of guards that we found in GUARDS, including those
1043 * that were already sampled.
1045 static smartlist_t
*
1046 get_eligible_guards(const or_options_t
*options
,
1047 guard_selection_t
*gs
,
1050 /* Construct eligible_guards as GUARDS - SAMPLED_GUARDS */
1051 smartlist_t
*eligible_guards
= smartlist_new();
1052 int n_guards
= 0; // total size of "GUARDS"
1054 if (gs
->type
== GS_TYPE_BRIDGE
) {
1055 const smartlist_t
*bridges
= bridge_list_get();
1056 SMARTLIST_FOREACH_BEGIN(bridges
, bridge_info_t
*, bridge
) {
1058 if (NULL
!= get_sampled_guard_for_bridge(gs
, bridge
)) {
1061 smartlist_add(eligible_guards
, bridge
);
1062 } SMARTLIST_FOREACH_END(bridge
);
1064 const smartlist_t
*nodes
= nodelist_get_list();
1065 const int n_sampled
= smartlist_len(gs
->sampled_entry_guards
);
1067 /* Build a bloom filter of our current guards: let's keep this O(N). */
1068 digestset_t
*sampled_guard_ids
= digestset_new(n_sampled
);
1069 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, const entry_guard_t
*,
1071 digestset_add(sampled_guard_ids
, guard
->identity
);
1072 } SMARTLIST_FOREACH_END(guard
);
1074 SMARTLIST_FOREACH_BEGIN(nodes
, const node_t
*, node
) {
1075 if (! node_is_possible_guard(node
))
1077 if (gs
->type
== GS_TYPE_RESTRICTED
) {
1078 /* In restricted mode, we apply the filter BEFORE sampling, so
1079 * that we are sampling from the nodes that we might actually
1080 * select. If we sampled first, we might wind up with a sample
1081 * that didn't include any EntryNodes at all. */
1082 if (! node_passes_guard_filter(options
, node
))
1086 if (digestset_probably_contains(sampled_guard_ids
, node
->identity
))
1088 smartlist_add(eligible_guards
, (node_t
*)node
);
1089 } SMARTLIST_FOREACH_END(node
);
1091 /* Now we can free that bloom filter. */
1092 digestset_free(sampled_guard_ids
);
1095 *n_guards_out
= n_guards
;
1096 return eligible_guards
;
1099 /** Helper: given a smartlist of either bridge_info_t (if gs->type is
1100 * GS_TYPE_BRIDGE) or node_t (otherwise), pick one that can be a guard,
1101 * add it as a guard, remove it from the list, and return a new
1102 * entry_guard_t. Return NULL on failure. */
1103 static entry_guard_t
*
1104 select_and_add_guard_item_for_sample(guard_selection_t
*gs
,
1105 smartlist_t
*eligible_guards
)
1107 entry_guard_t
*added_guard
;
1108 if (gs
->type
== GS_TYPE_BRIDGE
) {
1109 const bridge_info_t
*bridge
= smartlist_choose(eligible_guards
);
1111 return NULL
; // LCOV_EXCL_LINE
1112 smartlist_remove(eligible_guards
, bridge
);
1113 added_guard
= entry_guard_add_bridge_to_sample(gs
, bridge
);
1115 const node_t
*node
=
1116 node_sl_choose_by_bandwidth(eligible_guards
, WEIGHT_FOR_GUARD
);
1118 return NULL
; // LCOV_EXCL_LINE
1119 smartlist_remove(eligible_guards
, node
);
1120 added_guard
= entry_guard_add_to_sample(gs
, node
);
1127 * Return true iff we need a consensus to update our guards, but we don't
1128 * have one. (We can return 0 here either if the consensus is _not_ missing,
1129 * or if we don't need a consensus because we're using bridges.)
1132 reasonably_live_consensus_is_missing(const guard_selection_t
*gs
)
1135 if (gs
->type
== GS_TYPE_BRIDGE
) {
1136 /* We don't update bridges from the consensus; they aren't there. */
1139 return networkstatus_get_reasonably_live_consensus(
1141 usable_consensus_flavor()) == NULL
;
1145 * Add new guards to the sampled guards in <b>gs</b> until there are
1146 * enough usable filtered guards, but never grow the sample beyond its
1147 * maximum size. Return the last guard added, or NULL if none were
1150 STATIC entry_guard_t
*
1151 entry_guards_expand_sample(guard_selection_t
*gs
)
1154 const or_options_t
*options
= get_options();
1156 if (reasonably_live_consensus_is_missing(gs
)) {
1157 log_info(LD_GUARD
, "Not expanding the sample guard set; we have "
1158 "no reasonably live consensus.");
1162 int n_sampled
= smartlist_len(gs
->sampled_entry_guards
);
1163 entry_guard_t
*added_guard
= NULL
;
1164 int n_usable_filtered_guards
= num_reachable_filtered_guards(gs
, NULL
);
1166 smartlist_t
*eligible_guards
= get_eligible_guards(options
, gs
, &n_guards
);
1168 const int max_sample
= get_max_sample_size(gs
, n_guards
);
1169 const int min_filtered_sample
= get_min_filtered_sample_size();
1171 log_info(LD_GUARD
, "Expanding the sample guard set. We have %d guards "
1172 "in the sample, and %d eligible guards to extend it with.",
1173 n_sampled
, smartlist_len(eligible_guards
));
1175 while (n_usable_filtered_guards
< min_filtered_sample
) {
1176 /* Has our sample grown too large to expand? */
1177 if (n_sampled
>= max_sample
) {
1178 log_info(LD_GUARD
, "Not expanding the guard sample any further; "
1179 "just hit the maximum sample threshold of %d",
1184 /* Did we run out of guards? */
1185 if (smartlist_len(eligible_guards
) == 0) {
1187 As long as MAX_SAMPLE_THRESHOLD makes can't be adjusted to
1188 allow all guards to be sampled, this can't be reached.
1190 log_info(LD_GUARD
, "Not expanding the guard sample any further; "
1191 "just ran out of eligible guards");
1193 /* LCOV_EXCL_STOP */
1196 /* Otherwise we can add at least one new guard. */
1197 added_guard
= select_and_add_guard_item_for_sample(gs
, eligible_guards
);
1199 goto done
; // LCOV_EXCL_LINE -- only fails on BUG.
1203 if (added_guard
->is_usable_filtered_guard
)
1204 ++n_usable_filtered_guards
;
1208 smartlist_free(eligible_guards
);
1213 * Helper: <b>guard</b> has just been removed from the sampled guards:
1214 * also remove it from primary and confirmed. */
1216 remove_guard_from_confirmed_and_primary_lists(guard_selection_t
*gs
,
1217 entry_guard_t
*guard
)
1219 if (guard
->is_primary
) {
1220 guard
->is_primary
= 0;
1221 smartlist_remove_keeporder(gs
->primary_entry_guards
, guard
);
1223 if (BUG(smartlist_contains(gs
->primary_entry_guards
, guard
))) {
1224 smartlist_remove_keeporder(gs
->primary_entry_guards
, guard
);
1228 if (guard
->confirmed_idx
>= 0) {
1229 smartlist_remove_keeporder(gs
->confirmed_entry_guards
, guard
);
1230 guard
->confirmed_idx
= -1;
1231 guard
->confirmed_on_date
= 0;
1233 if (BUG(smartlist_contains(gs
->confirmed_entry_guards
, guard
))) {
1235 smartlist_remove_keeporder(gs
->confirmed_entry_guards
, guard
);
1241 /** Return true iff <b>guard</b> is currently "listed" -- that is, it
1242 * appears in the consensus, or as a configured bridge (as
1244 MOCK_IMPL(STATIC
int,
1245 entry_guard_is_listed
,(guard_selection_t
*gs
, const entry_guard_t
*guard
))
1247 if (gs
->type
== GS_TYPE_BRIDGE
) {
1248 return NULL
!= get_bridge_info_for_guard(guard
);
1250 const node_t
*node
= node_get_by_id(guard
->identity
);
1252 return node
&& node_is_possible_guard(node
);
1257 * Enumerate <b>sampled_entry_guards</b> smartlist in <b>gs</b>.
1258 * For each <b>entry_guard_t</b> object in smartlist, do the following:
1259 * * Update <b>currently_listed</b> field to reflect if guard is listed
1260 * in guard selection <b>gs</b>.
1261 * * Set <b>unlisted_since_date</b> to approximate UNIX time of
1262 * unlisting if guard is unlisted (randomize within 20% of
1263 * get_remove_unlisted_guards_after_seconds()). Otherwise,
1266 * Require <b>gs</b> to be non-null pointer.
1267 * Return a number of entries updated.
1270 sampled_guards_update_consensus_presence(guard_selection_t
*gs
)
1272 size_t n_changes
= 0;
1276 const time_t unlisted_since_slop
=
1277 get_remove_unlisted_guards_after_seconds() / 5;
1279 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
1280 /* XXXX #20827 check ed ID too */
1281 const int is_listed
= entry_guard_is_listed(gs
, guard
);
1283 if (is_listed
&& ! guard
->currently_listed
) {
1285 guard
->currently_listed
= 1;
1286 guard
->unlisted_since_date
= 0;
1287 log_info(LD_GUARD
, "Sampled guard %s is now listed again.",
1288 entry_guard_describe(guard
));
1289 } else if (!is_listed
&& guard
->currently_listed
) {
1291 guard
->currently_listed
= 0;
1292 guard
->unlisted_since_date
= randomize_time(approx_time(),
1293 unlisted_since_slop
);
1294 log_info(LD_GUARD
, "Sampled guard %s is now unlisted.",
1295 entry_guard_describe(guard
));
1296 } else if (is_listed
&& guard
->currently_listed
) {
1297 log_debug(LD_GUARD
, "Sampled guard %s is still listed.",
1298 entry_guard_describe(guard
));
1300 tor_assert(! is_listed
&& ! guard
->currently_listed
);
1301 log_debug(LD_GUARD
, "Sampled guard %s is still unlisted.",
1302 entry_guard_describe(guard
));
1305 /* Clean up unlisted_since_date, just in case. */
1306 if (guard
->currently_listed
&& guard
->unlisted_since_date
) {
1308 guard
->unlisted_since_date
= 0;
1309 log_warn(LD_BUG
, "Sampled guard %s was listed, but with "
1310 "unlisted_since_date set. Fixing.",
1311 entry_guard_describe(guard
));
1312 } else if (!guard
->currently_listed
&& ! guard
->unlisted_since_date
) {
1314 guard
->unlisted_since_date
= randomize_time(approx_time(),
1315 unlisted_since_slop
);
1316 log_warn(LD_BUG
, "Sampled guard %s was unlisted, but with "
1317 "unlisted_since_date unset. Fixing.",
1318 entry_guard_describe(guard
));
1320 } SMARTLIST_FOREACH_END(guard
);
1326 * Enumerate <b>sampled_entry_guards</b> smartlist in <b>gs</b>.
1327 * For each <b>entry_guard_t</b> object in smartlist, do the following:
1328 * * If <b>currently_listed</b> is false and <b>unlisted_since_date</b>
1329 * is earlier than <b>remove_if_unlisted_since</b> - remove it.
1330 * * Otherwise, check if <b>sampled_on_date</b> is earlier than
1331 * <b>maybe_remove_if_sampled_before</b>.
1332 * * When above condition is correct, remove the guard if:
1333 * * It was never confirmed.
1334 * * It was confirmed before <b>remove_if_confirmed_before</b>.
1336 * Require <b>gs</b> to be non-null pointer.
1337 * Return number of entries deleted.
1340 sampled_guards_prune_obsolete_entries(guard_selection_t
*gs
,
1341 const time_t remove_if_unlisted_since
,
1342 const time_t maybe_remove_if_sampled_before
,
1343 const time_t remove_if_confirmed_before
)
1345 size_t n_changes
= 0;
1349 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
1352 if (guard
->currently_listed
== 0 &&
1353 guard
->unlisted_since_date
< remove_if_unlisted_since
) {
1355 "We have a live consensus, and {IS_LISTED} is false, and
1356 {FIRST_UNLISTED_AT} is over get_remove_unlisted_guards_after_days()
1359 log_info(LD_GUARD
, "Removing sampled guard %s: it has been unlisted "
1360 "for over %d days", entry_guard_describe(guard
),
1361 get_remove_unlisted_guards_after_days());
1363 } else if (guard
->sampled_on_date
< maybe_remove_if_sampled_before
) {
1364 /* We have a live consensus, and {ADDED_ON_DATE} is over
1365 {GUARD_LIFETIME} ago, *and* {CONFIRMED_ON_DATE} is either
1366 "never", or over {GUARD_CONFIRMED_MIN_LIFETIME} ago.
1368 if (guard
->confirmed_on_date
== 0) {
1370 log_info(LD_GUARD
, "Removing sampled guard %s: it was sampled "
1371 "over %d days ago, but never confirmed.",
1372 entry_guard_describe(guard
),
1373 get_guard_lifetime() / 86400);
1374 } else if (guard
->confirmed_on_date
< remove_if_confirmed_before
) {
1376 log_info(LD_GUARD
, "Removing sampled guard %s: it was sampled "
1377 "over %d days ago, and confirmed over %d days ago.",
1378 entry_guard_describe(guard
),
1379 get_guard_lifetime() / 86400,
1380 get_guard_confirmed_min_lifetime() / 86400);
1386 SMARTLIST_DEL_CURRENT(gs
->sampled_entry_guards
, guard
);
1387 remove_guard_from_confirmed_and_primary_lists(gs
, guard
);
1388 entry_guard_free(guard
);
1390 } SMARTLIST_FOREACH_END(guard
);
1396 * Update the status of all sampled guards based on the arrival of a
1397 * new consensus networkstatus document. This will include marking
1398 * some guards as listed or unlisted, and removing expired guards. */
1400 sampled_guards_update_from_consensus(guard_selection_t
*gs
)
1404 // It's important to use a reasonably live consensus here; we want clients
1405 // to bootstrap even if their clock is skewed by more than 2-3 hours.
1406 // But we don't want to make changes based on anything that's really old.
1407 if (reasonably_live_consensus_is_missing(gs
)) {
1408 log_info(LD_GUARD
, "Not updating the sample guard set; we have "
1409 "no reasonably live consensus.");
1412 log_info(LD_GUARD
, "Updating sampled guard status based on received "
1415 /* First: Update listed/unlisted. */
1416 size_t n_changes
= sampled_guards_update_consensus_presence(gs
);
1418 const time_t remove_if_unlisted_since
=
1419 approx_time() - get_remove_unlisted_guards_after_seconds();
1420 const time_t maybe_remove_if_sampled_before
=
1421 approx_time() - get_guard_lifetime();
1422 const time_t remove_if_confirmed_before
=
1423 approx_time() - get_guard_confirmed_min_lifetime();
1425 /* Then: remove the ones that have been junk for too long */
1427 sampled_guards_prune_obsolete_entries(gs
,
1428 remove_if_unlisted_since
,
1429 maybe_remove_if_sampled_before
,
1430 remove_if_confirmed_before
);
1433 gs
->primary_guards_up_to_date
= 0;
1434 entry_guards_update_filtered_sets(gs
);
1435 /* We don't need to rebuild the confirmed list right here -- we may have
1436 * removed confirmed guards above, but we can't have added any new
1439 entry_guards_changed_for_guard_selection(gs
);
1444 * Return true iff <b>node</b> is a Tor relay that we are configured to
1445 * be able to connect to. */
1447 node_passes_guard_filter(const or_options_t
*options
,
1450 /* NOTE: Make sure that this function stays in sync with
1451 * options_transition_affects_entry_guards */
1452 if (routerset_contains_node(options
->ExcludeNodes
, node
))
1455 if (options
->EntryNodes
&&
1456 !routerset_contains_node(options
->EntryNodes
, node
))
1459 if (!fascist_firewall_allows_node(node
, FIREWALL_OR_CONNECTION
, 0))
1462 if (node_is_a_configured_bridge(node
))
1468 /** Helper: Return true iff <b>bridge</b> passes our configuration
1469 * filter-- if it is a relay that we are configured to be able to
1472 bridge_passes_guard_filter(const or_options_t
*options
,
1473 const bridge_info_t
*bridge
)
1479 if (routerset_contains_bridge(options
->ExcludeNodes
, bridge
))
1482 /* Ignore entrynodes */
1483 const tor_addr_port_t
*addrport
= bridge_get_addr_port(bridge
);
1485 if (!fascist_firewall_allows_address_addr(&addrport
->addr
,
1487 FIREWALL_OR_CONNECTION
,
1495 * Return true iff <b>guard</b> is a Tor relay that we are configured to
1496 * be able to connect to, and we haven't disabled it for omission from
1497 * the consensus or path bias issues. */
1499 entry_guard_passes_filter(const or_options_t
*options
, guard_selection_t
*gs
,
1500 entry_guard_t
*guard
)
1502 if (guard
->currently_listed
== 0)
1504 if (guard
->pb
.path_bias_disabled
)
1507 if (gs
->type
== GS_TYPE_BRIDGE
) {
1508 const bridge_info_t
*bridge
= get_bridge_info_for_guard(guard
);
1511 return bridge_passes_guard_filter(options
, bridge
);
1513 const node_t
*node
= node_get_by_id(guard
->identity
);
1515 // This can happen when currently_listed is true, and we're not updating
1516 // it because we don't have a live consensus.
1520 return node_passes_guard_filter(options
, node
);
1524 /** Return true iff <b>guard</b> is in the same family as <b>node</b>.
1527 guard_in_node_family(const entry_guard_t
*guard
, const node_t
*node
)
1529 const node_t
*guard_node
= node_get_by_id(guard
->identity
);
1531 return nodes_in_same_family(guard_node
, node
);
1533 /* If we don't have a node_t for the guard node, we might have
1534 * a bridge_info_t for it. So let's check to see whether the bridge
1535 * address matches has any family issues.
1537 * (Strictly speaking, I believe this check is unnecessary, since we only
1538 * use it to avoid the exit's family when building circuits, and we don't
1539 * build multihop circuits until we have a routerinfo_t for the
1540 * bridge... at which point, we'll also have a node_t for the
1541 * bridge. Nonetheless, it seems wise to include it, in case our
1542 * assumptions change down the road. -nickm.)
1544 if (get_options()->EnforceDistinctSubnets
&& guard
->bridge_addr
) {
1545 tor_addr_t node_addr
;
1546 node_get_addr(node
, &node_addr
);
1547 if (addrs_in_same_network_family(&node_addr
,
1548 &guard
->bridge_addr
->addr
)) {
1556 /* Allocate and return a new exit guard restriction (where <b>exit_id</b> is of
1557 * size DIGEST_LEN) */
1558 STATIC entry_guard_restriction_t
*
1559 guard_create_exit_restriction(const uint8_t *exit_id
)
1561 entry_guard_restriction_t
*rst
= NULL
;
1562 rst
= tor_malloc_zero(sizeof(entry_guard_restriction_t
));
1563 rst
->type
= RST_EXIT_NODE
;
1564 memcpy(rst
->exclude_id
, exit_id
, DIGEST_LEN
);
1568 /** If we have fewer than this many possible usable guards, don't set
1569 * MD-availability-based restrictions: we might blacklist all of them. */
1570 #define MIN_GUARDS_FOR_MD_RESTRICTION 10
1572 /** Return true if we should set md dirserver restrictions. We might not want
1573 * to set those if our guard options are too restricted, since we don't want
1574 * to blacklist all of them. */
1576 should_set_md_dirserver_restriction(void)
1578 const guard_selection_t
*gs
= get_guard_selection_info();
1579 int num_usable_guards
= num_reachable_filtered_guards(gs
, NULL
);
1581 /* Don't set restriction if too few reachable filtered guards. */
1582 if (num_usable_guards
< MIN_GUARDS_FOR_MD_RESTRICTION
) {
1583 log_info(LD_GUARD
, "Not setting md restriction: only %d"
1584 " usable guards.", num_usable_guards
);
1588 /* We have enough usable guards: set MD restriction */
1592 /** Allocate and return an outdated md guard restriction. Return NULL if no
1593 * such restriction is needed. */
1594 STATIC entry_guard_restriction_t
*
1595 guard_create_dirserver_md_restriction(void)
1597 entry_guard_restriction_t
*rst
= NULL
;
1599 if (!should_set_md_dirserver_restriction()) {
1600 log_debug(LD_GUARD
, "Not setting md restriction: too few "
1601 "filtered guards.");
1605 rst
= tor_malloc_zero(sizeof(entry_guard_restriction_t
));
1606 rst
->type
= RST_OUTDATED_MD_DIRSERVER
;
1611 /* Return True if <b>guard</b> obeys the exit restriction <b>rst</b>. */
1613 guard_obeys_exit_restriction(const entry_guard_t
*guard
,
1614 const entry_guard_restriction_t
*rst
)
1616 tor_assert(rst
->type
== RST_EXIT_NODE
);
1618 // Exclude the exit ID and all of its family.
1619 const node_t
*node
= node_get_by_id((const char*)rst
->exclude_id
);
1620 if (node
&& guard_in_node_family(guard
, node
))
1623 return tor_memneq(guard
->identity
, rst
->exclude_id
, DIGEST_LEN
);
1626 /** Return True if <b>guard</b> should be used as a dirserver for fetching
1627 * microdescriptors. */
1629 guard_obeys_md_dirserver_restriction(const entry_guard_t
*guard
)
1631 /* If this guard is an outdated dirserver, don't use it. */
1632 if (microdesc_relay_is_outdated_dirserver(guard
->identity
)) {
1633 log_info(LD_GENERAL
, "Skipping %s dirserver: outdated",
1634 hex_str(guard
->identity
, DIGEST_LEN
));
1638 log_debug(LD_GENERAL
, "%s dirserver obeys md restrictions",
1639 hex_str(guard
->identity
, DIGEST_LEN
));
1645 * Return true iff <b>guard</b> obeys the restrictions defined in <b>rst</b>.
1646 * (If <b>rst</b> is NULL, there are no restrictions.)
1649 entry_guard_obeys_restriction(const entry_guard_t
*guard
,
1650 const entry_guard_restriction_t
*rst
)
1654 return 1; // No restriction? No problem.
1656 if (rst
->type
== RST_EXIT_NODE
) {
1657 return guard_obeys_exit_restriction(guard
, rst
);
1658 } else if (rst
->type
== RST_OUTDATED_MD_DIRSERVER
) {
1659 return guard_obeys_md_dirserver_restriction(guard
);
1662 tor_assert_nonfatal_unreached();
1667 * Update the <b>is_filtered_guard</b> and <b>is_usable_filtered_guard</b>
1668 * flags on <b>guard</b>. */
1670 entry_guard_set_filtered_flags(const or_options_t
*options
,
1671 guard_selection_t
*gs
,
1672 entry_guard_t
*guard
)
1674 unsigned was_filtered
= guard
->is_filtered_guard
;
1675 guard
->is_filtered_guard
= 0;
1676 guard
->is_usable_filtered_guard
= 0;
1678 if (entry_guard_passes_filter(options
, gs
, guard
)) {
1679 guard
->is_filtered_guard
= 1;
1681 if (guard
->is_reachable
!= GUARD_REACHABLE_NO
)
1682 guard
->is_usable_filtered_guard
= 1;
1684 entry_guard_consider_retry(guard
);
1686 log_debug(LD_GUARD
, "Updated sampled guard %s: filtered=%d; "
1687 "reachable_filtered=%d.", entry_guard_describe(guard
),
1688 guard
->is_filtered_guard
, guard
->is_usable_filtered_guard
);
1690 if (!bool_eq(was_filtered
, guard
->is_filtered_guard
)) {
1691 /* This guard might now be primary or nonprimary. */
1692 gs
->primary_guards_up_to_date
= 0;
1697 * Update the <b>is_filtered_guard</b> and <b>is_usable_filtered_guard</b>
1698 * flag on every guard in <b>gs</b>. */
1700 entry_guards_update_filtered_sets(guard_selection_t
*gs
)
1702 const or_options_t
*options
= get_options();
1704 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
1705 entry_guard_set_filtered_flags(options
, gs
, guard
);
1706 } SMARTLIST_FOREACH_END(guard
);
1710 * Return a random guard from the reachable filtered sample guards
1711 * in <b>gs</b>, subject to the exclusion rules listed in <b>flags</b>.
1712 * Return NULL if no such guard can be found.
1714 * Make sure that the sample is big enough, and that all the filter flags
1715 * are set correctly, before calling this function.
1717 * If a restriction is provided in <b>rst</b>, do not return any guards that
1720 STATIC entry_guard_t
*
1721 sample_reachable_filtered_entry_guards(guard_selection_t
*gs
,
1722 const entry_guard_restriction_t
*rst
,
1726 entry_guard_t
*result
= NULL
;
1727 const unsigned exclude_confirmed
= flags
& SAMPLE_EXCLUDE_CONFIRMED
;
1728 const unsigned exclude_primary
= flags
& SAMPLE_EXCLUDE_PRIMARY
;
1729 const unsigned exclude_pending
= flags
& SAMPLE_EXCLUDE_PENDING
;
1730 const unsigned no_update_primary
= flags
& SAMPLE_NO_UPDATE_PRIMARY
;
1731 const unsigned need_descriptor
= flags
& SAMPLE_EXCLUDE_NO_DESCRIPTOR
;
1733 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
1734 entry_guard_consider_retry(guard
);
1735 } SMARTLIST_FOREACH_END(guard
);
1737 const int n_reachable_filtered
= num_reachable_filtered_guards(gs
, rst
);
1739 log_info(LD_GUARD
, "Trying to sample a reachable guard: We know of %d "
1740 "in the USABLE_FILTERED set.", n_reachable_filtered
);
1742 const int min_filtered_sample
= get_min_filtered_sample_size();
1743 if (n_reachable_filtered
< min_filtered_sample
) {
1744 log_info(LD_GUARD
, " (That isn't enough. Trying to expand the sample.)");
1745 entry_guards_expand_sample(gs
);
1748 if (exclude_primary
&& !gs
->primary_guards_up_to_date
&& !no_update_primary
)
1749 entry_guards_update_primary(gs
);
1751 /* Build the set of reachable filtered guards. */
1752 smartlist_t
*reachable_filtered_sample
= smartlist_new();
1753 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
1754 entry_guard_consider_retry(guard
);// redundant, but cheap.
1755 if (! entry_guard_obeys_restriction(guard
, rst
))
1757 if (! guard
->is_usable_filtered_guard
)
1759 if (exclude_confirmed
&& guard
->confirmed_idx
>= 0)
1761 if (exclude_primary
&& guard
->is_primary
)
1763 if (exclude_pending
&& guard
->is_pending
)
1765 if (need_descriptor
&& !guard_has_descriptor(guard
))
1767 smartlist_add(reachable_filtered_sample
, guard
);
1768 } SMARTLIST_FOREACH_END(guard
);
1770 log_info(LD_GUARD
, " (After filters [%x], we have %d guards to consider.)",
1771 flags
, smartlist_len(reachable_filtered_sample
));
1773 if (smartlist_len(reachable_filtered_sample
)) {
1774 result
= smartlist_choose(reachable_filtered_sample
);
1775 log_info(LD_GUARD
, " (Selected %s.)",
1776 result
? entry_guard_describe(result
) : "<null>");
1778 smartlist_free(reachable_filtered_sample
);
1784 * Helper: compare two entry_guard_t by their confirmed_idx values.
1785 * Used to sort the confirmed list.
1788 compare_guards_by_confirmed_idx(const void **a_
, const void **b_
)
1790 const entry_guard_t
*a
= *a_
, *b
= *b_
;
1791 if (a
->confirmed_idx
< b
->confirmed_idx
)
1793 else if (a
->confirmed_idx
> b
->confirmed_idx
)
1800 * Find the confirmed guards from among the sampled guards in <b>gs</b>,
1801 * and put them in confirmed_entry_guards in the correct
1802 * order. Recalculate their indices.
1805 entry_guards_update_confirmed(guard_selection_t
*gs
)
1807 smartlist_clear(gs
->confirmed_entry_guards
);
1808 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
1809 if (guard
->confirmed_idx
>= 0)
1810 smartlist_add(gs
->confirmed_entry_guards
, guard
);
1811 } SMARTLIST_FOREACH_END(guard
);
1813 smartlist_sort(gs
->confirmed_entry_guards
, compare_guards_by_confirmed_idx
);
1815 int any_changed
= 0;
1816 SMARTLIST_FOREACH_BEGIN(gs
->confirmed_entry_guards
, entry_guard_t
*, guard
) {
1817 if (guard
->confirmed_idx
!= guard_sl_idx
) {
1819 guard
->confirmed_idx
= guard_sl_idx
;
1821 } SMARTLIST_FOREACH_END(guard
);
1823 gs
->next_confirmed_idx
= smartlist_len(gs
->confirmed_entry_guards
);
1826 entry_guards_changed_for_guard_selection(gs
);
1831 * Mark <b>guard</b> as a confirmed guard -- that is, one that we have
1832 * connected to, and intend to use again.
1835 make_guard_confirmed(guard_selection_t
*gs
, entry_guard_t
*guard
)
1837 if (BUG(guard
->confirmed_on_date
&& guard
->confirmed_idx
>= 0))
1838 return; // LCOV_EXCL_LINE
1840 if (BUG(smartlist_contains(gs
->confirmed_entry_guards
, guard
)))
1841 return; // LCOV_EXCL_LINE
1843 const int GUARD_LIFETIME
= get_guard_lifetime();
1844 guard
->confirmed_on_date
= randomize_time(approx_time(), GUARD_LIFETIME
/10);
1846 log_info(LD_GUARD
, "Marking %s as a confirmed guard (index %d)",
1847 entry_guard_describe(guard
),
1848 gs
->next_confirmed_idx
);
1850 guard
->confirmed_idx
= gs
->next_confirmed_idx
++;
1851 smartlist_add(gs
->confirmed_entry_guards
, guard
);
1853 // This confirmed guard might kick something else out of the primary
1855 gs
->primary_guards_up_to_date
= 0;
1857 entry_guards_changed_for_guard_selection(gs
);
1861 * Recalculate the list of primary guards (the ones we'd prefer to use) from
1862 * the filtered sample and the confirmed list.
1865 entry_guards_update_primary(guard_selection_t
*gs
)
1869 // prevent recursion. Recursion is potentially very bad here.
1870 static int running
= 0;
1871 tor_assert(!running
);
1874 const int N_PRIMARY_GUARDS
= get_n_primary_guards();
1876 smartlist_t
*new_primary_guards
= smartlist_new();
1877 smartlist_t
*old_primary_guards
= smartlist_new();
1878 smartlist_add_all(old_primary_guards
, gs
->primary_entry_guards
);
1880 /* Set this flag now, to prevent the calls below from recursing. */
1881 gs
->primary_guards_up_to_date
= 1;
1883 /* First, can we fill it up with confirmed guards? */
1884 SMARTLIST_FOREACH_BEGIN(gs
->confirmed_entry_guards
, entry_guard_t
*, guard
) {
1885 if (smartlist_len(new_primary_guards
) >= N_PRIMARY_GUARDS
)
1887 if (! guard
->is_filtered_guard
)
1889 guard
->is_primary
= 1;
1890 smartlist_add(new_primary_guards
, guard
);
1891 } SMARTLIST_FOREACH_END(guard
);
1893 SMARTLIST_FOREACH_BEGIN(old_primary_guards
, entry_guard_t
*, guard
) {
1894 /* Can we keep any older primary guards? First remove all the ones
1895 * that we already kept. */
1896 if (smartlist_contains(new_primary_guards
, guard
)) {
1897 SMARTLIST_DEL_CURRENT_KEEPORDER(old_primary_guards
, guard
);
1901 /* Now add any that are still good. */
1902 if (smartlist_len(new_primary_guards
) < N_PRIMARY_GUARDS
&&
1903 guard
->is_filtered_guard
) {
1904 guard
->is_primary
= 1;
1905 smartlist_add(new_primary_guards
, guard
);
1906 SMARTLIST_DEL_CURRENT_KEEPORDER(old_primary_guards
, guard
);
1908 /* Mark the remaining previous primary guards as non-primary */
1909 guard
->is_primary
= 0;
1911 } SMARTLIST_FOREACH_END(guard
);
1913 /* Finally, fill out the list with sampled guards. */
1914 while (smartlist_len(new_primary_guards
) < N_PRIMARY_GUARDS
) {
1915 entry_guard_t
*guard
= sample_reachable_filtered_entry_guards(gs
, NULL
,
1916 SAMPLE_EXCLUDE_CONFIRMED
|
1917 SAMPLE_EXCLUDE_PRIMARY
|
1918 SAMPLE_NO_UPDATE_PRIMARY
);
1921 guard
->is_primary
= 1;
1922 smartlist_add(new_primary_guards
, guard
);
1927 SMARTLIST_FOREACH(gs
->sampled_entry_guards
, entry_guard_t
*, guard
, {
1928 tor_assert_nonfatal(
1929 bool_eq(guard
->is_primary
,
1930 smartlist_contains(new_primary_guards
, guard
)));
1934 const int any_change
= !smartlist_ptrs_eq(gs
->primary_entry_guards
,
1935 new_primary_guards
);
1937 log_info(LD_GUARD
, "Primary entry guards have changed. "
1938 "New primary guard list is: ");
1939 int n
= smartlist_len(new_primary_guards
);
1940 SMARTLIST_FOREACH_BEGIN(new_primary_guards
, entry_guard_t
*, g
) {
1941 log_info(LD_GUARD
, " %d/%d: %s%s%s",
1942 g_sl_idx
+1, n
, entry_guard_describe(g
),
1943 g
->confirmed_idx
>= 0 ? " (confirmed)" : "",
1944 g
->is_filtered_guard
? "" : " (excluded by filter)");
1945 } SMARTLIST_FOREACH_END(g
);
1948 smartlist_free(old_primary_guards
);
1949 smartlist_free(gs
->primary_entry_guards
);
1950 gs
->primary_entry_guards
= new_primary_guards
;
1951 gs
->primary_guards_up_to_date
= 1;
1956 * Return the number of seconds after the last attempt at which we should
1957 * retry a guard that has been failing since <b>failing_since</b>.
1960 get_retry_schedule(time_t failing_since
, time_t now
,
1963 const unsigned SIX_HOURS
= 6 * 3600;
1964 const unsigned FOUR_DAYS
= 4 * 86400;
1965 const unsigned SEVEN_DAYS
= 7 * 86400;
1968 if (now
> failing_since
) {
1969 tdiff
= now
- failing_since
;
1975 time_t maximum
; int primary_delay
; int nonprimary_delay
;
1977 { SIX_HOURS
, 10*60, 1*60*60 },
1978 { FOUR_DAYS
, 90*60, 4*60*60 },
1979 { SEVEN_DAYS
, 4*60*60, 18*60*60 },
1980 { TIME_MAX
, 9*60*60, 36*60*60 }
1984 for (i
= 0; i
< ARRAY_LENGTH(delays
); ++i
) {
1985 if (tdiff
<= delays
[i
].maximum
) {
1986 return is_primary
? delays
[i
].primary_delay
: delays
[i
].nonprimary_delay
;
1989 /* LCOV_EXCL_START -- can't reach, since delays ends with TIME_MAX. */
1990 tor_assert_nonfatal_unreached();
1992 /* LCOV_EXCL_STOP */
1996 * If <b>guard</b> is unreachable, consider whether enough time has passed
1997 * to consider it maybe-reachable again.
2000 entry_guard_consider_retry(entry_guard_t
*guard
)
2002 if (guard
->is_reachable
!= GUARD_REACHABLE_NO
)
2003 return; /* No retry needed. */
2005 const time_t now
= approx_time();
2007 get_retry_schedule(guard
->failing_since
, now
, guard
->is_primary
);
2008 const time_t last_attempt
= guard
->last_tried_to_connect
;
2010 if (BUG(last_attempt
== 0) ||
2011 now
>= last_attempt
+ delay
) {
2012 /* We should mark this retriable. */
2013 char tbuf
[ISO_TIME_LEN
+1];
2014 format_local_iso_time(tbuf
, last_attempt
);
2015 log_info(LD_GUARD
, "Marked %s%sguard %s for possible retry, since we "
2016 "haven't tried to use it since %s.",
2017 guard
->is_primary
?"primary ":"",
2018 guard
->confirmed_idx
>=0?"confirmed ":"",
2019 entry_guard_describe(guard
),
2022 guard
->is_reachable
= GUARD_REACHABLE_MAYBE
;
2023 if (guard
->is_filtered_guard
)
2024 guard
->is_usable_filtered_guard
= 1;
2028 /** Tell the entry guards subsystem that we have confirmed that as of
2029 * just now, we're on the internet. */
2031 entry_guards_note_internet_connectivity(guard_selection_t
*gs
)
2033 gs
->last_time_on_internet
= approx_time();
2037 * Pick a primary guard for use with a circuit, if available. Update the
2038 * <b>last_tried_to_connect</b> time and the <b>is_pending</b> fields of the
2039 * guard as appropriate. Set <b>state_out</b> to the new guard-state
2042 static entry_guard_t
*
2043 select_primary_guard_for_circuit(guard_selection_t
*gs
,
2044 guard_usage_t usage
,
2045 const entry_guard_restriction_t
*rst
,
2046 unsigned *state_out
)
2048 const int need_descriptor
= (usage
== GUARD_USAGE_TRAFFIC
);
2049 entry_guard_t
*chosen_guard
= NULL
;
2051 int num_entry_guards
= get_n_primary_guards_to_use(usage
);
2052 smartlist_t
*usable_primary_guards
= smartlist_new();
2054 SMARTLIST_FOREACH_BEGIN(gs
->primary_entry_guards
, entry_guard_t
*, guard
) {
2055 entry_guard_consider_retry(guard
);
2056 if (! entry_guard_obeys_restriction(guard
, rst
))
2058 if (guard
->is_reachable
!= GUARD_REACHABLE_NO
) {
2059 if (need_descriptor
&& !guard_has_descriptor(guard
)) {
2062 *state_out
= GUARD_CIRC_STATE_USABLE_ON_COMPLETION
;
2063 guard
->last_tried_to_connect
= approx_time();
2064 smartlist_add(usable_primary_guards
, guard
);
2065 if (smartlist_len(usable_primary_guards
) >= num_entry_guards
)
2068 } SMARTLIST_FOREACH_END(guard
);
2070 if (smartlist_len(usable_primary_guards
)) {
2071 chosen_guard
= smartlist_choose(usable_primary_guards
);
2072 smartlist_free(usable_primary_guards
);
2073 log_info(LD_GUARD
, "Selected primary guard %s for circuit.",
2074 entry_guard_describe(chosen_guard
));
2077 smartlist_free(usable_primary_guards
);
2078 return chosen_guard
;
2082 * For use with a circuit, pick a non-pending running filtered confirmed guard,
2083 * if one is available. Update the <b>last_tried_to_connect</b> time and the
2084 * <b>is_pending</b> fields of the guard as appropriate. Set <b>state_out</b>
2085 * to the new guard-state of the circuit.
2087 static entry_guard_t
*
2088 select_confirmed_guard_for_circuit(guard_selection_t
*gs
,
2089 guard_usage_t usage
,
2090 const entry_guard_restriction_t
*rst
,
2091 unsigned *state_out
)
2093 const int need_descriptor
= (usage
== GUARD_USAGE_TRAFFIC
);
2095 SMARTLIST_FOREACH_BEGIN(gs
->confirmed_entry_guards
, entry_guard_t
*, guard
) {
2096 if (guard
->is_primary
)
2097 continue; /* we already considered this one. */
2098 if (! entry_guard_obeys_restriction(guard
, rst
))
2100 entry_guard_consider_retry(guard
);
2101 if (guard
->is_usable_filtered_guard
&& ! guard
->is_pending
) {
2102 if (need_descriptor
&& !guard_has_descriptor(guard
))
2103 continue; /* not a bug */
2104 guard
->is_pending
= 1;
2105 guard
->last_tried_to_connect
= approx_time();
2106 *state_out
= GUARD_CIRC_STATE_USABLE_IF_NO_BETTER_GUARD
;
2107 log_info(LD_GUARD
, "No primary guards available. Selected confirmed "
2108 "guard %s for circuit. Will try other guards before using "
2110 entry_guard_describe(guard
));
2113 } SMARTLIST_FOREACH_END(guard
);
2119 * For use with a circuit, pick a confirmed usable filtered guard
2120 * at random. Update the <b>last_tried_to_connect</b> time and the
2121 * <b>is_pending</b> fields of the guard as appropriate. Set <b>state_out</b>
2122 * to the new guard-state of the circuit.
2124 static entry_guard_t
*
2125 select_filtered_guard_for_circuit(guard_selection_t
*gs
,
2126 guard_usage_t usage
,
2127 const entry_guard_restriction_t
*rst
,
2128 unsigned *state_out
)
2130 const int need_descriptor
= (usage
== GUARD_USAGE_TRAFFIC
);
2131 entry_guard_t
*chosen_guard
= NULL
;
2133 if (need_descriptor
)
2134 flags
|= SAMPLE_EXCLUDE_NO_DESCRIPTOR
;
2135 chosen_guard
= sample_reachable_filtered_entry_guards(gs
,
2137 SAMPLE_EXCLUDE_CONFIRMED
|
2138 SAMPLE_EXCLUDE_PRIMARY
|
2139 SAMPLE_EXCLUDE_PENDING
|
2141 if (!chosen_guard
) {
2145 chosen_guard
->is_pending
= 1;
2146 chosen_guard
->last_tried_to_connect
= approx_time();
2147 *state_out
= GUARD_CIRC_STATE_USABLE_IF_NO_BETTER_GUARD
;
2148 log_info(LD_GUARD
, "No primary or confirmed guards available. Selected "
2149 "random guard %s for circuit. Will try other guards before "
2150 "using this circuit.",
2151 entry_guard_describe(chosen_guard
));
2152 return chosen_guard
;
2156 * Get a guard for use with a circuit. Prefer to pick a running primary
2157 * guard; then a non-pending running filtered confirmed guard; then a
2158 * non-pending runnable filtered guard. Update the
2159 * <b>last_tried_to_connect</b> time and the <b>is_pending</b> fields of the
2160 * guard as appropriate. Set <b>state_out</b> to the new guard-state
2163 STATIC entry_guard_t
*
2164 select_entry_guard_for_circuit(guard_selection_t
*gs
,
2165 guard_usage_t usage
,
2166 const entry_guard_restriction_t
*rst
,
2167 unsigned *state_out
)
2169 entry_guard_t
*chosen_guard
= NULL
;
2171 tor_assert(state_out
);
2173 if (!gs
->primary_guards_up_to_date
)
2174 entry_guards_update_primary(gs
);
2176 /* "If any entry in PRIMARY_GUARDS has {is_reachable} status of
2177 <maybe> or <yes>, return the first such guard." */
2178 chosen_guard
= select_primary_guard_for_circuit(gs
, usage
, rst
, state_out
);
2180 return chosen_guard
;
2182 /* "Otherwise, if the ordered intersection of {CONFIRMED_GUARDS}
2183 and {USABLE_FILTERED_GUARDS} is nonempty, return the first
2184 entry in that intersection that has {is_pending} set to
2186 chosen_guard
= select_confirmed_guard_for_circuit(gs
, usage
, rst
, state_out
);
2188 return chosen_guard
;
2190 /* "Otherwise, if there is no such entry, select a member at
2191 random from {USABLE_FILTERED_GUARDS}." */
2192 chosen_guard
= select_filtered_guard_for_circuit(gs
, usage
, rst
, state_out
);
2194 if (chosen_guard
== NULL
) {
2195 log_info(LD_GUARD
, "Absolutely no sampled guards were available. "
2196 "Marking all guards for retry and starting from top again.");
2197 mark_all_guards_maybe_reachable(gs
);
2201 return chosen_guard
;
2205 * Note that we failed to connect to or build circuits through <b>guard</b>.
2206 * Use with a guard returned by select_entry_guard_for_circuit().
2209 entry_guards_note_guard_failure(guard_selection_t
*gs
,
2210 entry_guard_t
*guard
)
2214 guard
->is_reachable
= GUARD_REACHABLE_NO
;
2215 guard
->is_usable_filtered_guard
= 0;
2217 guard
->is_pending
= 0;
2218 if (guard
->failing_since
== 0)
2219 guard
->failing_since
= approx_time();
2221 log_info(LD_GUARD
, "Recorded failure for %s%sguard %s",
2222 guard
->is_primary
?"primary ":"",
2223 guard
->confirmed_idx
>=0?"confirmed ":"",
2224 entry_guard_describe(guard
));
2228 * Note that we successfully connected to, and built a circuit through
2229 * <b>guard</b>. Given the old guard-state of the circuit in <b>old_state</b>,
2230 * return the new guard-state of the circuit.
2232 * Be aware: the circuit is only usable when its guard-state becomes
2233 * GUARD_CIRC_STATE_COMPLETE.
2236 entry_guards_note_guard_success(guard_selection_t
*gs
,
2237 entry_guard_t
*guard
,
2242 /* Save this, since we're about to overwrite it. */
2243 const time_t last_time_on_internet
= gs
->last_time_on_internet
;
2244 gs
->last_time_on_internet
= approx_time();
2246 guard
->is_reachable
= GUARD_REACHABLE_YES
;
2247 guard
->failing_since
= 0;
2248 guard
->is_pending
= 0;
2249 if (guard
->is_filtered_guard
)
2250 guard
->is_usable_filtered_guard
= 1;
2252 if (guard
->confirmed_idx
< 0) {
2253 make_guard_confirmed(gs
, guard
);
2254 if (!gs
->primary_guards_up_to_date
)
2255 entry_guards_update_primary(gs
);
2259 switch (old_state
) {
2260 case GUARD_CIRC_STATE_COMPLETE
:
2261 case GUARD_CIRC_STATE_USABLE_ON_COMPLETION
:
2262 new_state
= GUARD_CIRC_STATE_COMPLETE
;
2265 tor_assert_nonfatal_unreached();
2267 case GUARD_CIRC_STATE_USABLE_IF_NO_BETTER_GUARD
:
2268 if (guard
->is_primary
) {
2269 /* XXXX #20832 -- I don't actually like this logic. It seems to make
2270 * us a little more susceptible to evil-ISP attacks. The mitigations
2271 * I'm thinking of, however, aren't local to this point, so I'll leave
2273 /* This guard may have become primary by virtue of being confirmed.
2274 * If so, the circuit for it is now complete.
2276 new_state
= GUARD_CIRC_STATE_COMPLETE
;
2278 new_state
= GUARD_CIRC_STATE_WAITING_FOR_BETTER_GUARD
;
2283 if (! guard
->is_primary
) {
2284 if (last_time_on_internet
+ get_internet_likely_down_interval()
2286 mark_primary_guards_maybe_reachable(gs
);
2290 log_info(LD_GUARD
, "Recorded success for %s%sguard %s",
2291 guard
->is_primary
?"primary ":"",
2292 guard
->confirmed_idx
>=0?"confirmed ":"",
2293 entry_guard_describe(guard
));
2299 * Helper: Return true iff <b>a</b> has higher priority than <b>b</b>.
2302 entry_guard_has_higher_priority(entry_guard_t
*a
, entry_guard_t
*b
)
2308 /* Confirmed is always better than unconfirmed; lower index better
2310 if (a
->confirmed_idx
< 0) {
2311 if (b
->confirmed_idx
>= 0)
2314 if (b
->confirmed_idx
< 0)
2317 /* Lower confirmed_idx is better than higher. */
2318 return (a
->confirmed_idx
< b
->confirmed_idx
);
2321 /* If we reach this point, both are unconfirmed. If one is pending, it
2322 * has higher priority. */
2323 if (a
->is_pending
) {
2324 if (! b
->is_pending
)
2327 /* Both are pending: earlier last_tried_connect wins. */
2328 return a
->last_tried_to_connect
< b
->last_tried_to_connect
;
2333 /* Neither is pending: priorities are equal. */
2338 /** Release all storage held in <b>restriction</b> */
2340 entry_guard_restriction_free_(entry_guard_restriction_t
*rst
)
2346 * Release all storage held in <b>state</b>.
2349 circuit_guard_state_free_(circuit_guard_state_t
*state
)
2353 entry_guard_restriction_free(state
->restrictions
);
2354 entry_guard_handle_free(state
->guard
);
2358 /** Allocate and return a new circuit_guard_state_t to track the result
2359 * of using <b>guard</b> for a given operation. */
2360 MOCK_IMPL(STATIC circuit_guard_state_t
*,
2361 circuit_guard_state_new
,(entry_guard_t
*guard
, unsigned state
,
2362 entry_guard_restriction_t
*rst
))
2364 circuit_guard_state_t
*result
;
2366 result
= tor_malloc_zero(sizeof(circuit_guard_state_t
));
2367 result
->guard
= entry_guard_handle_new(guard
);
2368 result
->state
= state
;
2369 result
->state_set_at
= approx_time();
2370 result
->restrictions
= rst
;
2376 * Pick a suitable entry guard for a circuit in, and place that guard
2377 * in *<b>chosen_node_out</b>. Set *<b>guard_state_out</b> to an opaque
2378 * state object that will record whether the circuit is ready to be used
2379 * or not. Return 0 on success; on failure, return -1.
2381 * If a restriction is provided in <b>rst</b>, do not return any guards that
2382 * violate it, and remember that restriction in <b>guard_state_out</b> for
2383 * later use. (Takes ownership of the <b>rst</b> object.)
2386 entry_guard_pick_for_circuit(guard_selection_t
*gs
,
2387 guard_usage_t usage
,
2388 entry_guard_restriction_t
*rst
,
2389 const node_t
**chosen_node_out
,
2390 circuit_guard_state_t
**guard_state_out
)
2393 tor_assert(chosen_node_out
);
2394 tor_assert(guard_state_out
);
2395 *chosen_node_out
= NULL
;
2396 *guard_state_out
= NULL
;
2399 entry_guard_t
*guard
=
2400 select_entry_guard_for_circuit(gs
, usage
, rst
, &state
);
2403 if (BUG(state
== 0))
2405 const node_t
*node
= node_get_by_id(guard
->identity
);
2406 // XXXX #20827 check Ed ID.
2409 if (BUG(usage
!= GUARD_USAGE_DIRGUARD
&&
2410 !node_has_preferred_descriptor(node
, 1)))
2413 *chosen_node_out
= node
;
2414 *guard_state_out
= circuit_guard_state_new(guard
, state
, rst
);
2418 entry_guard_restriction_free(rst
);
2423 * Called by the circuit building module when a circuit has succeeded: informs
2424 * the guards code that the guard in *<b>guard_state_p</b> is working, and
2425 * advances the state of the guard module. On a GUARD_USABLE_NEVER return
2426 * value, the circuit is broken and should not be used. On a GUARD_USABLE_NOW
2427 * return value, the circuit is ready to use. On a GUARD_MAYBE_USABLE_LATER
2428 * return value, the circuit should not be used until we find out whether
2429 * preferred guards will work for us.
2432 entry_guard_succeeded(circuit_guard_state_t
**guard_state_p
)
2434 if (BUG(*guard_state_p
== NULL
))
2435 return GUARD_USABLE_NEVER
;
2437 entry_guard_t
*guard
= entry_guard_handle_get((*guard_state_p
)->guard
);
2438 if (! guard
|| BUG(guard
->in_selection
== NULL
))
2439 return GUARD_USABLE_NEVER
;
2442 entry_guards_note_guard_success(guard
->in_selection
, guard
,
2443 (*guard_state_p
)->state
);
2445 (*guard_state_p
)->state
= newstate
;
2446 (*guard_state_p
)->state_set_at
= approx_time();
2448 if (newstate
== GUARD_CIRC_STATE_COMPLETE
) {
2449 return GUARD_USABLE_NOW
;
2451 return GUARD_MAYBE_USABLE_LATER
;
2455 /** Cancel the selection of *<b>guard_state_p</b> without declaring
2456 * success or failure. It is safe to call this function if success or
2457 * failure _has_ already been declared. */
2459 entry_guard_cancel(circuit_guard_state_t
**guard_state_p
)
2461 if (BUG(*guard_state_p
== NULL
))
2463 entry_guard_t
*guard
= entry_guard_handle_get((*guard_state_p
)->guard
);
2467 /* XXXX prop271 -- last_tried_to_connect_at will be erroneous here, but this
2468 * function will only get called in "bug" cases anyway. */
2469 guard
->is_pending
= 0;
2470 circuit_guard_state_free(*guard_state_p
);
2471 *guard_state_p
= NULL
;
2475 * Called by the circuit building module when a circuit has failed:
2476 * informs the guards code that the guard in *<b>guard_state_p</b> is
2477 * not working, and advances the state of the guard module.
2480 entry_guard_failed(circuit_guard_state_t
**guard_state_p
)
2482 if (BUG(*guard_state_p
== NULL
))
2485 entry_guard_t
*guard
= entry_guard_handle_get((*guard_state_p
)->guard
);
2486 if (! guard
|| BUG(guard
->in_selection
== NULL
))
2489 entry_guards_note_guard_failure(guard
->in_selection
, guard
);
2491 (*guard_state_p
)->state
= GUARD_CIRC_STATE_DEAD
;
2492 (*guard_state_p
)->state_set_at
= approx_time();
2496 * Run the entry_guard_failed() function on every circuit that is
2497 * pending on <b>chan</b>.
2500 entry_guard_chan_failed(channel_t
*chan
)
2505 smartlist_t
*pending
= smartlist_new();
2506 circuit_get_all_pending_on_channel(pending
, chan
);
2507 SMARTLIST_FOREACH_BEGIN(pending
, circuit_t
*, circ
) {
2508 if (!CIRCUIT_IS_ORIGIN(circ
))
2511 origin_circuit_t
*origin_circ
= TO_ORIGIN_CIRCUIT(circ
);
2512 if (origin_circ
->guard_state
) {
2513 /* We might have no guard state if we didn't use a guard on this
2514 * circuit (eg it's for a fallback directory). */
2515 entry_guard_failed(&origin_circ
->guard_state
);
2517 } SMARTLIST_FOREACH_END(circ
);
2518 smartlist_free(pending
);
2522 * Return true iff every primary guard in <b>gs</b> is believed to
2526 entry_guards_all_primary_guards_are_down(guard_selection_t
*gs
)
2529 if (!gs
->primary_guards_up_to_date
)
2530 entry_guards_update_primary(gs
);
2531 SMARTLIST_FOREACH_BEGIN(gs
->primary_entry_guards
, entry_guard_t
*, guard
) {
2532 entry_guard_consider_retry(guard
);
2533 if (guard
->is_reachable
!= GUARD_REACHABLE_NO
)
2535 } SMARTLIST_FOREACH_END(guard
);
2539 /** Wrapper for entry_guard_has_higher_priority that compares the
2540 * guard-priorities of a pair of circuits. Return 1 if <b>a</b> has higher
2541 * priority than <b>b</b>.
2543 * If a restriction is provided in <b>rst</b>, then do not consider
2544 * <b>a</b> to have higher priority if it violates the restriction.
2547 circ_state_has_higher_priority(origin_circuit_t
*a
,
2548 const entry_guard_restriction_t
*rst
,
2549 origin_circuit_t
*b
)
2551 circuit_guard_state_t
*state_a
= origin_circuit_get_guard_state(a
);
2552 circuit_guard_state_t
*state_b
= origin_circuit_get_guard_state(b
);
2554 tor_assert(state_a
);
2555 tor_assert(state_b
);
2557 entry_guard_t
*guard_a
= entry_guard_handle_get(state_a
->guard
);
2558 entry_guard_t
*guard_b
= entry_guard_handle_get(state_b
->guard
);
2561 /* Unknown guard -- never higher priority. */
2563 } else if (! guard_b
) {
2564 /* Known guard -- higher priority than any unknown guard. */
2566 } else if (! entry_guard_obeys_restriction(guard_a
, rst
)) {
2567 /* Restriction violated; guard_a cannot have higher priority. */
2570 /* Both known -- compare.*/
2571 return entry_guard_has_higher_priority(guard_a
, guard_b
);
2576 * Look at all of the origin_circuit_t * objects in <b>all_circuits_in</b>,
2577 * and see if any of them that were previously not ready to use for
2578 * guard-related reasons are now ready to use. Place those circuits
2579 * in <b>newly_complete_out</b>, and mark them COMPLETE.
2581 * Return 1 if we upgraded any circuits, and 0 otherwise.
2584 entry_guards_upgrade_waiting_circuits(guard_selection_t
*gs
,
2585 const smartlist_t
*all_circuits_in
,
2586 smartlist_t
*newly_complete_out
)
2589 tor_assert(all_circuits_in
);
2590 tor_assert(newly_complete_out
);
2592 if (! entry_guards_all_primary_guards_are_down(gs
)) {
2593 /* We only upgrade a waiting circuit if the primary guards are all
2595 log_debug(LD_GUARD
, "Considered upgrading guard-stalled circuits, "
2596 "but not all primary guards were definitely down.");
2602 int n_complete_blocking
= 0;
2603 origin_circuit_t
*best_waiting_circuit
= NULL
;
2604 smartlist_t
*all_circuits
= smartlist_new();
2605 SMARTLIST_FOREACH_BEGIN(all_circuits_in
, origin_circuit_t
*, circ
) {
2606 // We filter out circuits that aren't ours, or which we can't
2608 circuit_guard_state_t
*state
= origin_circuit_get_guard_state(circ
);
2611 entry_guard_t
*guard
= entry_guard_handle_get(state
->guard
);
2612 if (!guard
|| guard
->in_selection
!= gs
)
2614 if (TO_CIRCUIT(circ
)->marked_for_close
) {
2615 /* Don't consider any marked for close circuits. */
2619 smartlist_add(all_circuits
, circ
);
2620 } SMARTLIST_FOREACH_END(circ
);
2622 SMARTLIST_FOREACH_BEGIN(all_circuits
, origin_circuit_t
*, circ
) {
2623 circuit_guard_state_t
*state
= origin_circuit_get_guard_state(circ
);
2624 if (BUG(state
== NULL
))
2627 if (state
->state
== GUARD_CIRC_STATE_WAITING_FOR_BETTER_GUARD
) {
2629 if (! best_waiting_circuit
||
2630 circ_state_has_higher_priority(circ
, NULL
, best_waiting_circuit
)) {
2631 best_waiting_circuit
= circ
;
2634 } SMARTLIST_FOREACH_END(circ
);
2636 if (! best_waiting_circuit
) {
2637 log_debug(LD_GUARD
, "Considered upgrading guard-stalled circuits, "
2638 "but didn't find any.");
2642 /* We'll need to keep track of what restrictions were used when picking this
2643 * circuit, so that we don't allow any circuit without those restrictions to
2645 const entry_guard_restriction_t
*rst_on_best_waiting
=
2646 origin_circuit_get_guard_state(best_waiting_circuit
)->restrictions
;
2648 /* First look at the complete circuits: Do any block this circuit? */
2649 SMARTLIST_FOREACH_BEGIN(all_circuits
, origin_circuit_t
*, circ
) {
2650 /* "C2 "blocks" C1 if:
2651 * C2 obeys all the restrictions that C1 had to obey, AND
2652 * C2 has higher priority than C1, AND
2653 * Either C2 is <complete>, or C2 is <waiting_for_better_guard>,
2654 or C2 has been <usable_if_no_better_guard> for no more than
2655 {NONPRIMARY_GUARD_CONNECT_TIMEOUT} seconds."
2657 circuit_guard_state_t
*state
= origin_circuit_get_guard_state(circ
);
2658 if BUG((state
== NULL
))
2660 if (state
->state
!= GUARD_CIRC_STATE_COMPLETE
)
2663 if (circ_state_has_higher_priority(circ
, rst_on_best_waiting
,
2664 best_waiting_circuit
))
2665 ++n_complete_blocking
;
2666 } SMARTLIST_FOREACH_END(circ
);
2668 if (n_complete_blocking
) {
2669 log_debug(LD_GUARD
, "Considered upgrading guard-stalled circuits: found "
2670 "%d complete and %d guard-stalled. At least one complete "
2671 "circuit had higher priority, so not upgrading.",
2672 n_complete
, n_waiting
);
2676 /* " * If any circuit C1 is <waiting_for_better_guard>, AND:
2677 * All primary guards have reachable status of <no>.
2678 * There is no circuit C2 that "blocks" C1.
2679 Then, upgrade C1 to <complete>.""
2681 int n_blockers_found
= 0;
2682 const time_t state_set_at_cutoff
=
2683 approx_time() - get_nonprimary_guard_connect_timeout();
2684 SMARTLIST_FOREACH_BEGIN(all_circuits
, origin_circuit_t
*, circ
) {
2685 circuit_guard_state_t
*state
= origin_circuit_get_guard_state(circ
);
2686 if (BUG(state
== NULL
))
2688 if (state
->state
!= GUARD_CIRC_STATE_USABLE_IF_NO_BETTER_GUARD
)
2690 if (state
->state_set_at
<= state_set_at_cutoff
)
2692 if (circ_state_has_higher_priority(circ
, rst_on_best_waiting
,
2693 best_waiting_circuit
))
2695 } SMARTLIST_FOREACH_END(circ
);
2697 if (n_blockers_found
) {
2698 log_debug(LD_GUARD
, "Considered upgrading guard-stalled circuits: found "
2699 "%d guard-stalled, but %d pending circuit(s) had higher "
2700 "guard priority, so not upgrading.",
2701 n_waiting
, n_blockers_found
);
2705 /* Okay. We have a best waiting circuit, and we aren't waiting for
2706 anything better. Add all circuits with that priority to the
2707 list, and call them COMPLETE. */
2708 int n_succeeded
= 0;
2709 SMARTLIST_FOREACH_BEGIN(all_circuits
, origin_circuit_t
*, circ
) {
2710 circuit_guard_state_t
*state
= origin_circuit_get_guard_state(circ
);
2711 if (BUG(state
== NULL
))
2713 if (circ
!= best_waiting_circuit
&& rst_on_best_waiting
) {
2714 /* Can't upgrade other circ with same priority as best; might
2718 if (state
->state
!= GUARD_CIRC_STATE_WAITING_FOR_BETTER_GUARD
)
2720 if (circ_state_has_higher_priority(best_waiting_circuit
, NULL
, circ
))
2723 state
->state
= GUARD_CIRC_STATE_COMPLETE
;
2724 state
->state_set_at
= approx_time();
2725 smartlist_add(newly_complete_out
, circ
);
2727 } SMARTLIST_FOREACH_END(circ
);
2729 log_info(LD_GUARD
, "Considered upgrading guard-stalled circuits: found "
2730 "%d guard-stalled, %d complete. %d of the guard-stalled "
2731 "circuit(s) had high enough priority to upgrade.",
2732 n_waiting
, n_complete
, n_succeeded
);
2734 tor_assert_nonfatal(n_succeeded
>= 1);
2735 smartlist_free(all_circuits
);
2739 smartlist_free(all_circuits
);
2744 * Return true iff the circuit whose state is <b>guard_state</b> should
2748 entry_guard_state_should_expire(circuit_guard_state_t
*guard_state
)
2750 if (guard_state
== NULL
)
2752 const time_t expire_if_waiting_since
=
2753 approx_time() - get_nonprimary_guard_idle_timeout();
2754 return (guard_state
->state
== GUARD_CIRC_STATE_WAITING_FOR_BETTER_GUARD
2755 && guard_state
->state_set_at
< expire_if_waiting_since
);
2759 * Update all derived pieces of the guard selection state in <b>gs</b>.
2760 * Return true iff we should stop using all previously generated circuits.
2763 entry_guards_update_all(guard_selection_t
*gs
)
2765 sampled_guards_update_from_consensus(gs
);
2766 entry_guards_update_filtered_sets(gs
);
2767 entry_guards_update_confirmed(gs
);
2768 entry_guards_update_primary(gs
);
2773 * Return a newly allocated string for encoding the persistent parts of
2774 * <b>guard</b> to the state file.
2777 entry_guard_encode_for_state(entry_guard_t
*guard
)
2780 * The meta-format we use is K=V K=V K=V... where K can be any
2781 * characters excepts space and =, and V can be any characters except
2782 * space. The order of entries is not allowed to matter.
2783 * Unrecognized K=V entries are persisted; recognized but erroneous
2784 * entries are corrected.
2787 smartlist_t
*result
= smartlist_new();
2788 char tbuf
[ISO_TIME_LEN
+1];
2792 smartlist_add_asprintf(result
, "in=%s", guard
->selection_name
);
2793 smartlist_add_asprintf(result
, "rsa_id=%s",
2794 hex_str(guard
->identity
, DIGEST_LEN
));
2795 if (guard
->bridge_addr
) {
2796 smartlist_add_asprintf(result
, "bridge_addr=%s:%d",
2797 fmt_and_decorate_addr(&guard
->bridge_addr
->addr
),
2798 guard
->bridge_addr
->port
);
2800 if (strlen(guard
->nickname
) && is_legal_nickname(guard
->nickname
)) {
2801 smartlist_add_asprintf(result
, "nickname=%s", guard
->nickname
);
2804 format_iso_time_nospace(tbuf
, guard
->sampled_on_date
);
2805 smartlist_add_asprintf(result
, "sampled_on=%s", tbuf
);
2807 if (guard
->sampled_by_version
) {
2808 smartlist_add_asprintf(result
, "sampled_by=%s",
2809 guard
->sampled_by_version
);
2812 if (guard
->unlisted_since_date
> 0) {
2813 format_iso_time_nospace(tbuf
, guard
->unlisted_since_date
);
2814 smartlist_add_asprintf(result
, "unlisted_since=%s", tbuf
);
2817 smartlist_add_asprintf(result
, "listed=%d",
2818 (int)guard
->currently_listed
);
2820 if (guard
->confirmed_idx
>= 0) {
2821 format_iso_time_nospace(tbuf
, guard
->confirmed_on_date
);
2822 smartlist_add_asprintf(result
, "confirmed_on=%s", tbuf
);
2824 smartlist_add_asprintf(result
, "confirmed_idx=%d", guard
->confirmed_idx
);
2827 const double EPSILON
= 1.0e-6;
2829 /* Make a copy of the pathbias object, since we will want to update
2831 guard_pathbias_t
*pb
= tor_memdup(&guard
->pb
, sizeof(*pb
));
2832 pb
->use_successes
= pathbias_get_use_success_count(guard
);
2833 pb
->successful_circuits_closed
= pathbias_get_close_success_count(guard
);
2835 #define PB_FIELD(field) do { \
2836 if (pb->field >= EPSILON) { \
2837 smartlist_add_asprintf(result, "pb_" #field "=%f", pb->field); \
2840 PB_FIELD(use_attempts
);
2841 PB_FIELD(use_successes
);
2842 PB_FIELD(circ_attempts
);
2843 PB_FIELD(circ_successes
);
2844 PB_FIELD(successful_circuits_closed
);
2845 PB_FIELD(collapsed_circuits
);
2846 PB_FIELD(unusable_circuits
);
2851 if (guard
->extra_state_fields
)
2852 smartlist_add_strdup(result
, guard
->extra_state_fields
);
2854 char *joined
= smartlist_join_strings(result
, " ", 0, NULL
);
2855 SMARTLIST_FOREACH(result
, char *, cp
, tor_free(cp
));
2856 smartlist_free(result
);
2862 * Given a string generated by entry_guard_encode_for_state(), parse it
2863 * (if possible) and return an entry_guard_t object for it. Return NULL
2864 * on complete failure.
2866 STATIC entry_guard_t
*
2867 entry_guard_parse_from_state(const char *s
)
2869 /* Unrecognized entries get put in here. */
2870 smartlist_t
*extra
= smartlist_new();
2872 /* These fields get parsed from the string. */
2874 char *rsa_id
= NULL
;
2875 char *nickname
= NULL
;
2876 char *sampled_on
= NULL
;
2877 char *sampled_by
= NULL
;
2878 char *unlisted_since
= NULL
;
2879 char *listed
= NULL
;
2880 char *confirmed_on
= NULL
;
2881 char *confirmed_idx
= NULL
;
2882 char *bridge_addr
= NULL
;
2885 char *pb_use_attempts
= NULL
;
2886 char *pb_use_successes
= NULL
;
2887 char *pb_circ_attempts
= NULL
;
2888 char *pb_circ_successes
= NULL
;
2889 char *pb_successful_circuits_closed
= NULL
;
2890 char *pb_collapsed_circuits
= NULL
;
2891 char *pb_unusable_circuits
= NULL
;
2892 char *pb_timeouts
= NULL
;
2894 /* Split up the entries. Put the ones we know about in strings and the
2895 * rest in "extra". */
2897 smartlist_t
*entries
= smartlist_new();
2899 strmap_t
*vals
= strmap_new(); // Maps keyword to location
2901 strmap_set(vals, #f, &f);
2907 FIELD(unlisted_since
);
2909 FIELD(confirmed_on
);
2910 FIELD(confirmed_idx
);
2912 FIELD(pb_use_attempts
);
2913 FIELD(pb_use_successes
);
2914 FIELD(pb_circ_attempts
);
2915 FIELD(pb_circ_successes
);
2916 FIELD(pb_successful_circuits_closed
);
2917 FIELD(pb_collapsed_circuits
);
2918 FIELD(pb_unusable_circuits
);
2922 smartlist_split_string(entries
, s
, " ",
2923 SPLIT_SKIP_SPACE
|SPLIT_IGNORE_BLANK
, 0);
2925 SMARTLIST_FOREACH_BEGIN(entries
, char *, entry
) {
2926 const char *eq
= strchr(entry
, '=');
2928 smartlist_add(extra
, entry
);
2931 char *key
= tor_strndup(entry
, eq
-entry
);
2932 char **target
= strmap_get(vals
, key
);
2933 if (target
== NULL
|| *target
!= NULL
) {
2934 /* unrecognized or already set */
2935 smartlist_add(extra
, entry
);
2940 *target
= tor_strdup(eq
+1);
2943 } SMARTLIST_FOREACH_END(entry
);
2945 smartlist_free(entries
);
2946 strmap_free(vals
, NULL
);
2949 entry_guard_t
*guard
= tor_malloc_zero(sizeof(entry_guard_t
));
2950 guard
->is_persistent
= 1;
2953 log_warn(LD_CIRC
, "Guard missing 'in' field");
2957 guard
->selection_name
= in
;
2960 if (rsa_id
== NULL
) {
2961 log_warn(LD_CIRC
, "Guard missing RSA ID field");
2965 /* Process the identity and nickname. */
2966 if (base16_decode(guard
->identity
, sizeof(guard
->identity
),
2967 rsa_id
, strlen(rsa_id
)) != DIGEST_LEN
) {
2968 log_warn(LD_CIRC
, "Unable to decode guard identity %s", escaped(rsa_id
));
2973 strlcpy(guard
->nickname
, nickname
, sizeof(guard
->nickname
));
2975 guard
->nickname
[0]='$';
2976 base16_encode(guard
->nickname
+1, sizeof(guard
->nickname
)-1,
2977 guard
->identity
, DIGEST_LEN
);
2981 tor_addr_port_t res
;
2982 memset(&res
, 0, sizeof(res
));
2983 int r
= tor_addr_port_parse(LOG_WARN
, bridge_addr
,
2984 &res
.addr
, &res
.port
, -1);
2986 guard
->bridge_addr
= tor_memdup(&res
, sizeof(res
));
2987 /* On error, we already warned. */
2990 /* Process the various time fields. */
2992 #define HANDLE_TIME(field) do { \
2994 int r = parse_iso_time_nospace(field, &field ## _time); \
2996 log_warn(LD_CIRC, "Unable to parse %s %s from guard", \
2997 #field, escaped(field)); \
2998 field##_time = -1; \
3003 time_t sampled_on_time
= 0;
3004 time_t unlisted_since_time
= 0;
3005 time_t confirmed_on_time
= 0;
3007 HANDLE_TIME(sampled_on
);
3008 HANDLE_TIME(unlisted_since
);
3009 HANDLE_TIME(confirmed_on
);
3011 if (sampled_on_time
<= 0)
3012 sampled_on_time
= approx_time();
3013 if (unlisted_since_time
< 0)
3014 unlisted_since_time
= 0;
3015 if (confirmed_on_time
< 0)
3016 confirmed_on_time
= 0;
3020 guard
->sampled_on_date
= sampled_on_time
;
3021 guard
->unlisted_since_date
= unlisted_since_time
;
3022 guard
->confirmed_on_date
= confirmed_on_time
;
3024 /* Take sampled_by_version verbatim. */
3025 guard
->sampled_by_version
= sampled_by
;
3026 sampled_by
= NULL
; /* prevent free */
3028 /* Listed is a boolean */
3029 if (listed
&& strcmp(listed
, "0"))
3030 guard
->currently_listed
= 1;
3032 /* The index is a nonnegative integer. */
3033 guard
->confirmed_idx
= -1;
3034 if (confirmed_idx
) {
3036 long idx
= tor_parse_long(confirmed_idx
, 10, 0, INT_MAX
, &ok
, NULL
);
3038 log_warn(LD_GUARD
, "Guard has invalid confirmed_idx %s",
3039 escaped(confirmed_idx
));
3041 guard
->confirmed_idx
= (int)idx
;
3045 /* Anything we didn't recognize gets crammed together */
3046 if (smartlist_len(extra
) > 0) {
3047 guard
->extra_state_fields
= smartlist_join_strings(extra
, " ", 0, NULL
);
3050 /* initialize non-persistent fields */
3051 guard
->is_reachable
= GUARD_REACHABLE_MAYBE
;
3053 #define PB_FIELD(field) \
3055 if (pb_ ## field) { \
3057 double r = tor_parse_double(pb_ ## field, 0.0, 1e9, &ok, NULL); \
3059 log_warn(LD_CIRC, "Guard has invalid pb_%s %s", \
3060 #field, pb_ ## field); \
3062 guard->pb.field = r; \
3066 PB_FIELD(use_attempts
);
3067 PB_FIELD(use_successes
);
3068 PB_FIELD(circ_attempts
);
3069 PB_FIELD(circ_successes
);
3070 PB_FIELD(successful_circuits_closed
);
3071 PB_FIELD(collapsed_circuits
);
3072 PB_FIELD(unusable_circuits
);
3076 pathbias_check_use_success_count(guard
);
3077 pathbias_check_close_success_count(guard
);
3079 /* We update everything on this guard later, after we've parsed
3085 // only consider it an error if the guard state was totally unparseable.
3086 entry_guard_free(guard
);
3093 tor_free(sampled_on
);
3094 tor_free(sampled_by
);
3095 tor_free(unlisted_since
);
3097 tor_free(confirmed_on
);
3098 tor_free(confirmed_idx
);
3099 tor_free(bridge_addr
);
3100 tor_free(pb_use_attempts
);
3101 tor_free(pb_use_successes
);
3102 tor_free(pb_circ_attempts
);
3103 tor_free(pb_circ_successes
);
3104 tor_free(pb_successful_circuits_closed
);
3105 tor_free(pb_collapsed_circuits
);
3106 tor_free(pb_unusable_circuits
);
3107 tor_free(pb_timeouts
);
3109 SMARTLIST_FOREACH(extra
, char *, cp
, tor_free(cp
));
3110 smartlist_free(extra
);
3116 * Replace the Guards entries in <b>state</b> with a list of all our sampled
3120 entry_guards_update_guards_in_state(or_state_t
*state
)
3122 if (!guard_contexts
)
3124 config_line_t
*lines
= NULL
;
3125 config_line_t
**nextline
= &lines
;
3127 SMARTLIST_FOREACH_BEGIN(guard_contexts
, guard_selection_t
*, gs
) {
3128 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
3129 if (guard
->is_persistent
== 0)
3131 *nextline
= tor_malloc_zero(sizeof(config_line_t
));
3132 (*nextline
)->key
= tor_strdup("Guard");
3133 (*nextline
)->value
= entry_guard_encode_for_state(guard
);
3134 nextline
= &(*nextline
)->next
;
3135 } SMARTLIST_FOREACH_END(guard
);
3136 } SMARTLIST_FOREACH_END(gs
);
3138 config_free_lines(state
->Guard
);
3139 state
->Guard
= lines
;
3143 * Replace our sampled guards from the Guards entries in <b>state</b>. Return 0
3144 * on success, -1 on failure. (If <b>set</b> is true, replace nothing -- only
3145 * check whether replacing would work.)
3148 entry_guards_load_guards_from_state(or_state_t
*state
, int set
)
3150 const config_line_t
*line
= state
->Guard
;
3153 if (!guard_contexts
)
3154 guard_contexts
= smartlist_new();
3156 /* Wipe all our existing guard info. (we shouldn't have any, but
3157 * let's be safe.) */
3159 SMARTLIST_FOREACH_BEGIN(guard_contexts
, guard_selection_t
*, gs
) {
3160 guard_selection_free(gs
);
3161 if (curr_guard_context
== gs
)
3162 curr_guard_context
= NULL
;
3163 SMARTLIST_DEL_CURRENT(guard_contexts
, gs
);
3164 } SMARTLIST_FOREACH_END(gs
);
3167 for ( ; line
!= NULL
; line
= line
->next
) {
3168 entry_guard_t
*guard
= entry_guard_parse_from_state(line
->value
);
3169 if (guard
== NULL
) {
3173 tor_assert(guard
->selection_name
);
3174 if (!strcmp(guard
->selection_name
, "legacy")) {
3176 entry_guard_free(guard
);
3181 guard_selection_t
*gs
;
3182 gs
= get_guard_selection_by_name(guard
->selection_name
,
3185 smartlist_add(gs
->sampled_entry_guards
, guard
);
3186 guard
->in_selection
= gs
;
3188 entry_guard_free(guard
);
3193 SMARTLIST_FOREACH_BEGIN(guard_contexts
, guard_selection_t
*, gs
) {
3194 entry_guards_update_all(gs
);
3195 } SMARTLIST_FOREACH_END(gs
);
3197 return n_errors
? -1 : 0;
3200 /** If <b>digest</b> matches the identity of any node in the
3201 * entry_guards list for the provided guard selection state,
3202 return that node. Else return NULL. */
3204 entry_guard_get_by_id_digest_for_guard_selection(guard_selection_t
*gs
,
3207 return get_sampled_guard_with_id(gs
, (const uint8_t*)digest
);
3210 /** Return the node_t associated with a single entry_guard_t. May
3211 * return NULL if the guard is not currently in the consensus. */
3213 entry_guard_find_node(const entry_guard_t
*guard
)
3216 return node_get_by_id(guard
->identity
);
3219 /** If <b>digest</b> matches the identity of any node in the
3220 * entry_guards list for the default guard selection state,
3221 return that node. Else return NULL. */
3223 entry_guard_get_by_id_digest(const char *digest
)
3225 return entry_guard_get_by_id_digest_for_guard_selection(
3226 get_guard_selection_info(), digest
);
3229 /** We are about to connect to bridge with identity <b>digest</b> to fetch its
3230 * descriptor. Create a new guard state for this connection and return it. */
3231 circuit_guard_state_t
*
3232 get_guard_state_for_bridge_desc_fetch(const char *digest
)
3234 circuit_guard_state_t
*guard_state
= NULL
;
3235 entry_guard_t
*guard
= NULL
;
3237 guard
= entry_guard_get_by_id_digest_for_guard_selection(
3238 get_guard_selection_info(), digest
);
3243 /* Update the guard last_tried_to_connect time since it's checked by the
3244 * guard susbsystem. */
3245 guard
->last_tried_to_connect
= approx_time();
3247 /* Create the guard state */
3248 guard_state
= circuit_guard_state_new(guard
,
3249 GUARD_CIRC_STATE_USABLE_ON_COMPLETION
,
3255 /** Release all storage held by <b>e</b>. */
3257 entry_guard_free_(entry_guard_t
*e
)
3261 entry_guard_handles_clear(e
);
3262 tor_free(e
->sampled_by_version
);
3263 tor_free(e
->extra_state_fields
);
3264 tor_free(e
->selection_name
);
3265 tor_free(e
->bridge_addr
);
3269 /** Return 0 if we're fine adding arbitrary routers out of the
3270 * directory to our entry guard list, or return 1 if we have a
3271 * list already and we must stick to it.
3274 entry_list_is_constrained(const or_options_t
*options
)
3276 // XXXX #21425 look at the current selection.
3277 if (options
->EntryNodes
)
3279 if (options
->UseBridges
)
3284 /** Return the number of bridges that have descriptors that are marked with
3285 * purpose 'bridge' and are running. If use_maybe_reachable is
3286 * true, include bridges that might be reachable in the count.
3287 * Otherwise, if it is false, only include bridges that have recently been
3288 * found running in the count.
3290 * We use this function to decide if we're ready to start building
3291 * circuits through our bridges, or if we need to wait until the
3292 * directory "server/authority" requests finish. */
3294 num_bridges_usable
,(int use_maybe_reachable
))
3298 if (BUG(!get_options()->UseBridges
)) {
3301 guard_selection_t
*gs
= get_guard_selection_info();
3302 if (BUG(gs
->type
!= GS_TYPE_BRIDGE
)) {
3306 SMARTLIST_FOREACH_BEGIN(gs
->sampled_entry_guards
, entry_guard_t
*, guard
) {
3307 /* Not a bridge, or not one we are configured to be able to use. */
3308 if (! guard
->is_filtered_guard
)
3310 /* Definitely not usable */
3311 if (guard
->is_reachable
== GUARD_REACHABLE_NO
)
3313 /* If we want to be really sure the bridges will work, skip maybes */
3314 if (!use_maybe_reachable
&& guard
->is_reachable
== GUARD_REACHABLE_MAYBE
)
3316 if (tor_digest_is_zero(guard
->identity
))
3318 const node_t
*node
= node_get_by_id(guard
->identity
);
3319 if (node
&& node
->ri
)
3321 } SMARTLIST_FOREACH_END(guard
);
3326 /** Check the pathbias use success count of <b>node</b> and disable it if it
3327 * goes over our thresholds. */
3329 pathbias_check_use_success_count(entry_guard_t
*node
)
3331 const or_options_t
*options
= get_options();
3332 const double EPSILON
= 1.0e-9;
3334 /* Note: We rely on the < comparison here to allow us to set a 0
3335 * rate and disable the feature entirely. If refactoring, don't
3337 if (node
->pb
.use_attempts
> EPSILON
&&
3338 pathbias_get_use_success_count(node
)/node
->pb
.use_attempts
3339 < pathbias_get_extreme_use_rate(options
) &&
3340 pathbias_get_dropguards(options
)) {
3341 node
->pb
.path_bias_disabled
= 1;
3342 log_info(LD_GENERAL
,
3343 "Path use bias is too high (%f/%f); disabling node %s",
3344 node
->pb
.circ_successes
, node
->pb
.circ_attempts
,
3349 /** Check the pathbias close count of <b>node</b> and disable it if it goes
3350 * over our thresholds. */
3352 pathbias_check_close_success_count(entry_guard_t
*node
)
3354 const or_options_t
*options
= get_options();
3355 const double EPSILON
= 1.0e-9;
3357 /* Note: We rely on the < comparison here to allow us to set a 0
3358 * rate and disable the feature entirely. If refactoring, don't
3360 if (node
->pb
.circ_attempts
> EPSILON
&&
3361 pathbias_get_close_success_count(node
)/node
->pb
.circ_attempts
3362 < pathbias_get_extreme_rate(options
) &&
3363 pathbias_get_dropguards(options
)) {
3364 node
->pb
.path_bias_disabled
= 1;
3365 log_info(LD_GENERAL
,
3366 "Path bias is too high (%f/%f); disabling node %s",
3367 node
->pb
.circ_successes
, node
->pb
.circ_attempts
,
3372 /** Parse <b>state</b> and learn about the entry guards it describes.
3373 * If <b>set</b> is true, and there are no errors, replace the guard
3374 * list in the default guard selection context with what we find.
3375 * On success, return 0. On failure, alloc into *<b>msg</b> a string
3376 * describing the error, and return -1.
3379 entry_guards_parse_state(or_state_t
*state
, int set
, char **msg
)
3381 entry_guards_dirty
= 0;
3382 int r1
= entry_guards_load_guards_from_state(state
, set
);
3383 entry_guards_dirty
= 0;
3386 if (msg
&& *msg
== NULL
) {
3387 *msg
= tor_strdup("parsing error");
3394 /** How long will we let a change in our guard nodes stay un-saved
3395 * when we are trying to avoid disk writes? */
3396 #define SLOW_GUARD_STATE_FLUSH_TIME 600
3397 /** How long will we let a change in our guard nodes stay un-saved
3398 * when we are not trying to avoid disk writes? */
3399 #define FAST_GUARD_STATE_FLUSH_TIME 30
3401 /** Our list of entry guards has changed for a particular guard selection
3402 * context, or some element of one of our entry guards has changed for one.
3403 * Write the changes to disk within the next few minutes.
3406 entry_guards_changed_for_guard_selection(guard_selection_t
*gs
)
3410 tor_assert(gs
!= NULL
);
3412 entry_guards_dirty
= 1;
3414 if (get_options()->AvoidDiskWrites
)
3415 when
= time(NULL
) + SLOW_GUARD_STATE_FLUSH_TIME
;
3417 when
= time(NULL
) + FAST_GUARD_STATE_FLUSH_TIME
;
3419 /* or_state_save() will call entry_guards_update_state() and
3420 entry_guards_update_guards_in_state()
3422 or_state_mark_dirty(get_or_state(), when
);
3425 /** Our list of entry guards has changed for the default guard selection
3426 * context, or some element of one of our entry guards has changed. Write
3427 * the changes to disk within the next few minutes.
3430 entry_guards_changed(void)
3432 entry_guards_changed_for_guard_selection(get_guard_selection_info());
3435 /** If the entry guard info has not changed, do nothing and return.
3436 * Otherwise, free the EntryGuards piece of <b>state</b> and create
3437 * a new one out of the global entry_guards list, and then mark
3438 * <b>state</b> dirty so it will get saved to disk.
3441 entry_guards_update_state(or_state_t
*state
)
3443 entry_guards_dirty
= 0;
3445 // Handles all guard info.
3446 entry_guards_update_guards_in_state(state
);
3448 entry_guards_dirty
= 0;
3450 if (!get_options()->AvoidDiskWrites
)
3451 or_state_mark_dirty(get_or_state(), 0);
3452 entry_guards_dirty
= 0;
3455 /** Return true iff the circuit's guard can succeed, that is, can be used. */
3457 entry_guard_could_succeed(const circuit_guard_state_t
*guard_state
)
3459 if (get_options()->UseEntryGuards
== 0) {
3460 /* we're fine with this circuit's first hop, because we're not
3461 * configured to use entry guards. */
3469 entry_guard_t
*guard
= entry_guard_handle_get(guard_state
->guard
);
3470 if (!guard
|| BUG(guard
->in_selection
== NULL
)) {
3478 * Format a single entry guard in the format expected by the controller.
3479 * Return a newly allocated string.
3482 getinfo_helper_format_single_entry_guard(const entry_guard_t
*e
)
3484 const char *status
= NULL
;
3487 char tbuf
[ISO_TIME_LEN
+1];
3488 char nbuf
[MAX_VERBOSE_NICKNAME_LEN
+1];
3490 /* This is going to be a bit tricky, since the status
3491 * codes weren't really intended for prop271 guards.
3493 * XXXX use a more appropriate format for exporting this information
3495 if (e
->confirmed_idx
< 0) {
3496 status
= "never-connected";
3497 } else if (! e
->currently_listed
) {
3498 when
= e
->unlisted_since_date
;
3499 status
= "unusable";
3500 } else if (! e
->is_filtered_guard
) {
3501 status
= "unusable";
3502 } else if (e
->is_reachable
== GUARD_REACHABLE_NO
) {
3503 when
= e
->failing_since
;
3509 node
= entry_guard_find_node(e
);
3511 node_get_verbose_nickname(node
, nbuf
);
3514 base16_encode(nbuf
+1, sizeof(nbuf
)-1, e
->identity
, DIGEST_LEN
);
3515 /* e->nickname field is not very reliable if we don't know about
3516 * this router any longer; don't include it. */
3519 char *result
= NULL
;
3521 format_iso_time(tbuf
, when
);
3522 tor_asprintf(&result
, "%s %s %s\n", nbuf
, status
, tbuf
);
3524 tor_asprintf(&result
, "%s %s\n", nbuf
, status
);
3529 /** If <b>question</b> is the string "entry-guards", then dump
3530 * to *<b>answer</b> a newly allocated string describing all of
3531 * the nodes in the global entry_guards list. See control-spec.txt
3533 * For backward compatibility, we also handle the string "helper-nodes".
3535 * XXX this should be totally redesigned after prop 271 too, and that's
3536 * going to take some control spec work.
3539 getinfo_helper_entry_guards(control_connection_t
*conn
,
3540 const char *question
, char **answer
,
3541 const char **errmsg
)
3543 guard_selection_t
*gs
= get_guard_selection_info();
3545 tor_assert(gs
!= NULL
);
3550 if (!strcmp(question
,"entry-guards") ||
3551 !strcmp(question
,"helper-nodes")) {
3552 const smartlist_t
*guards
;
3553 guards
= gs
->sampled_entry_guards
;
3555 smartlist_t
*sl
= smartlist_new();
3557 SMARTLIST_FOREACH_BEGIN(guards
, const entry_guard_t
*, e
) {
3558 char *cp
= getinfo_helper_format_single_entry_guard(e
);
3559 smartlist_add(sl
, cp
);
3560 } SMARTLIST_FOREACH_END(e
);
3561 *answer
= smartlist_join_strings(sl
, "", 0, NULL
);
3562 SMARTLIST_FOREACH(sl
, char *, c
, tor_free(c
));
3568 /* Given the original bandwidth of a guard and its guardfraction,
3569 * calculate how much bandwidth the guard should have as a guard and
3572 * Quoting from proposal236:
3574 * Let Wpf denote the weight from the 'bandwidth-weights' line a
3575 * client would apply to N for position p if it had the guard
3576 * flag, Wpn the weight if it did not have the guard flag, and B the
3577 * measured bandwidth of N in the consensus. Then instead of choosing
3578 * N for position p proportionally to Wpf*B or Wpn*B, clients should
3579 * choose N proportionally to F*Wpf*B + (1-F)*Wpn*B.
3581 * This function fills the <b>guardfraction_bw</b> structure. It sets
3582 * <b>guard_bw</b> to F*B and <b>non_guard_bw</b> to (1-F)*B.
3585 guard_get_guardfraction_bandwidth(guardfraction_bandwidth_t
*guardfraction_bw
,
3587 uint32_t guardfraction_percentage
)
3589 double guardfraction_fraction
;
3591 /* Turn the percentage into a fraction. */
3592 tor_assert(guardfraction_percentage
<= 100);
3593 guardfraction_fraction
= guardfraction_percentage
/ 100.0;
3595 long guard_bw
= tor_lround(guardfraction_fraction
* orig_bandwidth
);
3596 tor_assert(guard_bw
<= INT_MAX
);
3598 guardfraction_bw
->guard_bw
= (int) guard_bw
;
3600 guardfraction_bw
->non_guard_bw
= orig_bandwidth
- (int) guard_bw
;
3603 /** Helper: Update the status of all entry guards, in whatever algorithm
3604 * is used. Return true if we should stop using all previously generated
3605 * circuits, by calling circuit_mark_all_unused_circs() and
3606 * circuit_mark_all_dirty_circs_as_unusable().
3609 guards_update_all(void)
3611 int mark_circuits
= 0;
3612 if (update_guard_selection_choice(get_options()))
3615 tor_assert(curr_guard_context
);
3617 if (entry_guards_update_all(curr_guard_context
))
3620 return mark_circuits
;
3623 /** Helper: pick a guard for a circuit, with whatever algorithm is
3626 guards_choose_guard(cpath_build_state_t
*state
,
3628 circuit_guard_state_t
**guard_state_out
)
3630 const node_t
*r
= NULL
;
3631 const uint8_t *exit_id
= NULL
;
3632 entry_guard_restriction_t
*rst
= NULL
;
3634 /* Only apply restrictions if we have a specific exit node in mind, and only
3635 * if we are not doing vanguard circuits: we don't want to apply guard
3636 * restrictions to vanguard circuits. */
3637 if (state
&& !circuit_should_use_vanguards(purpose
) &&
3638 (exit_id
= build_state_get_exit_rsa_id(state
))) {
3639 /* We're building to a targeted exit node, so that node can't be
3640 * chosen as our guard for this circuit. Remember that fact in a
3642 rst
= guard_create_exit_restriction(exit_id
);
3645 if (entry_guard_pick_for_circuit(get_guard_selection_info(),
3646 GUARD_USAGE_TRAFFIC
,
3649 guard_state_out
) < 0) {
3650 tor_assert(r
== NULL
);
3655 /** Remove all currently listed entry guards for a given guard selection
3656 * context. This frees and replaces <b>gs</b>, so don't use <b>gs</b>
3657 * after calling this function. */
3659 remove_all_entry_guards_for_guard_selection(guard_selection_t
*gs
)
3661 // This function shouldn't exist. XXXX
3662 tor_assert(gs
!= NULL
);
3663 char *old_name
= tor_strdup(gs
->name
);
3664 guard_selection_type_t old_type
= gs
->type
;
3666 SMARTLIST_FOREACH(gs
->sampled_entry_guards
, entry_guard_t
*, entry
, {
3667 control_event_guard(entry
->nickname
, entry
->identity
, "DROPPED");
3670 if (gs
== curr_guard_context
) {
3671 curr_guard_context
= NULL
;
3674 smartlist_remove(guard_contexts
, gs
);
3675 guard_selection_free(gs
);
3677 gs
= get_guard_selection_by_name(old_name
, old_type
, 1);
3678 entry_guards_changed_for_guard_selection(gs
);
3682 /** Remove all currently listed entry guards, so new ones will be chosen.
3684 * XXXX This function shouldn't exist -- it's meant to support the DROPGUARDS
3685 * command, which is deprecated.
3688 remove_all_entry_guards(void)
3690 remove_all_entry_guards_for_guard_selection(get_guard_selection_info());
3693 /** Helper: pick a directory guard, with whatever algorithm is used. */
3695 guards_choose_dirguard(uint8_t dir_purpose
,
3696 circuit_guard_state_t
**guard_state_out
)
3698 const node_t
*r
= NULL
;
3699 entry_guard_restriction_t
*rst
= NULL
;
3701 /* If we are fetching microdescs, don't query outdated dirservers. */
3702 if (dir_purpose
== DIR_PURPOSE_FETCH_MICRODESC
) {
3703 rst
= guard_create_dirserver_md_restriction();
3706 if (entry_guard_pick_for_circuit(get_guard_selection_info(),
3707 GUARD_USAGE_DIRGUARD
,
3710 guard_state_out
) < 0) {
3711 tor_assert(r
== NULL
);
3717 * If we're running with a constrained guard set, then maybe mark our guards
3718 * usable. Return 1 if we do; 0 if we don't.
3721 guards_retry_optimistic(const or_options_t
*options
)
3723 if (! entry_list_is_constrained(options
))
3726 mark_primary_guards_maybe_reachable(get_guard_selection_info());
3732 * Check if we are missing any crucial dirinfo for the guard subsystem to
3733 * work. Return NULL if everything went well, otherwise return a newly
3734 * allocated string with an informative error message. In the latter case, use
3735 * the genreal descriptor information <b>using_mds</b>, <b>num_present</b> and
3736 * <b>num_usable</b> to improve the error message. */
3738 guard_selection_get_err_str_if_dir_info_missing(guard_selection_t
*gs
,
3740 int num_present
, int num_usable
)
3742 if (!gs
->primary_guards_up_to_date
)
3743 entry_guards_update_primary(gs
);
3745 char *ret_str
= NULL
;
3746 int n_missing_descriptors
= 0;
3747 int n_considered
= 0;
3748 int num_primary_to_check
;
3750 /* We want to check for the descriptor of at least the first two primary
3751 * guards in our list, since these are the guards that we typically use for
3753 num_primary_to_check
= get_n_primary_guards_to_use(GUARD_USAGE_TRAFFIC
);
3754 num_primary_to_check
++;
3756 SMARTLIST_FOREACH_BEGIN(gs
->primary_entry_guards
, entry_guard_t
*, guard
) {
3757 entry_guard_consider_retry(guard
);
3758 if (guard
->is_reachable
== GUARD_REACHABLE_NO
)
3761 if (!guard_has_descriptor(guard
))
3762 n_missing_descriptors
++;
3763 if (n_considered
>= num_primary_to_check
)
3765 } SMARTLIST_FOREACH_END(guard
);
3767 /* If we are not missing any descriptors, return NULL. */
3768 if (!n_missing_descriptors
) {
3772 /* otherwise return a helpful error string */
3773 tor_asprintf(&ret_str
, "We're missing descriptors for %d/%d of our "
3774 "primary entry guards (total %sdescriptors: %d/%d). "
3775 "That's ok. We will try to fetch missing descriptors soon.",
3776 n_missing_descriptors
, num_primary_to_check
,
3777 using_mds
?"micro":"", num_present
, num_usable
);
3782 /** As guard_selection_have_enough_dir_info_to_build_circuits, but uses
3783 * the default guard selection. */
3785 entry_guards_get_err_str_if_dir_info_missing(int using_mds
,
3786 int num_present
, int num_usable
)
3788 return guard_selection_get_err_str_if_dir_info_missing(
3789 get_guard_selection_info(),
3791 num_present
, num_usable
);
3794 /** Free one guard selection context */
3796 guard_selection_free_(guard_selection_t
*gs
)
3802 if (gs
->sampled_entry_guards
) {
3803 SMARTLIST_FOREACH(gs
->sampled_entry_guards
, entry_guard_t
*, e
,
3804 entry_guard_free(e
));
3805 smartlist_free(gs
->sampled_entry_guards
);
3806 gs
->sampled_entry_guards
= NULL
;
3809 smartlist_free(gs
->confirmed_entry_guards
);
3810 smartlist_free(gs
->primary_entry_guards
);
3815 /** Release all storage held by the list of entry guards and related
3816 * memory structs. */
3818 entry_guards_free_all(void)
3820 /* Null out the default */
3821 curr_guard_context
= NULL
;
3822 /* Free all the guard contexts */
3823 if (guard_contexts
!= NULL
) {
3824 SMARTLIST_FOREACH_BEGIN(guard_contexts
, guard_selection_t
*, gs
) {
3825 guard_selection_free(gs
);
3826 } SMARTLIST_FOREACH_END(gs
);
3827 smartlist_free(guard_contexts
);
3828 guard_contexts
= NULL
;
3830 circuit_build_times_free_timeouts(get_circuit_build_times_mutable());