tor  0.4.2.1-alpha-dev
Data Structures | Macros | Typedefs | Enumerations | Functions
entrynodes.h File Reference
#include "lib/container/handles.h"

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_tguards_choose_guard (cpath_build_state_t *state, uint8_t purpose, circuit_guard_state_t **guard_state_out)
 
const node_tguards_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_tentry_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_tentry_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.

Definition in file entrynodes.h.

Typedef Documentation

◆ 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 to specify how we're going to use a given guard, when we're picking one for immediate use.

Definition at line 358 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 2349 of file entrynodes.c.

References tor_free.

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

◆ entry_guard_chan_failed()

void entry_guard_chan_failed ( channel_t chan)

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

References DIGEST_LEN, hex_str(), and tor_snprintf().

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

References tor_assert().

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

References entry_guard_get_by_id_digest_for_guard_selection(), and get_guard_selection_info().

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

References get_sampled_guard_with_id().

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)

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

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

References DIGEST_LEN, get_guard_selection_by_name(), get_sampled_guard_by_bridge_addr(), tor_digest_is_zero(), and tor_memeq().

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

References select_entry_guard_for_circuit(), and tor_assert().

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

References approx_time(), and get_nonprimary_guard_idle_timeout().

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 2432 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 3430 of file entrynodes.c.

References entry_guards_changed_for_guard_selection(), and get_guard_selection_info().

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

References entry_guards_dirty, FAST_GUARD_STATE_FLUSH_TIME, or_state_mark_dirty(), SLOW_GUARD_STATE_FLUSH_TIME, and tor_assert().

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

References curr_guard_context, guard_contexts, and SMARTLIST_FOREACH_BEGIN.

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

References get_guard_selection_info(), and guard_selection_get_err_str_if_dir_info_missing().

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

References approx_time().

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

References entry_guards_dirty, and entry_guards_load_guards_from_state().

Referenced by or_state_validate().

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

References entry_guards_update_confirmed(), entry_guards_update_filtered_sets(), entry_guards_update_primary(), and sampled_guards_update_from_consensus().

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

References entry_guards_dirty, entry_guards_update_guards_in_state(), and or_state_mark_dirty().

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

References entry_guards_all_primary_guards_are_down(), and tor_assert().

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

References or_options_t::EntryNodes, and or_options_t::UseBridges.

Referenced by connection_dir_client_request_failed(), and guards_retry_optimistic().

◆ get_guard_selection_info()

guard_selection_t* get_guard_selection_info ( void  )

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

References approx_time(), entry_guard_get_by_id_digest_for_guard_selection(), and get_guard_selection_info().

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

References get_guard_selection_info(), getinfo_helper_format_single_entry_guard(), smartlist_add(), SMARTLIST_FOREACH_BEGIN, and tor_assert().

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

Definition at line 3732 of file entrynodes.c.

References entry_guards_update_primary(), and get_n_primary_guards_to_use().

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

References DIR_PURPOSE_FETCH_MICRODESC, entry_guard_pick_for_circuit(), get_guard_selection_info(), and guard_create_dirserver_md_restriction().

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

References build_state_get_exit_rsa_id(), and circuit_should_use_vanguards().

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

References entry_list_is_constrained(), get_guard_selection_info(), and mark_primary_guards_maybe_reachable().

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

References curr_guard_context, entry_guards_update_all(), tor_assert(), and update_guard_selection_choice().

Referenced by directory_info_has_arrived().

◆ 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 1292 of file circpathbias.c.

References entry_guard_get_pathbias_state(), pathbias_count_circs_in_states(), and guard_pathbias_t::successful_circuits_closed.

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 1310 of file circpathbias.c.

References entry_guard_get_pathbias_state(), pathbias_count_circs_in_states(), and guard_pathbias_t::use_successes.

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

References get_guard_selection_info(), and remove_all_entry_guards_for_guard_selection().

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

References tor_assert().

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

References or_options_t::UseGuardFraction.

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

References create_initial_guard_context(), and curr_guard_context.

Referenced by guards_update_all().