Header file for circuitbuild.c. More...

#include "lib/container/handles.h"

Data Structures
struct	guard_pathbias_t

struct	guardfraction_bandwidth_t

Macros
#define	circuit_guard_state_free(val) FREE_AND_NULL(circuit_guard_state_t, circuit_guard_state_free_, (val))

Typedefs
typedef struct guard_selection_t	guard_selection_t

typedef struct entry_guard_t	entry_guard_t

typedef struct circuit_guard_state_t	circuit_guard_state_t

typedef struct entry_guard_restriction_t	entry_guard_restriction_t

Enumerations
enum	guard_usage_t { GUARD_USAGE_TRAFFIC = 0 , GUARD_USAGE_DIRGUARD = 1 }

enum	guard_usable_t { GUARD_USABLE_NEVER = -1 , GUARD_MAYBE_USABLE_LATER = 0 , GUARD_USABLE_NOW = 1 }

Functions
int	guards_update_all (void)

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

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

entry_guard_t *	entry_guard_get_by_id_digest_for_guard_selection (guard_selection_t gs, const char digest)

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)

void	entry_guards_changed_for_guard_selection (guard_selection_t *gs)

void	entry_guards_changed (void)

guard_selection_t *	get_guard_selection_info (void)

int	num_live_entry_guards_for_guard_selection (guard_selection_t *gs, int for_directory)

int	num_live_entry_guards (int for_directory)

const node_t *	entry_guard_find_node (const entry_guard_t *guard)

const char *	entry_guard_get_rsa_id_digest (const entry_guard_t *guard)

const char *	entry_guard_describe (const entry_guard_t *guard)

guard_pathbias_t *	entry_guard_get_pathbias_state (entry_guard_t *guard)

void	circuit_guard_state_free_ (circuit_guard_state_t *state)

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_failed (circuit_guard_state_t **guard_state_p)

void	entry_guard_cancel (circuit_guard_state_t **guard_state_p)

void	entry_guard_chan_failed (channel_t *chan)

int	entry_guards_update_all (guard_selection_t *gs)

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

int	entry_guard_state_should_expire (circuit_guard_state_t *guard_state)

void	entry_guards_note_internet_connectivity (guard_selection_t *gs)

int	update_guard_selection_choice (const or_options_t *options)

int	entry_guard_could_succeed (const circuit_guard_state_t *guard_state)

int	num_bridges_usable (int use_maybe_reachable)

void	remove_all_entry_guards_for_guard_selection (guard_selection_t *gs)

void	remove_all_entry_guards (void)

void	entry_guard_learned_bridge_identity (const tor_addr_port_t addrport, const uint8_t rsa_id_digest)

int	entry_list_is_constrained (const or_options_t *options)

int	guards_retry_optimistic (const or_options_t *options)

int	entry_guards_parse_state_for_guard_selection (guard_selection_t gs, or_state_t state, int set, char **msg)

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

void	entry_guards_update_state (or_state_t *state)

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

int	entries_known_but_down (const or_options_t *options)

void	entries_retry_all (const or_options_t *options)

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

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

void	entry_guards_free_all (void)

double	pathbias_get_close_success_count (entry_guard_t *guard)

double	pathbias_get_use_success_count (entry_guard_t *guard)

int	should_apply_guardfraction (const networkstatus_t *ns)

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

Detailed Description

Header file for circuitbuild.c.

Definition in file entrynodes.h.

Enumeration Type Documentation

◆ guard_usage_t

enum guard_usage_t

Enum to specify how we're going to use a given guard, when we're picking one for immediate use.

Definition at line 372 of file entrynodes.h.

Function Documentation

◆ circuit_guard_state_free_()

void circuit_guard_state_free_ ( circuit_guard_state_t * state )

Release all storage held in state.

Definition at line 2403 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 2513 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 2554 of file entrynodes.c.

◆ 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 3575 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 319 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 2534 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 3331 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 3341 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 3322 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 338 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 331 of file entrynodes.c.

Referenced by pathbias_count_circs_in_states().

◆ 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 960 of file entrynodes.c.

◆ 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 2440 of file entrynodes.c.

Referenced by guards_choose_dirguard().

◆ 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 2802 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 2486 of file entrynodes.c.

◆ 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 3548 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 3524 of file entrynodes.c.

Referenced by entry_guards_changed().

◆ 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 3936 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 3903 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 2070 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 3497 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 2817 of file entrynodes.c.

Referenced by guards_update_all().

◆ 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 3559 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 2638 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 3392 of file entrynodes.c.

Referenced by connection_dir_client_request_failed(), and guards_retry_optimistic().

◆ 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 307 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 3350 of file entrynodes.c.

◆ 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 3657 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 3856 of file entrynodes.c.

Referenced by entry_guards_get_err_str_if_dir_info_missing().

◆ 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 3813 of file entrynodes.c.

◆ guards_choose_guard()

const node_t* guards_choose_guard	(	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 3744 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 3839 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 3727 of file entrynodes.c.

Referenced by directory_info_has_arrived().

◆ 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 3412 of file entrynodes.c.

Referenced by learned_bridge_descriptor().

◆ pathbias_get_close_success_count()

double pathbias_get_close_success_count ( entry_guard_t * guard )

Return the number of circuits counted as successfully closed for this guard.

Also add in the currently open circuits to give them the benefit of the doubt.

Definition at line 1297 of file circpathbias.c.

Referenced by pathbias_check_close_success_count(), and pathbias_measure_close_rate().

◆ pathbias_get_use_success_count()

double pathbias_get_use_success_count ( entry_guard_t * guard )

Return the number of circuits counted as successfully used this guard.

Also add in the currently open circuits that we are attempting to use to give them the benefit of the doubt.

Definition at line 1315 of file circpathbias.c.

Referenced by pathbias_check_use_success_count(), and pathbias_measure_use_rate().

◆ 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 3806 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 3777 of file entrynodes.c.

Referenced by remove_all_entry_guards().

◆ 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 184 of file entrynodes.c.

◆ 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 725 of file entrynodes.c.