entrynodes.h File Reference

Header file for circuitbuild.c. More...

#include "handles.h"

Include dependency graph for entrynodes.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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_s	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
typedef struct guard_pathbias_t	guard_pathbias_t
typedef struct guardfraction_bandwidth_t	guardfraction_bandwidth_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)
	MOCK_DECL (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.

Typedef Documentation

guardfraction_bandwidth_t

typedef struct guardfraction_bandwidth_t guardfraction_bandwidth_t

Contains the bandwidth of a relay as a guard and as a non-guard after the guardfraction has been considered.

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.

Function Documentation

circuit_guard_state_free_()

void circuit_guard_state_free_

(

circuit_guard_state_t *

state

)

Release all storage held in state.

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.

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.

Here is the call graph for this function:

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.

entry_guard_describe()

const char* entry_guard_describe

(

const entry_guard_t *

guard

)

Return a statically allocated human-readable description of guard

Here is the call graph for this function:

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.

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.

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

Here is the caller graph for this function:

entry_guard_get_pathbias_state()

guard_pathbias_t* entry_guard_get_pathbias_state

(

entry_guard_t *

guard

)

Return the pathbias state associated with guard.

Here is the caller graph for this function:

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

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.

Here is the call graph for this function:

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.)

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Here is the call graph for this function:

Here is the caller graph for this function:

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.

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.

Here is the call graph for this function:

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.

Here is the caller graph for this function:

entry_guards_free_all()

void entry_guards_free_all

(

void

)

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

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

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.

Here is the call graph for this function:

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.

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.

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Here is the caller graph for this function:

get_guard_selection_info()

guard_selection_t* get_guard_selection_info

(

void

)

Get current default guard_selection_t, creating it if necessary

Here is the caller graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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 genreal descriptor information using_mds, num_present and num_usable to improve the error message.

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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().

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the caller graph for this function:

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.

Here is the caller graph for this function:

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().

Here is the caller graph for this function: