Code to manage our fixed first nodes for various functions. More...

#include "core/or/or.h"
#include "app/config/config.h"
#include "lib/confmgt/confmgt.h"
#include "app/config/statefile.h"
#include "core/mainloop/connection.h"
#include "core/mainloop/mainloop.h"
#include "core/or/channel.h"
#include "core/or/circuitbuild.h"
#include "core/or/circuitlist.h"
#include "core/or/circuitstats.h"
#include "core/or/circuituse.h"
#include "core/or/conflux_pool.h"
#include "core/or/policies.h"
#include "feature/client/bridges.h"
#include "feature/client/circpathbias.h"
#include "feature/client/entrynodes.h"
#include "feature/client/transports.h"
#include "feature/control/control_events.h"
#include "feature/dirclient/dlstatus.h"
#include "feature/dircommon/directory.h"
#include "feature/nodelist/describe.h"
#include "feature/nodelist/microdesc.h"
#include "feature/nodelist/networkstatus.h"
#include "feature/nodelist/nickname.h"
#include "feature/nodelist/nodelist.h"
#include "feature/nodelist/node_select.h"
#include "feature/nodelist/routerset.h"
#include "feature/relay/router.h"
#include "lib/crypt_ops/crypto_rand.h"
#include "lib/crypt_ops/digestset.h"
#include "lib/encoding/confline.h"
#include "lib/math/fp.h"
#include "feature/nodelist/node_st.h"
#include "core/or/origin_circuit_st.h"
#include "app/config/or_state_st.h"
#include "src/feature/nodelist/routerstatus_st.h"
#include "core/or/conflux_util.h"

Data Structures
struct	layer2_guard_t

Macros
#define	ENTRYNODES_PRIVATE

#define	MIN_GUARDS_FOR_MD_RESTRICTION 10

#define	PB_FIELD(field)

#define	HANDLE_TIME(field)

#define	FIELD(f) strmap_set(vals, #f, &f);

#define	PB_FIELD(field)

#define	SLOW_GUARD_STATE_FLUSH_TIME 600

#define	FAST_GUARD_STATE_FLUSH_TIME 30

#define	layer2_guard_free(val) FREE_AND_NULL(layer2_guard_t, layer2_guard_free_, (val))

#define	NUMBER_SECOND_GUARDS 4

#define	MIN_SECOND_GUARD_LIFETIME (3600*24)

#define	MAX_SECOND_GUARD_LIFETIME (36002412)

Functions
static void	entry_guard_set_filtered_flags (const or_options_t options, guard_selection_t gs, entry_guard_t *guard)

static void	pathbias_check_use_success_count (entry_guard_t *guard)

static void	pathbias_check_close_success_count (entry_guard_t *guard)

static int	node_is_possible_guard (const node_t *node)

static int	node_passes_guard_filter (const or_options_t options, const node_t node)

static entry_guard_t *	entry_guard_add_to_sample_impl (guard_selection_t gs, const uint8_t rsa_id_digest, const char nickname, const tor_addr_port_t bridge_addrport)

static entry_guard_t *	get_sampled_guard_by_bridge_addr (guard_selection_t gs, const tor_addr_port_t addrport)

static int	entry_guard_obeys_restriction (const entry_guard_t guard, const entry_guard_restriction_t rst)

static int	compare_guards_by_sampled_idx (const void a_, const void b_)

int	should_apply_guardfraction (const networkstatus_t *ns)

static int	guard_has_descriptor (const entry_guard_t *guard)

STATIC guard_selection_type_t	guard_selection_infer_type (guard_selection_type_t type, const char *name)

STATIC guard_selection_t *	guard_selection_new (const char *name, guard_selection_type_t type)

STATIC guard_selection_t *	get_guard_selection_by_name (const char *name, guard_selection_type_t type, int create_if_absent)

static void	create_initial_guard_context (void)

guard_selection_t *	get_guard_selection_info (void)

const char *	entry_guard_describe (const entry_guard_t *guard)

const char *	entry_guard_get_rsa_id_digest (const entry_guard_t *guard)

guard_pathbias_t *	entry_guard_get_pathbias_state (entry_guard_t *guard)

STATIC time_t	randomize_time (time_t now, time_t max_backdate)

STATIC const char *	choose_guard_selection (const or_options_t options, const networkstatus_t live_ns, const guard_selection_t old_selection, guard_selection_type_t type_out)

int	update_guard_selection_choice (const or_options_t *options)

STATIC entry_guard_t *	get_sampled_guard_with_id (guard_selection_t gs, const uint8_t rsa_id)

static entry_guard_t *	get_sampled_guard_for_bridge (guard_selection_t gs, const bridge_info_t bridge)

static bridge_info_t *	get_bridge_info_for_guard (const entry_guard_t *guard)

static int	have_sampled_guard_with_id (guard_selection_t gs, const uint8_t rsa_id)

STATIC entry_guard_t *	entry_guard_add_to_sample (guard_selection_t gs, const node_t node)

static entry_guard_t *	entry_guard_add_bridge_to_sample (guard_selection_t gs, const bridge_info_t bridge)

void	entry_guard_learned_bridge_identity (const tor_addr_port_t addrport, const uint8_t rsa_id_digest)

STATIC int	num_reachable_filtered_guards (const guard_selection_t gs, const entry_guard_restriction_t rst)

static int	get_max_sample_size (guard_selection_t *gs, int n_guards)

static smartlist_t *	get_eligible_guards (const or_options_t options, guard_selection_t gs, int *n_guards_out)

static entry_guard_t *	select_and_add_guard_item_for_sample (guard_selection_t gs, smartlist_t eligible_guards)

static int	reasonably_live_consensus_is_missing (const guard_selection_t *gs)

STATIC entry_guard_t *	entry_guards_expand_sample (guard_selection_t *gs)

static void	remove_guard_from_confirmed_and_primary_lists (guard_selection_t gs, entry_guard_t guard)

STATIC int	entry_guard_is_listed (guard_selection_t gs, const entry_guard_t guard)

static size_t	sampled_guards_update_consensus_presence (guard_selection_t *gs)

static size_t	sampled_guards_prune_obsolete_entries (guard_selection_t *gs, const time_t remove_if_unlisted_since, const time_t maybe_remove_if_sampled_before, const time_t remove_if_confirmed_before)

STATIC void	sampled_guards_update_from_consensus (guard_selection_t *gs)

static int	bridge_passes_guard_filter (const or_options_t options, const bridge_info_t bridge)

static int	entry_guard_passes_filter (const or_options_t options, guard_selection_t gs, entry_guard_t *guard)

static int	guard_in_node_family (const entry_guard_t guard, const node_t node)

STATIC entry_guard_restriction_t *	guard_create_exit_restriction (const uint8_t *exit_id)

STATIC entry_guard_restriction_t *	guard_create_conflux_restriction (const origin_circuit_t *circ)

static int	should_set_md_dirserver_restriction (void)

STATIC entry_guard_restriction_t *	guard_create_dirserver_md_restriction (void)

static int	guard_obeys_exit_restriction (const entry_guard_t guard, const entry_guard_restriction_t rst)

static int	guard_obeys_md_dirserver_restriction (const entry_guard_t *guard)

static bool	entry_guard_restriction_is_reachability (const entry_guard_restriction_t *rst)

STATIC void	entry_guards_update_filtered_sets (guard_selection_t *gs)

STATIC entry_guard_t *	first_reachable_filtered_entry_guard (guard_selection_t gs, const entry_guard_restriction_t rst, unsigned flags)

static int	compare_guards_by_confirmed_idx (const void a_, const void b_)

STATIC void	entry_guards_update_confirmed (guard_selection_t *gs)

STATIC void	make_guard_confirmed (guard_selection_t gs, entry_guard_t guard)

STATIC void	entry_guards_update_primary (guard_selection_t *gs)

static int	get_retry_schedule (time_t failing_since, time_t now, int is_primary)

STATIC void	entry_guard_consider_retry (entry_guard_t *guard)

void	entry_guards_note_internet_connectivity (guard_selection_t *gs)

static entry_guard_t *	select_primary_guard_for_circuit (guard_selection_t gs, guard_usage_t usage, const entry_guard_restriction_t rst, unsigned *state_out)

static entry_guard_t *	select_confirmed_guard_for_circuit (guard_selection_t gs, guard_usage_t usage, const entry_guard_restriction_t rst, unsigned *state_out)

static entry_guard_t *	select_filtered_guard_for_circuit (guard_selection_t gs, guard_usage_t usage, const entry_guard_restriction_t rst, unsigned *state_out)

STATIC entry_guard_t *	select_entry_guard_for_circuit (guard_selection_t gs, guard_usage_t usage, const entry_guard_restriction_t rst, unsigned *state_out)

STATIC void	entry_guards_note_guard_failure (guard_selection_t gs, entry_guard_t guard)

STATIC unsigned	entry_guards_note_guard_success (guard_selection_t gs, entry_guard_t guard, unsigned old_state)

STATIC int	entry_guard_has_higher_priority (entry_guard_t a, entry_guard_t b)

STATIC void	entry_guard_restriction_free_ (entry_guard_restriction_t *rst)

void	circuit_guard_state_free_ (circuit_guard_state_t *state)

STATIC circuit_guard_state_t *	circuit_guard_state_new (entry_guard_t guard, unsigned state, entry_guard_restriction_t rst)

int	entry_guard_pick_for_circuit (guard_selection_t gs, guard_usage_t usage, entry_guard_restriction_t rst, const node_t chosen_node_out, circuit_guard_state_t guard_state_out)

guard_usable_t	entry_guard_succeeded (circuit_guard_state_t **guard_state_p)

void	entry_guard_cancel (circuit_guard_state_t **guard_state_p)

void	entry_guard_failed (circuit_guard_state_t **guard_state_p)

void	entry_guard_chan_failed (channel_t *chan)

STATIC int	entry_guards_all_primary_guards_are_down (guard_selection_t *gs)

static int	circ_state_has_higher_priority (origin_circuit_t a, const entry_guard_restriction_t rst, origin_circuit_t *b)

int	entry_guards_upgrade_waiting_circuits (guard_selection_t gs, const smartlist_t all_circuits_in, smartlist_t *newly_complete_out)

int	entry_guard_state_should_expire (circuit_guard_state_t *guard_state)

int	entry_guards_update_all (guard_selection_t *gs)

STATIC char *	entry_guard_encode_for_state (entry_guard_t *guard, int dense_sampled_idx)

static void	parse_from_state_set_vals (const char s, smartlist_t entries, smartlist_t extra, strmap_t vals)

static void	parse_from_state_handle_time (entry_guard_t guard, char sampled_on, char unlisted_since, char confirmed_on)

STATIC entry_guard_t *	entry_guard_parse_from_state (const char *s)

static void	entry_guards_update_guards_in_state (or_state_t *state)

static int	entry_guards_load_guards_from_state (or_state_t *state, int set)

entry_guard_t *	entry_guard_get_by_id_digest_for_guard_selection (guard_selection_t gs, const char digest)

const node_t *	entry_guard_find_node (const entry_guard_t *guard)

entry_guard_t *	entry_guard_get_by_id_digest (const char *digest)

circuit_guard_state_t *	get_guard_state_for_bridge_desc_fetch (const char *digest)

STATIC void	entry_guard_free_ (entry_guard_t *e)

int	entry_list_is_constrained (const or_options_t *options)

int	num_bridges_usable (int use_maybe_reachable)

int	entry_guards_parse_state (or_state_t state, int set, char *msg)

void	entry_guards_changed_for_guard_selection (guard_selection_t *gs)

void	entry_guards_changed (void)

void	entry_guards_update_state (or_state_t *state)

int	entry_guard_could_succeed (const circuit_guard_state_t *guard_state)

STATIC char *	getinfo_helper_format_single_entry_guard (const entry_guard_t *e)

int	getinfo_helper_entry_guards (control_connection_t conn, const char question, char answer, const char errmsg)

void	guard_get_guardfraction_bandwidth (guardfraction_bandwidth_t *guardfraction_bw, int orig_bandwidth, uint32_t guardfraction_percentage)

int	guards_update_all (void)

const node_t *	guards_choose_guard (const origin_circuit_t circ, cpath_build_state_t state, uint8_t purpose, circuit_guard_state_t **guard_state_out)

void	remove_all_entry_guards_for_guard_selection (guard_selection_t *gs)

void	remove_all_entry_guards (void)

const node_t *	guards_choose_dirguard (uint8_t dir_purpose, circuit_guard_state_t **guard_state_out)

int	guards_retry_optimistic (const or_options_t *options)

char *	guard_selection_get_err_str_if_dir_info_missing (guard_selection_t *gs, int using_mds, int num_present, int num_usable)

char *	entry_guards_get_err_str_if_dir_info_missing (int using_mds, int num_present, int num_usable)

STATIC void	guard_selection_free_ (guard_selection_t *gs)

bool	vanguards_lite_is_enabled (void)

static void	layer2_guard_free_ (layer2_guard_t *l2)

	CTASSERT (NUMBER_SECOND_GUARDS< 20)

static int	get_number_of_layer2_hs_guards (void)

static int	get_min_lifetime_of_layer2_hs_guards (void)

static int	get_max_lifetime_of_layer2_hs_guards (void)

static int	get_layer2_hs_guard_lifetime (void)

void	maintain_layer2_guards (void)

void	purge_vanguards_lite (void)

const routerset_t *	get_layer2_guards (void)

void	entry_guards_free_all (void)

parameters for networkstatus algorithm
These parameters are taken from the consensus; some are overrideable in the torrc.
STATIC double	get_max_sample_threshold (void)

STATIC int	get_max_sample_size_absolute (void)

STATIC int	get_min_filtered_sample_size (void)

STATIC int	get_remove_unlisted_guards_after_days (void)

static time_t	get_remove_unlisted_guards_after_seconds (void)

STATIC int	get_guard_lifetime (void)

STATIC int	get_guard_confirmed_min_lifetime (void)

STATIC int	get_n_primary_guards (void)

STATIC int	get_n_primary_guards_to_use (guard_usage_t usage)

STATIC int	get_internet_likely_down_interval (void)

STATIC int	get_nonprimary_guard_connect_timeout (void)

STATIC int	get_nonprimary_guard_idle_timeout (void)

STATIC double	get_meaningful_restriction_threshold (void)

STATIC double	get_extreme_restriction_threshold (void)

static void	mark_guard_maybe_reachable (entry_guard_t *guard)

STATIC void	mark_primary_guards_maybe_reachable (guard_selection_t *gs)

static void	mark_all_guards_maybe_reachable (guard_selection_t *gs)

Variables
static smartlist_t *	guard_contexts = NULL

static guard_selection_t *	curr_guard_context = NULL

static int	entry_guards_dirty = 0

static smartlist_t *	layer2_guards = NULL

static routerset_t *	layer2_routerset = NULL

Detailed Description

Code to manage our fixed first nodes for various functions.

Entry nodes can be guards (for general use) or bridges (for censorship circumvention).

In general, we use entry guards to prevent traffic-sampling attacks: if we chose every circuit independently, an adversary controlling some fraction of paths on the network would observe a sample of every user's traffic. Using guards gives users a chance of not being profiled.

The current entry guard selection code is designed to try to avoid ever trying every guard on the network, to try to stick to guards that we've used before, to handle hostile/broken networks, and to behave sanely when the network goes up and down.

Our algorithm works as follows: First, we maintain a SAMPLE of guards we've seen in the networkstatus consensus. We maintain this sample over time, and store it persistently; it is chosen without reference to our configuration or firewall rules. Guards remain in the sample as they enter and leave the consensus. We expand this sample as needed, up to a maximum size.

As a subset of the sample, we maintain a FILTERED SET of the guards that we would be willing to use if we could connect to them. The filter removes all the guards that we're excluding because they're bridges (or not bridges), because we have restrictive firewall rules, because of ExcludeNodes, because we of path bias restrictions, because they're absent from the network at present, and so on.

As a subset of the filtered set, we keep a REACHABLE FILTERED SET (also called a "usable filtered set") of those guards that we call "reachable" or "maybe reachable". A guard is reachable if we've connected to it more recently than we've failed. A guard is "maybe reachable" if we have never tried to connect to it, or if we failed to connect to it so long ago that we no longer think our failure means it's down.

As a persistent ordered list whose elements are taken from the sampled set, we track a CONFIRMED GUARDS LIST. A guard becomes confirmed when we successfully build a circuit through it, and decide to use that circuit.

And as a final group, we have an ordered list of PRIMARY GUARDS, whose elements are taken from the filtered set. We prefer confirmed guards to non-confirmed guards for this list, and place other restrictions on it. The primary guards are the ones that we connect to "when nothing is wrong" – circuits through them can be used immediately.

To build circuits, we take a primary guard if possible – or a reachable filtered confirmed guard if no primary guard is possible – or the first (by sampled order) filtered guard otherwise. If the guard is primary, we can use the circuit immediately on success. Otherwise, the guard is now "pending" – we won't use its circuit unless all of the circuits we're trying to build through better guards have definitely failed.

While we're building circuits, we track a little "guard state" for each circuit. We use this to keep track of whether the circuit is one that we can use as soon as it's done, or whether it's one that we should keep around to see if we can do better. In the latter case, a periodic call to entry_guards_upgrade_waiting_circuits() will eventually upgrade it.

Definition in file entrynodes.c.

Macro Definition Documentation

◆ ENTRYNODES_PRIVATE

#define ENTRYNODES_PRIVATE

Definition at line 116 of file entrynodes.c.

◆ FAST_GUARD_STATE_FLUSH_TIME

#define FAST_GUARD_STATE_FLUSH_TIME 30

How long will we let a change in our guard nodes stay un-saved when we are not trying to avoid disk writes?

Definition at line 3636 of file entrynodes.c.

◆ HANDLE_TIME

#define HANDLE_TIME ( field )

Value:

    do {                                 \
    if (field) {                                                \
      int r = parse_iso_time_nospace(field, &field ## _time);   \
      if (r < 0) {                                              \
        log_warn(LD_CIRC, "Unable to parse %s %s from guard",   \
                 #field, escaped(field));                       \
        field##_time = -1;                                      \
      }                                                         \
    }                                                           \
  } while (0)

◆ layer2_guard_free

#define layer2_guard_free ( val ) FREE_AND_NULL(layer2_guard_t, layer2_guard_free_, (val))

Definition at line 4076 of file entrynodes.c.

◆ MAX_SECOND_GUARD_LIFETIME

#define MAX_SECOND_GUARD_LIFETIME (3600*24*12)

Definition at line 4129 of file entrynodes.c.

◆ MIN_GUARDS_FOR_MD_RESTRICTION

#define MIN_GUARDS_FOR_MD_RESTRICTION 10

If we have fewer than this many possible usable guards, don't set MD-availability-based restrictions: we might denylist all of them.

Definition at line 1610 of file entrynodes.c.

◆ MIN_SECOND_GUARD_LIFETIME

#define MIN_SECOND_GUARD_LIFETIME (3600*24)

Lifetime of L2 guards: 1 to 12 days, for an average of a week using the max(x,x) distribution

Definition at line 4128 of file entrynodes.c.

◆ NUMBER_SECOND_GUARDS

#define NUMBER_SECOND_GUARDS 4

Number of L2 guards

Definition at line 4121 of file entrynodes.c.

◆ PB_FIELD [1/2]

#define PB_FIELD ( field )

Value:

      do {                                          \
      if (pb->field >= EPSILON) {                                       \
        smartlist_add_asprintf(result, "pb_" #field "=%f", pb->field);  \
      }                                                                 \
    } while (0)

◆ PB_FIELD [2/2]

#define PB_FIELD ( field )

Value:

  do {                                                                  \
    if (pb_ ## field) {                                                 \
      int ok = 1;                                                       \
      double r = tor_parse_double(pb_ ## field, 0.0, 1e9, &ok, NULL);   \
      if (! ok) {                                                       \
        log_warn(LD_CIRC, "Guard has invalid pb_%s %s",                 \
                 #field, pb_ ## field);                                 \
      } else {                                                          \
        guard->pb.field = r;                                            \
      }                                                                 \
    }                                                                   \
  } while (0)

◆ SLOW_GUARD_STATE_FLUSH_TIME

#define SLOW_GUARD_STATE_FLUSH_TIME 600

How long will we let a change in our guard nodes stay un-saved when we are trying to avoid disk writes?

Definition at line 3633 of file entrynodes.c.

Function Documentation

◆ bridge_passes_guard_filter()

static int bridge_passes_guard_filter	(	const or_options_t *	options,
		const bridge_info_t *	bridge
	)

static

Helper: Return true iff bridge passes our configuration filter– if it is a relay that we are configured to be able to connect to.

Definition at line 1499 of file entrynodes.c.

Referenced by entry_guard_passes_filter().

◆ choose_guard_selection()

STATIC const char * choose_guard_selection	(	const or_options_t *	options,
		const networkstatus_t *	live_ns,
		const guard_selection_t *	old_selection,
		guard_selection_type_t *	type_out
	)

Given our options and our list of nodes, return the name of the guard selection that we should use. Return NULL for "use the same selection you were using before.

Definition at line 636 of file entrynodes.c.

◆ circ_state_has_higher_priority()

static int circ_state_has_higher_priority	(	origin_circuit_t *	a,
		const entry_guard_restriction_t *	rst,
		origin_circuit_t *	b
	)

static

Wrapper for entry_guard_has_higher_priority that compares the guard-priorities of a pair of circuits. Return 1 if a has higher priority than b.

If a restriction is provided in rst, then do not consider a to have higher priority if it violates the restriction.

Definition at line 2720 of file entrynodes.c.

◆ circuit_guard_state_free_()

void circuit_guard_state_free_ ( circuit_guard_state_t * state )

Release all storage held in state.

Definition at line 2522 of file entrynodes.c.

◆ circuit_guard_state_new()

STATIC circuit_guard_state_t * circuit_guard_state_new	(	entry_guard_t *	guard,
		unsigned	state,
		entry_guard_restriction_t *	rst
	)

Allocate and return a new circuit_guard_state_t to track the result of using guard for a given operation.

Definition at line 2535 of file entrynodes.c.

Referenced by get_guard_state_for_bridge_desc_fetch().

◆ compare_guards_by_confirmed_idx()

static int compare_guards_by_confirmed_idx	(	const void **	a_,
		const void **	b_
	)

static

Definition at line 1847 of file entrynodes.c.

◆ compare_guards_by_sampled_idx()

static int compare_guards_by_sampled_idx	(	const void **	a_,
		const void **	b_
	)

static

Helper: compare two entry_guard_t by their sampled_idx values. Used to sort the sampled list

Definition at line 1862 of file entrynodes.c.

◆ create_initial_guard_context()

static void create_initial_guard_context ( void )

static

Allocate the first guard context that we're planning to use, and make it the current context.

Definition at line 290 of file entrynodes.c.

Referenced by get_guard_selection_info(), and update_guard_selection_choice().

◆ CTASSERT()

CTASSERT ( )

Make sure that the number of L2 guards is less than the number of MAX_SANE_RESTRICTED_NODES

Referenced by connection_proxy_state_to_string(), and resolved_addr_set_last().

◆ entry_guard_add_bridge_to_sample()

static entry_guard_t * entry_guard_add_bridge_to_sample	(	guard_selection_t *	gs,
		const bridge_info_t *	bridge
	)

static

Add an entry guard to the "bridges" guard selection sample, with information taken from bridge. Return that entry guard.

Definition at line 939 of file entrynodes.c.

◆ entry_guard_add_to_sample()

STATIC entry_guard_t * entry_guard_add_to_sample	(	guard_selection_t *	gs,
		const node_t *	node
	)

Allocate a new entry_guard_t object for node, add it to the sampled entry guards in gs, and return it. node must not currently be a sampled guard in gs.

Definition at line 864 of file entrynodes.c.

◆ entry_guard_add_to_sample_impl()

static entry_guard_t * entry_guard_add_to_sample_impl	(	guard_selection_t *	gs,
		const uint8_t *	rsa_id_digest,
		const char *	nickname,
		const tor_addr_port_t *	bridge_addrport
	)

static

Backend: adds a new sampled guard to gs, with given identity, nickname, and ORPort. rsa_id_digest and bridge_addrport are optional, but we need one of them. nickname is optional. The caller is responsible for maintaining the size limit of the SAMPLED_GUARDS set.

Definition at line 887 of file entrynodes.c.

◆ entry_guard_cancel()

void entry_guard_cancel ( circuit_guard_state_t ** guard_state_p )

Cancel the selection of *guard_state_p without declaring success or failure. It is safe to call this function if success or failure has already been declared.

Definition at line 2632 of file entrynodes.c.

◆ entry_guard_chan_failed()

void entry_guard_chan_failed ( channel_t * chan )

Run the entry_guard_failed() function on every circuit that is pending on chan.

Definition at line 2673 of file entrynodes.c.

◆ entry_guard_consider_retry()

STATIC void entry_guard_consider_retry ( entry_guard_t * guard )

If guard is unreachable, consider whether enough time has passed to consider it maybe-reachable again.

Definition at line 2082 of file entrynodes.c.

Referenced by entry_guard_set_filtered_flags(), entry_guards_all_primary_guards_are_down(), first_reachable_filtered_entry_guard(), and num_reachable_filtered_guards().

◆ entry_guard_could_succeed()

int entry_guard_could_succeed ( const circuit_guard_state_t * guard_state )

Return true iff the circuit's guard can succeed, that is, can be used.

Definition at line 3699 of file entrynodes.c.

◆ entry_guard_describe()

const char * entry_guard_describe ( const entry_guard_t * guard )

Return a statically allocated human-readable description of guard

Definition at line 324 of file entrynodes.c.

◆ entry_guard_encode_for_state()

STATIC char * entry_guard_encode_for_state	(	entry_guard_t *	guard,
		int	dense_sampled_idx
	)

Return a newly allocated string for encoding the persistent parts of guard to the state file. dense_sampled_idx refers to the sampled_idx made dense for this guard. Encoding all guards should lead to a dense array of sampled_idx in the state file.

Definition at line 2952 of file entrynodes.c.

◆ entry_guard_failed()

void entry_guard_failed ( circuit_guard_state_t ** guard_state_p )

Called by the circuit building module when a circuit has failed: informs the guards code that the guard in *guard_state_p is not working, and advances the state of the guard module.

Definition at line 2653 of file entrynodes.c.

Referenced by connection_dir_client_request_failed(), and entry_guard_chan_failed().

◆ entry_guard_find_node()

const node_t * entry_guard_find_node ( const entry_guard_t * guard )

Return the node_t associated with a single entry_guard_t. May return NULL if the guard is not currently in the consensus.

Definition at line 3450 of file entrynodes.c.

◆ entry_guard_free_()

STATIC void entry_guard_free_ ( entry_guard_t * e )

Release all storage held by e.

Definition at line 3494 of file entrynodes.c.

◆ entry_guard_get_by_id_digest()

entry_guard_t * entry_guard_get_by_id_digest ( const char * digest )

If digest matches the identity of any node in the entry_guards list for the default guard selection state, return that node. Else return NULL.

Definition at line 3460 of file entrynodes.c.

Referenced by pathbias_count_collapse(), pathbias_count_successful_close(), pathbias_count_timeout(), and pathbias_count_use_failed().

◆ entry_guard_get_by_id_digest_for_guard_selection()

entry_guard_t * entry_guard_get_by_id_digest_for_guard_selection	(	guard_selection_t *	gs,
		const char *	digest
	)

If digest matches the identity of any node in the entry_guards list for the provided guard selection state, return that node. Else return NULL.

Definition at line 3441 of file entrynodes.c.

Referenced by entry_guard_get_by_id_digest(), and get_guard_state_for_bridge_desc_fetch().

◆ entry_guard_get_pathbias_state()

guard_pathbias_t * entry_guard_get_pathbias_state ( entry_guard_t * guard )

Return the pathbias state associated with guard.

Definition at line 343 of file entrynodes.c.

Referenced by entry_guard_inc_circ_attempt_count(), pathbias_count_collapse(), pathbias_count_successful_close(), pathbias_count_timeout(), pathbias_count_use_failed(), pathbias_get_close_success_count(), pathbias_get_use_success_count(), pathbias_measure_close_rate(), pathbias_measure_use_rate(), pathbias_scale_close_rates(), and pathbias_scale_use_rates().

◆ entry_guard_get_rsa_id_digest()

const char * entry_guard_get_rsa_id_digest ( const entry_guard_t * guard )

Return guard's 20-byte RSA identity digest

Definition at line 336 of file entrynodes.c.

Referenced by pathbias_count_circs_in_states().

◆ entry_guard_has_higher_priority()

STATIC int entry_guard_has_higher_priority	(	entry_guard_t *	a,
		entry_guard_t *	b
	)

Helper: Return true iff a has higher priority than b.

Definition at line 2470 of file entrynodes.c.

Referenced by circ_state_has_higher_priority().

◆ entry_guard_is_listed()

STATIC int entry_guard_is_listed	(	guard_selection_t *	gs,
		const entry_guard_t *	guard
	)

Return true iff guard is currently "listed" – that is, it appears in the consensus, or as a configured bridge (as appropriate)

Definition at line 1272 of file entrynodes.c.

Referenced by sampled_guards_update_consensus_presence().

◆ entry_guard_learned_bridge_identity()

void entry_guard_learned_bridge_identity	(	const tor_addr_port_t *	addrport,
		const uint8_t *	rsa_id_digest
	)

Update the guard subsystem's knowledge of the identity of the bridge at addrport. Idempotent.

Definition at line 977 of file entrynodes.c.

◆ entry_guard_obeys_restriction()

static int entry_guard_obeys_restriction	(	const entry_guard_t *	guard,
		const entry_guard_restriction_t *	rst
	)

static

Return true iff guard obeys the restrictions defined in rst. (If rst is NULL, there are no restrictions.)

Definition at line 1700 of file entrynodes.c.

Referenced by circ_state_has_higher_priority(), and num_reachable_filtered_guards().

◆ entry_guard_parse_from_state()

STATIC entry_guard_t * entry_guard_parse_from_state ( const char * s )

Given a string generated by entry_guard_encode_for_state(), parse it (if possible) and return an entry_guard_t object for it. Return NULL on complete failure.

Definition at line 3115 of file entrynodes.c.

◆ entry_guard_passes_filter()

static int entry_guard_passes_filter	(	const or_options_t *	options,
		guard_selection_t *	gs,
		entry_guard_t *	guard
	)

static

Return true iff guard is a Tor relay that we are configured to be able to connect to, and we haven't disabled it for omission from the consensus or path bias issues.

Definition at line 1526 of file entrynodes.c.

Referenced by entry_guard_set_filtered_flags().

◆ entry_guard_pick_for_circuit()

int entry_guard_pick_for_circuit	(	guard_selection_t *	gs,
		guard_usage_t	usage,
		entry_guard_restriction_t *	rst,
		const node_t **	chosen_node_out,
		circuit_guard_state_t **	guard_state_out
	)

Pick a suitable entry guard for a circuit in, and place that guard in *chosen_node_out. Set *guard_state_out to an opaque state object that will record whether the circuit is ready to be used or not. Return 0 on success; on failure, return -1.

If a restriction is provided in rst, do not return any guards that violate it, and remember that restriction in guard_state_out for later use. (Takes ownership of the rst object.)

Definition at line 2559 of file entrynodes.c.

Referenced by guards_choose_dirguard().

◆ entry_guard_restriction_free_()

STATIC void entry_guard_restriction_free_ ( entry_guard_restriction_t * rst )

Release all storage held in restriction

Definition at line 2508 of file entrynodes.c.

◆ entry_guard_restriction_is_reachability()

static bool entry_guard_restriction_is_reachability ( const entry_guard_restriction_t * rst )

static

Return true if a restriction is reachability related, such that it should cause us to consider additional primary guards when selecting one.

Definition at line 1689 of file entrynodes.c.

◆ entry_guard_set_filtered_flags()

void entry_guard_set_filtered_flags	(	const or_options_t *	options,
		guard_selection_t *	gs,
		entry_guard_t *	guard
	)

static

Update the is_filtered_guard and is_usable_filtered_guard flags on guard.

Definition at line 1723 of file entrynodes.c.

Referenced by entry_guards_update_filtered_sets().

◆ entry_guard_state_should_expire()

int entry_guard_state_should_expire ( circuit_guard_state_t * guard_state )

Return true iff the circuit whose state is guard_state should expire.

Definition at line 2921 of file entrynodes.c.

Referenced by circuit_expire_waiting_for_better_guard().

◆ entry_guard_succeeded()

guard_usable_t entry_guard_succeeded ( circuit_guard_state_t ** guard_state_p )

Called by the circuit building module when a circuit has succeeded: informs the guards code that the guard in *guard_state_p is working, and advances the state of the guard module. On a GUARD_USABLE_NEVER return value, the circuit is broken and should not be used. On a GUARD_USABLE_NOW return value, the circuit is ready to use. On a GUARD_MAYBE_USABLE_LATER return value, the circuit should not be used until we find out whether preferred guards will work for us.

Definition at line 2605 of file entrynodes.c.

◆ entry_guards_all_primary_guards_are_down()

STATIC int entry_guards_all_primary_guards_are_down ( guard_selection_t * gs )

Return true iff every primary guard in gs is believed to be unreachable.

Definition at line 2699 of file entrynodes.c.

Referenced by entry_guards_upgrade_waiting_circuits().

◆ entry_guards_changed()

void entry_guards_changed ( void )

Our list of entry guards has changed for the default guard selection context, or some element of one of our entry guards has changed. Write the changes to disk within the next few minutes.

Definition at line 3672 of file entrynodes.c.

Referenced by entry_guard_inc_circ_attempt_count(), pathbias_count_collapse(), pathbias_count_successful_close(), pathbias_count_timeout(), pathbias_count_use_failed(), and pathbias_scale_close_rates().

◆ entry_guards_changed_for_guard_selection()

void entry_guards_changed_for_guard_selection ( guard_selection_t * gs )

Our list of entry guards has changed for a particular guard selection context, or some element of one of our entry guards has changed for one. Write the changes to disk within the next few minutes.

Definition at line 3643 of file entrynodes.c.

Referenced by entry_guards_changed().

◆ entry_guards_expand_sample()

STATIC entry_guard_t * entry_guards_expand_sample ( guard_selection_t * gs )

Add new guards to the sampled guards in gs until there are enough usable filtered guards, but never grow the sample beyond its maximum size. Return the last guard added, or NULL if none were added.

Definition at line 1178 of file entrynodes.c.

◆ entry_guards_free_all()

void entry_guards_free_all ( void )

Release all storage held by the list of entry guards and related memory structs.

Definition at line 4324 of file entrynodes.c.

◆ entry_guards_get_err_str_if_dir_info_missing()

char * entry_guards_get_err_str_if_dir_info_missing	(	int	using_mds,
		int	num_present,
		int	num_usable
	)

As guard_selection_have_enough_dir_info_to_build_circuits, but uses the default guard selection.

Definition at line 4032 of file entrynodes.c.

◆ entry_guards_load_guards_from_state()

static int entry_guards_load_guards_from_state	(	or_state_t *	state,
		int	set
	)

static

Replace our sampled guards from the Guards entries in state. Return 0 on success, -1 on failure. (If set is true, replace nothing – only check whether replacing would work.)

Guards should be in sample order within the file, but it is maybe better NOT to assume that. Let's order them before updating lists

Definition at line 3373 of file entrynodes.c.

Referenced by entry_guards_parse_state().

◆ entry_guards_note_guard_failure()

STATIC void entry_guards_note_guard_failure	(	guard_selection_t *	gs,
		entry_guard_t *	guard
	)

Note that we failed to connect to or build circuits through guard. Use with a guard returned by select_entry_guard_for_circuit().

Definition at line 2356 of file entrynodes.c.

◆ entry_guards_note_guard_success()

STATIC unsigned entry_guards_note_guard_success	(	guard_selection_t *	gs,
		entry_guard_t *	guard,
		unsigned	old_state
	)

Note that we successfully connected to, and built a circuit through guard. Given the old guard-state of the circuit in old_state, return the new guard-state of the circuit.

Be aware: the circuit is only usable when its guard-state becomes GUARD_CIRC_STATE_COMPLETE.

Definition at line 2393 of file entrynodes.c.

◆ entry_guards_note_internet_connectivity()

void entry_guards_note_internet_connectivity ( guard_selection_t * gs )

Tell the entry guards subsystem that we have confirmed that as of just now, we're on the internet.

Definition at line 2121 of file entrynodes.c.

◆ entry_guards_parse_state()

int entry_guards_parse_state	(	or_state_t *	state,
		int	set,
		char **	msg
	)

Parse state and learn about the entry guards it describes. If set is true, and there are no errors, replace the guard list in the default guard selection context with what we find. On success, return 0. On failure, alloc into *msg a string describing the error, and return -1.

Definition at line 3616 of file entrynodes.c.

◆ entry_guards_update_all()

int entry_guards_update_all ( guard_selection_t * gs )

Update all derived pieces of the guard selection state in gs. Return true iff we should stop using all previously generated circuits.

Definition at line 2936 of file entrynodes.c.

Referenced by guards_update_all().

◆ entry_guards_update_confirmed()

STATIC void entry_guards_update_confirmed ( guard_selection_t * gs )

Find the confirmed guards from among the sampled guards in gs, and put them in confirmed_entry_guards in the correct order. Recalculate their indices.

Needed to keep a dense array of confirmed_idx

Definition at line 1879 of file entrynodes.c.

Referenced by entry_guards_update_all().

◆ entry_guards_update_filtered_sets()

STATIC void entry_guards_update_filtered_sets ( guard_selection_t * gs )

Update the is_filtered_guard and is_usable_filtered_guard flag on every guard in gs.

Definition at line 1753 of file entrynodes.c.

Referenced by entry_guards_update_all().

◆ entry_guards_update_guards_in_state()

static void entry_guards_update_guards_in_state ( or_state_t * state )

static

Replace the Guards entries in state with a list of all our sampled guards.

Definition at line 3343 of file entrynodes.c.

Referenced by entry_guards_update_state().

◆ entry_guards_update_primary()

STATIC void entry_guards_update_primary ( guard_selection_t * gs )

Recalculate the list of primary guards (the ones we'd prefer to use) from the filtered sample and the confirmed list.

Definition at line 1944 of file entrynodes.c.

Referenced by entry_guards_all_primary_guards_are_down(), entry_guards_note_guard_success(), entry_guards_update_all(), guard_selection_get_err_str_if_dir_info_missing(), mark_primary_guards_maybe_reachable(), and select_entry_guard_for_circuit().

◆ entry_guards_update_state()

void entry_guards_update_state ( or_state_t * state )

If the entry guard info has not changed, do nothing and return. Otherwise, free the EntryGuards piece of state and create a new one out of the global entry_guards list, and then mark state dirty so it will get saved to disk.

Definition at line 3683 of file entrynodes.c.

◆ entry_guards_upgrade_waiting_circuits()

int entry_guards_upgrade_waiting_circuits	(	guard_selection_t *	gs,
		const smartlist_t *	all_circuits_in,
		smartlist_t *	newly_complete_out
	)

Look at all of the origin_circuit_t * objects in all_circuits_in, and see if any of them that were previously not ready to use for guard-related reasons are now ready to use. Place those circuits in newly_complete_out, and mark them COMPLETE.

Return 1 if we upgraded any circuits, and 0 otherwise.

Definition at line 2757 of file entrynodes.c.

◆ entry_list_is_constrained()

int entry_list_is_constrained ( const or_options_t * options )

Return 0 if we're fine adding arbitrary routers out of the directory to our entry guard list, or return 1 if we have a list already and we must stick to it.

Definition at line 3511 of file entrynodes.c.

Referenced by connection_dir_client_request_failed(), and guards_retry_optimistic().

◆ first_reachable_filtered_entry_guard()

STATIC entry_guard_t * first_reachable_filtered_entry_guard	(	guard_selection_t *	gs,
		const entry_guard_restriction_t *	rst,
		unsigned	flags
	)

Return the first sampled guard from the reachable filtered sample guards in gs, subject to the exclusion rules listed in flags. Return NULL if no such guard can be found.

Make sure that the sample is big enough, and that all the filter flags are set correctly, before calling this function.

If a restriction is provided in rst, do not return any guards that violate it.

Get the first guard of the filtered set builds from sampled_entry_guards. Proposal 310 suggests this design to overcome performance and security issues linked to the previous selection method. The guard selected here should be filtered out if this function is called again in the same context. I.e., if we filter guards to add them into some list X, then the guards from list X will be filtered out when this function is called again. Hence it requires setting exclude flags in a appropriate way (depending of the context of the caller).

Definition at line 1774 of file entrynodes.c.

◆ get_bridge_info_for_guard()

static bridge_info_t * get_bridge_info_for_guard ( const entry_guard_t * guard )

static

If we know a bridge_info_t matching guard, return that bridge. Otherwise return NULL.

Definition at line 834 of file entrynodes.c.

Referenced by entry_guard_is_listed(), and entry_guard_passes_filter().

◆ get_eligible_guards()

static smartlist_t * get_eligible_guards	(	const or_options_t *	options,
		guard_selection_t *	gs,
		int *	n_guards_out
	)

static

Return a smartlist of all the guards that are not currently members of the sample (GUARDS - SAMPLED_GUARDS). The elements of this list are node_t pointers in the non-bridge case, and bridge_info_t pointers in the bridge case. Set *n_guards_out to the number of guards that we found in GUARDS, including those that were already sampled.

Definition at line 1073 of file entrynodes.c.

◆ get_extreme_restriction_threshold()

STATIC double get_extreme_restriction_threshold ( void )

If our configuration retains fewer than this fraction of guards from the torrc, we are in an extremely restricted setting, and should warn.

Definition at line 562 of file entrynodes.c.

◆ get_guard_confirmed_min_lifetime()

STATIC int get_guard_confirmed_min_lifetime ( void )

We remove confirmed guards from the sample if they were sampled GUARD_LIFETIME_DAYS ago and confirmed this many days ago.

Definition at line 451 of file entrynodes.c.

◆ get_guard_lifetime()

STATIC int get_guard_lifetime ( void )

We remove unconfirmed guards from the sample after this many days, regardless of whether they are listed or unlisted.

Definition at line 436 of file entrynodes.c.

Referenced by entry_guard_add_to_sample_impl().

◆ get_guard_selection_by_name()

STATIC guard_selection_t * get_guard_selection_by_name	(	const char *	name,
		guard_selection_type_t	type,
		int	create_if_absent
	)

Return the guard selection called name. If there is none, and create_if_absent is true, then create and return it. If there is none, and create_if_absent is false, then return NULL.

Definition at line 263 of file entrynodes.c.

Referenced by entry_guard_learned_bridge_identity().

◆ get_guard_selection_info()

guard_selection_t * get_guard_selection_info ( void )

Get current default guard_selection_t, creating it if necessary

Definition at line 312 of file entrynodes.c.

Referenced by entry_guard_get_by_id_digest(), entry_guards_changed(), entry_guards_get_err_str_if_dir_info_missing(), get_guard_state_for_bridge_desc_fetch(), getinfo_helper_entry_guards(), guards_choose_dirguard(), guards_retry_optimistic(), remove_all_entry_guards(), and should_set_md_dirserver_restriction().

◆ get_guard_state_for_bridge_desc_fetch()

circuit_guard_state_t * get_guard_state_for_bridge_desc_fetch ( const char * digest )

We are about to connect to bridge with identity digest to fetch its descriptor. Create a new guard state for this connection and return it.

Definition at line 3469 of file entrynodes.c.

◆ get_internet_likely_down_interval()

STATIC int get_internet_likely_down_interval ( void )

If we haven't successfully built or used a circuit in this long, then consider that the internet is probably down.

Definition at line 513 of file entrynodes.c.

Referenced by entry_guards_note_guard_success().

◆ get_layer2_guards()

const routerset_t * get_layer2_guards ( void )

Return a routerset containing the L2 guards or NULL if it's not yet initialized. Callers must not free the routerset. Designed for use in pick_vanguard_middle_node() and should not be used anywhere else. Do not store this pointer – any future calls to maintain_layer2_guards() and purge_vanguards_lite() can invalidate it.

Definition at line 4310 of file entrynodes.c.

Referenced by pick_vanguard_middle_node().

◆ get_layer2_hs_guard_lifetime()

static int get_layer2_hs_guard_lifetime ( void )

static

Sample and return a lifetime for an L2 guard.

Lifetime randomized uniformly between min and max consensus params.

Definition at line 4167 of file entrynodes.c.

◆ get_max_lifetime_of_layer2_hs_guards()

static int get_max_lifetime_of_layer2_hs_guards ( void )

static

Return the maximum lifetime of L2 guards

Definition at line 4153 of file entrynodes.c.

Referenced by get_layer2_hs_guard_lifetime().

◆ get_max_sample_size()

static int get_max_sample_size	(	guard_selection_t *	gs,
		int	n_guards
	)

static

Return the actual maximum size for the sample in gs, given that we know about n_guards total.

Definition at line 1043 of file entrynodes.c.

◆ get_max_sample_size_absolute()

STATIC int get_max_sample_size_absolute ( void )

We never let our sampled guard set grow larger than this number.

Definition at line 393 of file entrynodes.c.

Referenced by entry_guard_parse_from_state(), and get_max_sample_size().

◆ get_max_sample_threshold()

STATIC double get_max_sample_threshold ( void )

We never let our sampled guard set grow larger than this fraction of the guards on the network.

Definition at line 381 of file entrynodes.c.

Referenced by get_max_sample_size().

◆ get_meaningful_restriction_threshold()

STATIC double get_meaningful_restriction_threshold ( void )

If our configuration retains fewer than this fraction of guards from the torrc, we are in a restricted setting.

Definition at line 549 of file entrynodes.c.

◆ get_min_filtered_sample_size()

STATIC int get_min_filtered_sample_size ( void )

We always try to make our sample contain at least this many guards.

Definition at line 403 of file entrynodes.c.

Referenced by get_max_sample_size().

◆ get_min_lifetime_of_layer2_hs_guards()

static int get_min_lifetime_of_layer2_hs_guards ( void )

static

Return the minimum lifetime of L2 guards

Definition at line 4143 of file entrynodes.c.

Referenced by get_layer2_hs_guard_lifetime().

◆ get_n_primary_guards()

STATIC int get_n_primary_guards ( void )

How many guards do we try to keep on our primary guard list?

Definition at line 465 of file entrynodes.c.

Referenced by entry_guards_update_primary().

◆ get_n_primary_guards_to_use()

STATIC int get_n_primary_guards_to_use ( guard_usage_t usage )

Return the number of the live primary guards we should look at when making a circuit.

Definition at line 485 of file entrynodes.c.

Referenced by guard_selection_get_err_str_if_dir_info_missing().

◆ get_nonprimary_guard_connect_timeout()

STATIC int get_nonprimary_guard_connect_timeout ( void )

If we're trying to connect to a nonprimary guard for at least this many seconds, and we haven't gotten the connection to work, we will treat lower-priority guards as usable.

Definition at line 525 of file entrynodes.c.

◆ get_nonprimary_guard_idle_timeout()

STATIC int get_nonprimary_guard_idle_timeout ( void )

If a circuit has been sitting around in 'waiting for better guard' state for at least this long, we'll expire it.

Definition at line 537 of file entrynodes.c.

Referenced by entry_guard_state_should_expire().

◆ get_number_of_layer2_hs_guards()

static int get_number_of_layer2_hs_guards ( void )

static

Return the number of guards our L2 guardset should have

Definition at line 4133 of file entrynodes.c.

◆ get_remove_unlisted_guards_after_days()

STATIC int get_remove_unlisted_guards_after_days ( void )

If a guard is unlisted for this many days in a row, we remove it.

Definition at line 413 of file entrynodes.c.

Referenced by get_remove_unlisted_guards_after_seconds().

◆ get_remove_unlisted_guards_after_seconds()

static time_t get_remove_unlisted_guards_after_seconds ( void )

static

Return number of seconds that will make a guard no longer eligible for selection if unlisted for this long.

Definition at line 426 of file entrynodes.c.

Referenced by sampled_guards_update_consensus_presence().

◆ get_retry_schedule()

static int get_retry_schedule	(	time_t	failing_since,
		time_t	now,
		int	is_primary
	)

static

Return the number of seconds after the last attempt at which we should retry a guard that has been failing since failing_since.

Definition at line 2040 of file entrynodes.c.

Referenced by entry_guard_consider_retry().

◆ get_sampled_guard_by_bridge_addr()

static entry_guard_t * get_sampled_guard_by_bridge_addr	(	guard_selection_t *	gs,
		const tor_addr_port_t *	addrport
	)

static

Return the entry_guard_t in gs whose address is addrport, or NULL if none exists.

Definition at line 959 of file entrynodes.c.

Referenced by entry_guard_learned_bridge_identity().

◆ get_sampled_guard_for_bridge()

static entry_guard_t * get_sampled_guard_for_bridge	(	guard_selection_t *	gs,
		const bridge_info_t *	bridge
	)

static

If gs contains a sampled entry guard matching bridge, return that guard. Otherwise return NULL.

Definition at line 816 of file entrynodes.c.

Referenced by get_eligible_guards().

◆ get_sampled_guard_with_id()

STATIC entry_guard_t * get_sampled_guard_with_id	(	guard_selection_t *	gs,
		const uint8_t *	rsa_id
	)

Return the sampled guard with the RSA identity digest rsa_id, or NULL if we don't have one.

Definition at line 801 of file entrynodes.c.

Referenced by entry_guard_get_by_id_digest_for_guard_selection(), and have_sampled_guard_with_id().

◆ getinfo_helper_entry_guards()

int getinfo_helper_entry_guards	(	control_connection_t *	conn,
		const char *	question,
		char **	answer,
		const char **	errmsg
	)

If question is the string "entry-guards", then dump to *answer a newly allocated string describing all of the nodes in the global entry_guards list. See control-spec.txt for details. For backward compatibility, we also handle the string "helper-nodes".

XXX this should be totally redesigned after prop 271 too, and that's going to take some control spec work.

Definition at line 3781 of file entrynodes.c.

◆ getinfo_helper_format_single_entry_guard()

STATIC char * getinfo_helper_format_single_entry_guard ( const entry_guard_t * e )

Format a single entry guard in the format expected by the controller. Return a newly allocated string.

Definition at line 3724 of file entrynodes.c.

Referenced by getinfo_helper_entry_guards().

◆ guard_create_conflux_restriction()

STATIC entry_guard_restriction_t * guard_create_conflux_restriction ( const origin_circuit_t * circ )

Definition at line 1598 of file entrynodes.c.

◆ guard_create_dirserver_md_restriction()

STATIC entry_guard_restriction_t * guard_create_dirserver_md_restriction ( void )

Allocate and return an outdated md guard restriction. Return NULL if no such restriction is needed.

Definition at line 1635 of file entrynodes.c.

Referenced by guards_choose_dirguard().

◆ guard_create_exit_restriction()

STATIC entry_guard_restriction_t * guard_create_exit_restriction ( const uint8_t * exit_id )

Definition at line 1586 of file entrynodes.c.

◆ guard_get_guardfraction_bandwidth()

void guard_get_guardfraction_bandwidth	(	guardfraction_bandwidth_t *	guardfraction_bw,
		int	orig_bandwidth,
		uint32_t	guardfraction_percentage
	)

Definition at line 3827 of file entrynodes.c.

◆ guard_has_descriptor()

static int guard_has_descriptor ( const entry_guard_t * guard )

static

Return true iff we know a preferred descriptor for guard

Definition at line 209 of file entrynodes.c.

Referenced by entry_guard_consider_retry().

◆ guard_in_node_family()

static int guard_in_node_family	(	const entry_guard_t *	guard,
		const node_t *	node
	)

static

Return true iff guard is in the same family as node.

Definition at line 1554 of file entrynodes.c.

◆ guard_obeys_exit_restriction()

static int guard_obeys_exit_restriction	(	const entry_guard_t *	guard,
		const entry_guard_restriction_t *	rst
	)

static

Definition at line 1653 of file entrynodes.c.

◆ guard_obeys_md_dirserver_restriction()

static int guard_obeys_md_dirserver_restriction ( const entry_guard_t * guard )

static

Return True if guard should be used as a dirserver for fetching microdescriptors.

Definition at line 1669 of file entrynodes.c.

◆ guard_selection_free_()

STATIC void guard_selection_free_ ( guard_selection_t * gs )

Free one guard selection context

Definition at line 4043 of file entrynodes.c.

◆ guard_selection_get_err_str_if_dir_info_missing()

char * guard_selection_get_err_str_if_dir_info_missing	(	guard_selection_t *	gs,
		int	using_mds,
		int	num_present,
		int	num_usable
	)

Check if we are missing any crucial dirinfo for the guard subsystem to work. Return NULL if everything went well, otherwise return a newly allocated string with an informative error message. In the latter case, use the general descriptor information using_mds, num_present and num_usable to improve the error message.

Definition at line 3985 of file entrynodes.c.

Referenced by entry_guards_get_err_str_if_dir_info_missing().

◆ guard_selection_infer_type()

STATIC guard_selection_type_t guard_selection_infer_type	(	guard_selection_type_t	type,
		const char *	name
	)

Try to determine the correct type for a selection named "name", if type is GS_TYPE_INFER.

Definition at line 222 of file entrynodes.c.

◆ guard_selection_new()

STATIC guard_selection_t * guard_selection_new	(	const char *	name,
		guard_selection_type_t	type
	)

Allocate and return a new guard_selection_t, with the name name.

Definition at line 240 of file entrynodes.c.

◆ guards_choose_dirguard()

const node_t * guards_choose_dirguard	(	uint8_t	dir_purpose,
		circuit_guard_state_t **	guard_state_out
	)

Helper: pick a directory guard, with whatever algorithm is used.

Definition at line 3942 of file entrynodes.c.

◆ guards_choose_guard()

const node_t * guards_choose_guard	(	const origin_circuit_t *	circ,
		cpath_build_state_t *	state,
		uint8_t	purpose,
		circuit_guard_state_t **	guard_state_out
	)

Helper: pick a guard for a circuit, with whatever algorithm is used.

Definition at line 3868 of file entrynodes.c.

◆ guards_retry_optimistic()

int guards_retry_optimistic ( const or_options_t * options )

If we're running with a constrained guard set, then maybe mark our guards usable. Return 1 if we do; 0 if we don't.

Definition at line 3968 of file entrynodes.c.

◆ guards_update_all()

int guards_update_all ( void )

Helper: Update the status of all entry guards, in whatever algorithm is used. Return true if we should stop using all previously generated circuits, by calling circuit_mark_all_unused_circs() and circuit_mark_all_dirty_circs_as_unusable().

Definition at line 3851 of file entrynodes.c.

Referenced by directory_info_has_arrived().

◆ have_sampled_guard_with_id()

static int have_sampled_guard_with_id	(	guard_selection_t *	gs,
		const uint8_t *	rsa_id
	)

inlinestatic

Return true iff we have a sampled guard with the RSA identity digest rsa_id.

Definition at line 853 of file entrynodes.c.

◆ layer2_guard_free_()

static void layer2_guard_free_ ( layer2_guard_t * l2 )

static

Definition at line 4104 of file entrynodes.c.

◆ maintain_layer2_guards()

void maintain_layer2_guards ( void )

Maintain the L2 guard list. Make sure the list contains enough guards, do expirations as necessary, and keep all the data structures of this subsystem synchronized

Definition at line 4183 of file entrynodes.c.

Referenced by get_layer2_guards(), and manage_vglite_callback().

◆ make_guard_confirmed()

STATIC void make_guard_confirmed	(	guard_selection_t *	gs,
		entry_guard_t *	guard
	)

Mark guard as a confirmed guard – that is, one that we have connected to, and intend to use again.

The confirmation ordering might not be the sample ordering. We need to reorder

Definition at line 1911 of file entrynodes.c.

Referenced by entry_guards_note_guard_success().

◆ mark_all_guards_maybe_reachable()

static void mark_all_guards_maybe_reachable ( guard_selection_t * gs )

static

Definition at line 619 of file entrynodes.c.

◆ mark_guard_maybe_reachable()

static void mark_guard_maybe_reachable ( entry_guard_t * guard )

static

Definition at line 573 of file entrynodes.c.

◆ mark_primary_guards_maybe_reachable()

STATIC void mark_primary_guards_maybe_reachable ( guard_selection_t * gs )

Called when the network comes up after having seemed to be down for a while: Mark the primary guards as maybe-reachable so that we'll try them again.

Definition at line 604 of file entrynodes.c.

Referenced by entry_guards_note_guard_success(), and guards_retry_optimistic().

◆ node_is_possible_guard()

static int node_is_possible_guard ( const node_t * node )

static

Return true iff node has all the flags needed for us to consider it a possible guard when sampling guards.

Definition at line 783 of file entrynodes.c.

Referenced by choose_guard_selection(), and entry_guard_is_listed().

◆ node_passes_guard_filter()

static int node_passes_guard_filter	(	const or_options_t *	options,
		const node_t *	node
	)

static

Return true iff node is a Tor relay that we are configured to be able to connect to.

Definition at line 1474 of file entrynodes.c.

Referenced by choose_guard_selection(), and entry_guard_passes_filter().

◆ num_bridges_usable()

int num_bridges_usable ( int use_maybe_reachable )

Return the number of bridges that have descriptors that are marked with purpose 'bridge' and are running. If use_maybe_reachable is true, include bridges that might be reachable in the count. Otherwise, if it is false, only include bridges that have recently been found running in the count.

We use this function to decide if we're ready to start building circuits through our bridges, or if we need to wait until the directory "server/authority" requests finish.

Definition at line 3531 of file entrynodes.c.

Referenced by learned_bridge_descriptor().

◆ num_reachable_filtered_guards()

STATIC int num_reachable_filtered_guards	(	const guard_selection_t *	gs,
		const entry_guard_restriction_t *	rst
	)

Return the number of sampled guards in gs that are "filtered" (that is, we're willing to connect to them) and that are "usable" (that is, either "reachable" or "maybe reachable").

If a restriction is provided in rst, do not count any guards that violate it.

Definition at line 1026 of file entrynodes.c.

Referenced by should_set_md_dirserver_restriction().

◆ parse_from_state_handle_time()

static void parse_from_state_handle_time	(	entry_guard_t *	guard,
		char *	sampled_on,
		char *	unlisted_since,
		char *	confirmed_on
	)

static

Handle part of the parsing state file logic, focused on time related things

Definition at line 3073 of file entrynodes.c.

◆ parse_from_state_set_vals()

static void parse_from_state_set_vals	(	const char *	s,
		smartlist_t *	entries,
		smartlist_t *	extra,
		strmap_t *	vals
	)

static

Extract key=val from the state string s and duplicate the value to some string target declared in entry_guard_parse_from_state

Definition at line 3042 of file entrynodes.c.

◆ pathbias_check_close_success_count()

static void pathbias_check_close_success_count ( entry_guard_t * node )

static

Check the pathbias close count of node and disable it if it goes over our thresholds.

Definition at line 3589 of file entrynodes.c.

◆ pathbias_check_use_success_count()

static void pathbias_check_use_success_count ( entry_guard_t * node )

static

Check the pathbias use success count of node and disable it if it goes over our thresholds.

Definition at line 3566 of file entrynodes.c.

◆ purge_vanguards_lite()

void purge_vanguards_lite ( void )

Reset vanguards-lite list(s).

Used for SIGNAL NEWNYM.

Definition at line 4288 of file entrynodes.c.

◆ randomize_time()

STATIC time_t randomize_time	(	time_t	now,
		time_t	max_backdate
	)

Return an interval between 'now' and 'max_backdate' seconds in the past, chosen uniformly at random. We use this before recording persistent dates, so that we aren't leaking exactly when we recorded it.

Definition at line 355 of file entrynodes.c.

◆ reasonably_live_consensus_is_missing()

static int reasonably_live_consensus_is_missing ( const guard_selection_t * gs )

static

Return true iff we need a consensus to update our guards, but we don't have one. (We can return 0 here either if the consensus is not missing, or if we don't need a consensus because we're using bridges.)

Definition at line 1159 of file entrynodes.c.

Referenced by entry_guards_expand_sample(), and sampled_guards_update_from_consensus().

◆ remove_all_entry_guards()

void remove_all_entry_guards ( void )

Remove all currently listed entry guards, so new ones will be chosen.

XXXX This function shouldn't exist – it's meant to support the DROPGUARDS command, which is deprecated.

Definition at line 3935 of file entrynodes.c.

◆ remove_all_entry_guards_for_guard_selection()

void remove_all_entry_guards_for_guard_selection ( guard_selection_t * gs )

Remove all currently listed entry guards for a given guard selection context. This frees and replaces gs, so don't use gs after calling this function.

Definition at line 3906 of file entrynodes.c.

Referenced by remove_all_entry_guards().

◆ remove_guard_from_confirmed_and_primary_lists()

static void remove_guard_from_confirmed_and_primary_lists	(	guard_selection_t *	gs,
		entry_guard_t *	guard
	)

static

Helper: guard has just been removed from the sampled guards: also remove it from primary and confirmed.

Definition at line 1243 of file entrynodes.c.

◆ sampled_guards_prune_obsolete_entries()

static size_t sampled_guards_prune_obsolete_entries	(	guard_selection_t *	gs,
		const time_t	remove_if_unlisted_since,
		const time_t	maybe_remove_if_sampled_before,
		const time_t	remove_if_confirmed_before
	)

static

Enumerate sampled_entry_guards smartlist in gs. For each entry_guard_t object in smartlist, do the following:

If currently_listed is false and unlisted_since_date is earlier than remove_if_unlisted_since - remove it.
Otherwise, check if sampled_on_date is earlier than maybe_remove_if_sampled_before.
- When above condition is correct, remove the guard if:
  - It was never confirmed.
  - It was confirmed before remove_if_confirmed_before.

Require gs to be non-null pointer. Return number of entries deleted.

Definition at line 1367 of file entrynodes.c.

◆ sampled_guards_update_consensus_presence()

static size_t sampled_guards_update_consensus_presence ( guard_selection_t * gs )

static

Enumerate sampled_entry_guards smartlist in gs. For each entry_guard_t object in smartlist, do the following:

Update currently_listed field to reflect if guard is listed in guard selection gs.
Set unlisted_since_date to approximate UNIX time of unlisting if guard is unlisted (randomize within 20% of get_remove_unlisted_guards_after_seconds()). Otherwise, set it to 0.

Require gs to be non-null pointer. Return a number of entries updated.

Definition at line 1297 of file entrynodes.c.

◆ sampled_guards_update_from_consensus()

STATIC void sampled_guards_update_from_consensus ( guard_selection_t * gs )

Update the status of all sampled guards based on the arrival of a new consensus networkstatus document. This will include marking some guards as listed or unlisted, and removing expired guards.

Definition at line 1427 of file entrynodes.c.

Referenced by entry_guards_update_all().

◆ select_and_add_guard_item_for_sample()

static entry_guard_t * select_and_add_guard_item_for_sample	(	guard_selection_t *	gs,
		smartlist_t *	eligible_guards
	)

static

Helper: given a smartlist of either bridge_info_t (if gs->type is GS_TYPE_BRIDGE) or node_t (otherwise), pick one that can be a guard, add it as a guard, remove it from the list, and return a new entry_guard_t. Return NULL on failure.

Definition at line 1131 of file entrynodes.c.

◆ select_confirmed_guard_for_circuit()

static entry_guard_t * select_confirmed_guard_for_circuit	(	guard_selection_t *	gs,
		guard_usage_t	usage,
		const entry_guard_restriction_t *	rst,
		unsigned *	state_out
	)

static

For use with a circuit, pick a non-pending running filtered confirmed guard, if one is available. Update the last_tried_to_connect time and the is_pending fields of the guard as appropriate. Set state_out to the new guard-state of the circuit.

Definition at line 2227 of file entrynodes.c.

◆ select_entry_guard_for_circuit()

STATIC entry_guard_t * select_entry_guard_for_circuit	(	guard_selection_t *	gs,
		guard_usage_t	usage,
		const entry_guard_restriction_t *	rst,
		unsigned *	state_out
	)

Get a guard for use with a circuit. Prefer to pick a running primary guard; then a non-pending running filtered confirmed guard; then a non-pending runnable filtered guard. Update the last_tried_to_connect time and the is_pending fields of the guard as appropriate. Set state_out to the new guard-state of the circuit.

Definition at line 2303 of file entrynodes.c.

Referenced by entry_guard_pick_for_circuit().

◆ select_filtered_guard_for_circuit()

static entry_guard_t * select_filtered_guard_for_circuit	(	guard_selection_t *	gs,
		guard_usage_t	usage,
		const entry_guard_restriction_t *	rst,
		unsigned *	state_out
	)

static

For use with a circuit, pick a usable filtered guard. Update the last_tried_to_connect time and the is_pending fields of the guard as appropriate. Set state_out to the new guard-state of the circuit.

Definition at line 2264 of file entrynodes.c.

◆ select_primary_guard_for_circuit()

static entry_guard_t * select_primary_guard_for_circuit	(	guard_selection_t *	gs,
		guard_usage_t	usage,
		const entry_guard_restriction_t *	rst,
		unsigned *	state_out
	)

static

Pick a primary guard for use with a circuit, if available. Update the last_tried_to_connect time and the is_pending fields of the guard as appropriate. Set state_out to the new guard-state of the circuit.

Definition at line 2133 of file entrynodes.c.

Referenced by select_entry_guard_for_circuit().

◆ should_apply_guardfraction()

int should_apply_guardfraction ( const networkstatus_t * ns )

Return 0 if we should apply guardfraction information found in the consensus. A specific consensus can be specified with the ns argument, if NULL the most recent one will be picked.

Definition at line 189 of file entrynodes.c.

◆ should_set_md_dirserver_restriction()

static int should_set_md_dirserver_restriction ( void )

static

Return true if we should set md dirserver restrictions. We might not want to set those if our guard options are too restricted, since we don't want to denylist all of them.

Definition at line 1616 of file entrynodes.c.

Referenced by guard_create_dirserver_md_restriction().

◆ update_guard_selection_choice()

int update_guard_selection_choice ( const or_options_t * options )

Check whether we should switch from our current guard selection to a different one. If so, switch and return 1. Return 0 otherwise.

On a 1 return, the caller should mark all currently live circuits unusable for new streams, by calling circuit_mark_all_unused_circs() and circuit_mark_all_dirty_circs_as_unusable().

Definition at line 742 of file entrynodes.c.

Referenced by guards_update_all().

◆ vanguards_lite_is_enabled()

bool vanguards_lite_is_enabled ( void )

Return true if the vanguards-lite subsystem is enabled

Definition at line 4081 of file entrynodes.c.

Referenced by middle_node_must_be_vanguard().

Variable Documentation

◆ curr_guard_context

guard_selection_t* curr_guard_context = NULL

static

The currently enabled guard selection context.

Definition at line 161 of file entrynodes.c.

Referenced by create_initial_guard_context(), entry_guards_free_all(), entry_guards_load_guards_from_state(), get_guard_selection_info(), guards_update_all(), and update_guard_selection_choice().

◆ entry_guards_dirty

int entry_guards_dirty = 0

static

A value of 1 means that at least one context has changed, and those changes need to be flushed to disk.

Definition at line 165 of file entrynodes.c.

Referenced by entry_guards_changed_for_guard_selection(), entry_guards_parse_state(), and entry_guards_update_state().

◆ guard_contexts

smartlist_t* guard_contexts = NULL

static

A list of existing guard selection contexts.

Definition at line 159 of file entrynodes.c.

Referenced by create_initial_guard_context(), entry_guards_free_all(), entry_guards_load_guards_from_state(), and entry_guards_update_guards_in_state().

◆ layer2_guards

smartlist_t* layer2_guards = NULL

static

Global list and routerset of L2 guards. They are both synced and they get updated periodically. We need both the list and the routerset: we use the smartlist to keep track of expiration times and the routerset is what we return to the users of this subsystem.

Definition at line 4117 of file entrynodes.c.

Referenced by get_layer2_guards(), maintain_layer2_guards(), and purge_vanguards_lite().

◆ layer2_routerset

routerset_t* layer2_routerset = NULL

static

Definition at line 4118 of file entrynodes.c.

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ENTRYNODES_PRIVATE

◆ FAST_GUARD_STATE_FLUSH_TIME

◆ HANDLE_TIME

◆ layer2_guard_free

◆ MAX_SECOND_GUARD_LIFETIME

◆ MIN_GUARDS_FOR_MD_RESTRICTION

◆ MIN_SECOND_GUARD_LIFETIME

◆ NUMBER_SECOND_GUARDS

◆ PB_FIELD [1/2]

◆ PB_FIELD [2/2]

◆ SLOW_GUARD_STATE_FLUSH_TIME

Function Documentation

◆ bridge_passes_guard_filter()

◆ choose_guard_selection()

◆ circ_state_has_higher_priority()

◆ circuit_guard_state_free_()

◆ circuit_guard_state_new()

◆ compare_guards_by_confirmed_idx()

◆ compare_guards_by_sampled_idx()

◆ create_initial_guard_context()

◆ CTASSERT()

◆ entry_guard_add_bridge_to_sample()

◆ entry_guard_add_to_sample()

◆ entry_guard_add_to_sample_impl()

◆ entry_guard_cancel()

◆ entry_guard_chan_failed()

◆ entry_guard_consider_retry()

◆ entry_guard_could_succeed()

◆ entry_guard_describe()

◆ entry_guard_encode_for_state()

◆ entry_guard_failed()

◆ entry_guard_find_node()

◆ entry_guard_free_()

◆ entry_guard_get_by_id_digest()

◆ entry_guard_get_by_id_digest_for_guard_selection()

◆ entry_guard_get_pathbias_state()

◆ entry_guard_get_rsa_id_digest()

◆ entry_guard_has_higher_priority()

◆ entry_guard_is_listed()

◆ entry_guard_learned_bridge_identity()

◆ entry_guard_obeys_restriction()

◆ entry_guard_parse_from_state()

◆ entry_guard_passes_filter()

◆ entry_guard_pick_for_circuit()

◆ entry_guard_restriction_free_()

◆ entry_guard_restriction_is_reachability()

◆ entry_guard_set_filtered_flags()

◆ entry_guard_state_should_expire()

◆ entry_guard_succeeded()

◆ entry_guards_all_primary_guards_are_down()

◆ entry_guards_changed()

◆ entry_guards_changed_for_guard_selection()

◆ entry_guards_expand_sample()

◆ entry_guards_free_all()

◆ entry_guards_get_err_str_if_dir_info_missing()

◆ entry_guards_load_guards_from_state()

◆ entry_guards_note_guard_failure()

◆ entry_guards_note_guard_success()

◆ entry_guards_note_internet_connectivity()

◆ entry_guards_parse_state()

◆ entry_guards_update_all()

◆ entry_guards_update_confirmed()

◆ entry_guards_update_filtered_sets()

◆ entry_guards_update_guards_in_state()

◆ entry_guards_update_primary()

◆ entry_guards_update_state()

◆ entry_guards_upgrade_waiting_circuits()

◆ entry_list_is_constrained()

◆ first_reachable_filtered_entry_guard()

◆ get_bridge_info_for_guard()

◆ get_eligible_guards()

◆ get_extreme_restriction_threshold()

◆ get_guard_confirmed_min_lifetime()

◆ get_guard_lifetime()