entrynodes.h 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637
  1. /* Copyright (c) 2001 Matej Pfajfar.
  2. * Copyright (c) 2001-2004, Roger Dingledine.
  3. * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
  4. * Copyright (c) 2007-2017, The Tor Project, Inc. */
  5. /* See LICENSE for licensing information */
  6. /**
  7. * \file entrynodes.h
  8. * \brief Header file for circuitbuild.c.
  9. **/
  10. #ifndef TOR_ENTRYNODES_H
  11. #define TOR_ENTRYNODES_H
  12. #include "handles.h"
  13. /* Forward declare for guard_selection_t; entrynodes.c has the real struct */
  14. typedef struct guard_selection_s guard_selection_t;
  15. /* Forward declare for entry_guard_t; the real declaration is private. */
  16. typedef struct entry_guard_t entry_guard_t;
  17. /* Forward declaration for circuit_guard_state_t; the real declaration is
  18. private. */
  19. typedef struct circuit_guard_state_t circuit_guard_state_t;
  20. /* Forward declaration for entry_guard_restriction_t; the real declaration is
  21. private. */
  22. typedef struct entry_guard_restriction_t entry_guard_restriction_t;
  23. /* Information about a guard's pathbias status.
  24. * These fields are used in circpathbias.c to try to detect entry
  25. * nodes that are failing circuits at a suspicious frequency.
  26. */
  27. typedef struct guard_pathbias_t {
  28. unsigned int path_bias_noticed : 1; /**< Did we alert the user about path
  29. * bias for this node already? */
  30. unsigned int path_bias_warned : 1; /**< Did we alert the user about path bias
  31. * for this node already? */
  32. unsigned int path_bias_extreme : 1; /**< Did we alert the user about path
  33. * bias for this node already? */
  34. unsigned int path_bias_disabled : 1; /**< Have we disabled this node because
  35. * of path bias issues? */
  36. unsigned int path_bias_use_noticed : 1; /**< Did we alert the user about path
  37. * use bias for this node already? */
  38. unsigned int path_bias_use_extreme : 1; /**< Did we alert the user about path
  39. * use bias for this node already? */
  40. double circ_attempts; /**< Number of circuits this guard has "attempted" */
  41. double circ_successes; /**< Number of successfully built circuits using
  42. * this guard as first hop. */
  43. double successful_circuits_closed; /**< Number of circuits that carried
  44. * streams successfully. */
  45. double collapsed_circuits; /**< Number of fully built circuits that were
  46. * remotely closed before any streams were
  47. * attempted. */
  48. double unusable_circuits; /**< Number of circuits for which streams were
  49. * attempted, but none succeeded. */
  50. double timeouts; /**< Number of 'right-censored' circuit timeouts for this
  51. * guard. */
  52. double use_attempts; /**< Number of circuits we tried to use with streams */
  53. double use_successes; /**< Number of successfully used circuits using
  54. * this guard as first hop. */
  55. } guard_pathbias_t;
  56. #if defined(ENTRYNODES_PRIVATE)
  57. /**
  58. * @name values for entry_guard_t.is_reachable.
  59. *
  60. * See entry_guard_t.is_reachable for more information.
  61. */
  62. /**@{*/
  63. #define GUARD_REACHABLE_NO 0
  64. #define GUARD_REACHABLE_YES 1
  65. #define GUARD_REACHABLE_MAYBE 2
  66. /**@}*/
  67. /** An entry_guard_t represents our information about a chosen long-term
  68. * first hop, known as a "helper" node in the literature. We can't just
  69. * use a node_t, since we want to remember these even when we
  70. * don't have any directory info. */
  71. struct entry_guard_t {
  72. HANDLE_ENTRY(entry_guard, entry_guard_t);
  73. char nickname[MAX_HEX_NICKNAME_LEN+1];
  74. char identity[DIGEST_LEN];
  75. ed25519_public_key_t ed_id;
  76. /**
  77. * @name new guard selection algorithm fields.
  78. *
  79. * Only the new (prop271) algorithm uses these. For a more full
  80. * description of the algorithm, see the module documentation for
  81. * entrynodes.c
  82. */
  83. /**@{*/
  84. /* == Persistent fields, present for all sampled guards. */
  85. /** When was this guard added to the sample? */
  86. time_t sampled_on_date;
  87. /** Since what date has this guard been "unlisted"? A guard counts as
  88. * unlisted if we have a live consensus that does not include it, or
  89. * if we have a live consensus that does not include it as a usable
  90. * guard. This field is zero when the guard is listed. */
  91. time_t unlisted_since_date; // can be zero
  92. /** What version of Tor added this guard to the sample? */
  93. char *sampled_by_version;
  94. /** Is this guard listed right now? If this is set, then
  95. * unlisted_since_date should be set too. */
  96. unsigned currently_listed : 1;
  97. /* == Persistent fields, for confirmed guards only */
  98. /** When was this guard confirmed? (That is, when did we first use it
  99. * successfully and decide to keep it?) This field is zero if this is not a
  100. * confirmed guard. */
  101. time_t confirmed_on_date; /* 0 if not confirmed */
  102. /**
  103. * In what order was this guard confirmed? Guards with lower indices
  104. * appear earlier on the confirmed list. If the confirmed list is compacted,
  105. * this field corresponds to the index of this guard on the confirmed list.
  106. *
  107. * This field is set to -1 if this guard is not confirmed.
  108. */
  109. int confirmed_idx; /* -1 if not confirmed; otherwise the order that this
  110. * item should occur in the CONFIRMED_GUARDS ordered
  111. * list */
  112. /**
  113. * Which selection does this guard belong to?
  114. */
  115. char *selection_name;
  116. /** Bridges only: address of the bridge. */
  117. tor_addr_port_t *bridge_addr;
  118. /* ==== Non-persistent fields. */
  119. /* == These are used by sampled guards */
  120. /** When did we last decide to try using this guard for a circuit? 0 for
  121. * "not since we started up." */
  122. time_t last_tried_to_connect;
  123. /** How reachable do we consider this guard to be? One of
  124. * GUARD_REACHABLE_NO, GUARD_REACHABLE_YES, or GUARD_REACHABLE_MAYBE. */
  125. unsigned is_reachable : 2;
  126. /** Boolean: true iff this guard is pending. A pending guard is one
  127. * that we have an in-progress circuit through, and which we do not plan
  128. * to try again until it either succeeds or fails. Primary guards can
  129. * never be pending. */
  130. unsigned is_pending : 1;
  131. /** If true, don't write this guard to disk. (Used for bridges with unknown
  132. * identities) */
  133. unsigned is_persistent : 1;
  134. /** When did we get the earliest connection failure for this guard?
  135. * We clear this field on a successful connect. We do _not_ clear it
  136. * when we mark the guard as "MAYBE" reachable.
  137. */
  138. time_t failing_since;
  139. /* == Set inclusion flags. */
  140. /** If true, this guard is in the filtered set. The filtered set includes
  141. * all sampled guards that our configuration allows us to use. */
  142. unsigned is_filtered_guard : 1;
  143. /** If true, this guard is in the usable filtered set. The usable filtered
  144. * set includes all filtered guards that are not believed to be
  145. * unreachable. (That is, those for which is_reachable is not
  146. * GUARD_REACHABLE_NO) */
  147. unsigned is_usable_filtered_guard : 1;
  148. unsigned is_primary:1;
  149. /** This string holds any fields that we are maintaining because
  150. * we saw them in the state, even if we don't understand them. */
  151. char *extra_state_fields;
  152. /** Backpointer to the guard selection that this guard belongs to.
  153. * The entry_guard_t must never outlive its guard_selection. */
  154. guard_selection_t *in_selection;
  155. /**@}*/
  156. /** Path bias information for this guard. */
  157. guard_pathbias_t pb;
  158. };
  159. /**
  160. * Possible rules for a guard selection to follow
  161. */
  162. typedef enum guard_selection_type_t {
  163. /** Infer the type of this selection from its name. */
  164. GS_TYPE_INFER=0,
  165. /** Use the normal guard selection algorithm, taking our sample from the
  166. * complete list of guards in the consensus. */
  167. GS_TYPE_NORMAL=1,
  168. /** Use the normal guard selection algorithm, taking our sample from the
  169. * configured bridges, and allowing it to grow as large as all the configured
  170. * bridges */
  171. GS_TYPE_BRIDGE,
  172. /** Use the normal guard selection algorithm, taking our sample from the
  173. * set of filtered nodes. */
  174. GS_TYPE_RESTRICTED,
  175. } guard_selection_type_t;
  176. /**
  177. * All of the the context for guard selection on a particular client.
  178. *
  179. * We maintain multiple guard selection contexts for a client, depending
  180. * aspects on its current configuration -- whether an extremely
  181. * restrictive EntryNodes is used, whether UseBridges is enabled, and so
  182. * on.)
  183. *
  184. * See the module documentation for entrynodes.c for more information
  185. * about guard selection algorithms.
  186. */
  187. struct guard_selection_s {
  188. /**
  189. * The name for this guard-selection object. (Must not contain spaces).
  190. */
  191. char *name;
  192. /**
  193. * What rules does this guard-selection object follow?
  194. */
  195. guard_selection_type_t type;
  196. /**
  197. * A value of 1 means that primary_entry_guards is up-to-date with respect to
  198. * the consensus and status info that we currently have; 0 means we need to
  199. * recalculate it before using primary_entry_guards or the is_primary flag on
  200. * any guard.
  201. */
  202. int primary_guards_up_to_date;
  203. /**
  204. * A list of the sampled entry guards, as entry_guard_t structures.
  205. * Not in any particular order. When we 'sample' a guard, we are
  206. * noting it as a possible guard to pick in the future. The use of
  207. * sampling here prevents us from being forced by an attacker to try
  208. * every guard on the network. This list is persistent.
  209. */
  210. smartlist_t *sampled_entry_guards;
  211. /**
  212. * Ordered list (from highest to lowest priority) of guards that we
  213. * have successfully contacted and decided to use. Every member of
  214. * this list is a member of sampled_entry_guards. Every member should
  215. * have confirmed_on_date set, and have confirmed_idx greater than
  216. * any earlier member of the list.
  217. *
  218. * This list is persistent. It is a subset of the elements in
  219. * sampled_entry_guards, and its pointers point to elements of
  220. * sampled_entry_guards.
  221. */
  222. smartlist_t *confirmed_entry_guards;
  223. /**
  224. * Ordered list (from highest to lowest priority) of guards that we
  225. * are willing to use the most happily. These guards may or may not
  226. * yet be confirmed yet. If we can use one of these guards, we are
  227. * probably not on a network that is trying to restrict our guard
  228. * choices.
  229. *
  230. * This list is a subset of the elements in
  231. * sampled_entry_guards, and its pointers point to elements of
  232. * sampled_entry_guards.
  233. */
  234. smartlist_t *primary_entry_guards;
  235. /** When did we last successfully build a circuit or use a circuit? */
  236. time_t last_time_on_internet;
  237. /** What confirmed_idx value should the next-added member of
  238. * confirmed_entry_guards receive? */
  239. int next_confirmed_idx;
  240. };
  241. struct entry_guard_handle_t;
  242. /** Types of restrictions we impose when picking guard nodes */
  243. typedef enum guard_restriction_type_t {
  244. /* Don't pick the same guard node as our exit node (or its family) */
  245. RST_EXIT_NODE = 0,
  246. /* Don't pick dirguards that have previously shown to be outdated */
  247. RST_OUTDATED_MD_DIRSERVER = 1
  248. } guard_restriction_type_t;
  249. /**
  250. * A restriction to remember which entry guards are off-limits for a given
  251. * circuit.
  252. *
  253. * Note: This mechanism is NOT for recording which guards are never to be
  254. * used: only which guards cannot be used on <em>one particular circuit</em>.
  255. */
  256. struct entry_guard_restriction_t {
  257. /* What type of restriction are we imposing? */
  258. guard_restriction_type_t type;
  259. /* In case of restriction type RST_EXIT_NODE, the guard's RSA identity
  260. * digest must not equal this; and it must not be in the same family as any
  261. * node with this digest. */
  262. uint8_t exclude_id[DIGEST_LEN];
  263. };
  264. /**
  265. * Per-circuit state to track whether we'll be able to use the circuit.
  266. */
  267. struct circuit_guard_state_t {
  268. /** Handle to the entry guard object for this circuit. */
  269. struct entry_guard_handle_t *guard;
  270. /** The time at which <b>state</b> last changed. */
  271. time_t state_set_at;
  272. /** One of GUARD_CIRC_STATE_* */
  273. uint8_t state;
  274. /**
  275. * A set of restrictions that were placed on this guard when we selected it
  276. * for this particular circuit. We need to remember the restrictions here,
  277. * since any guard that breaks these restrictions will not block this
  278. * circuit from becoming COMPLETE.
  279. */
  280. entry_guard_restriction_t *restrictions;
  281. };
  282. #endif /* defined(ENTRYNODES_PRIVATE) */
  283. /* Common entry points for old and new guard code */
  284. int guards_update_all(void);
  285. const node_t *guards_choose_guard(cpath_build_state_t *state,
  286. circuit_guard_state_t **guard_state_out);
  287. const node_t *guards_choose_dirguard(uint8_t dir_purpose,
  288. circuit_guard_state_t **guard_state_out);
  289. #if 1
  290. /* XXXX NM I would prefer that all of this stuff be private to
  291. * entrynodes.c. */
  292. entry_guard_t *entry_guard_get_by_id_digest_for_guard_selection(
  293. guard_selection_t *gs, const char *digest);
  294. entry_guard_t *entry_guard_get_by_id_digest(const char *digest);
  295. circuit_guard_state_t *
  296. get_guard_state_for_bridge_desc_fetch(const char *digest);
  297. void entry_guards_changed_for_guard_selection(guard_selection_t *gs);
  298. void entry_guards_changed(void);
  299. guard_selection_t * get_guard_selection_info(void);
  300. int num_live_entry_guards_for_guard_selection(
  301. guard_selection_t *gs,
  302. int for_directory);
  303. int num_live_entry_guards(int for_directory);
  304. #endif /* 1 */
  305. const node_t *entry_guard_find_node(const entry_guard_t *guard);
  306. const char *entry_guard_get_rsa_id_digest(const entry_guard_t *guard);
  307. const char *entry_guard_describe(const entry_guard_t *guard);
  308. guard_pathbias_t *entry_guard_get_pathbias_state(entry_guard_t *guard);
  309. /** Enum to specify how we're going to use a given guard, when we're picking
  310. * one for immediate use. */
  311. typedef enum {
  312. GUARD_USAGE_TRAFFIC = 0,
  313. GUARD_USAGE_DIRGUARD = 1
  314. } guard_usage_t;
  315. #define circuit_guard_state_free(val) \
  316. FREE_AND_NULL(circuit_guard_state_t, circuit_guard_state_free_, (val))
  317. void circuit_guard_state_free_(circuit_guard_state_t *state);
  318. int entry_guard_pick_for_circuit(guard_selection_t *gs,
  319. guard_usage_t usage,
  320. entry_guard_restriction_t *rst,
  321. const node_t **chosen_node_out,
  322. circuit_guard_state_t **guard_state_out);
  323. /* We just connected to an entry guard. What should we do with the circuit? */
  324. typedef enum {
  325. GUARD_USABLE_NEVER = -1, /* Never use the circuit */
  326. GUARD_MAYBE_USABLE_LATER = 0, /* Keep it. We might use it in the future */
  327. GUARD_USABLE_NOW = 1, /* Use it right now */
  328. } guard_usable_t;
  329. guard_usable_t entry_guard_succeeded(circuit_guard_state_t **guard_state_p);
  330. void entry_guard_failed(circuit_guard_state_t **guard_state_p);
  331. void entry_guard_cancel(circuit_guard_state_t **guard_state_p);
  332. void entry_guard_chan_failed(channel_t *chan);
  333. int entry_guards_update_all(guard_selection_t *gs);
  334. int entry_guards_upgrade_waiting_circuits(guard_selection_t *gs,
  335. const smartlist_t *all_circuits,
  336. smartlist_t *newly_complete_out);
  337. int entry_guard_state_should_expire(circuit_guard_state_t *guard_state);
  338. void entry_guards_note_internet_connectivity(guard_selection_t *gs);
  339. int update_guard_selection_choice(const or_options_t *options);
  340. int entry_guard_could_succeed(const circuit_guard_state_t *guard_state);
  341. MOCK_DECL(int,num_bridges_usable,(int use_maybe_reachable));
  342. #ifdef ENTRYNODES_PRIVATE
  343. /**
  344. * @name Default values for the parameters for the new (prop271) entry guard
  345. * algorithm.
  346. */
  347. /**@{*/
  348. /**
  349. * We never let our sampled guard set grow larger than this percentage
  350. * of the guards on the network.
  351. */
  352. #define DFLT_MAX_SAMPLE_THRESHOLD_PERCENT 20
  353. /**
  354. * We never let our sampled guard set grow larger than this number of
  355. * guards.
  356. */
  357. #define DFLT_MAX_SAMPLE_SIZE 60
  358. /**
  359. * We always try to make our sample contain at least this many guards.
  360. */
  361. #define DFLT_MIN_FILTERED_SAMPLE_SIZE 20
  362. /**
  363. * If a guard is unlisted for this many days in a row, we remove it.
  364. */
  365. #define DFLT_REMOVE_UNLISTED_GUARDS_AFTER_DAYS 20
  366. /**
  367. * We remove unconfirmed guards from the sample after this many days,
  368. * regardless of whether they are listed or unlisted.
  369. */
  370. #define DFLT_GUARD_LIFETIME_DAYS 120
  371. /**
  372. * We remove confirmed guards from the sample if they were sampled
  373. * GUARD_LIFETIME_DAYS ago and confirmed this many days ago.
  374. */
  375. #define DFLT_GUARD_CONFIRMED_MIN_LIFETIME_DAYS 60
  376. /**
  377. * How many guards do we try to keep on our primary guard list?
  378. */
  379. #define DFLT_N_PRIMARY_GUARDS 3
  380. /**
  381. * Of the live guards on the primary guard list, how many do we consider when
  382. * choosing a guard to use?
  383. */
  384. #define DFLT_N_PRIMARY_GUARDS_TO_USE 1
  385. /**
  386. * As DFLT_N_PRIMARY_GUARDS, but for choosing which directory guard to use.
  387. */
  388. #define DFLT_N_PRIMARY_DIR_GUARDS_TO_USE 3
  389. /**
  390. * If we haven't successfully built or used a circuit in this long, then
  391. * consider that the internet is probably down.
  392. */
  393. #define DFLT_INTERNET_LIKELY_DOWN_INTERVAL (10*60)
  394. /**
  395. * If we're trying to connect to a nonprimary guard for at least this
  396. * many seconds, and we haven't gotten the connection to work, we will treat
  397. * lower-priority guards as usable.
  398. */
  399. #define DFLT_NONPRIMARY_GUARD_CONNECT_TIMEOUT 15
  400. /**
  401. * If a circuit has been sitting around in 'waiting for better guard' state
  402. * for at least this long, we'll expire it.
  403. */
  404. #define DFLT_NONPRIMARY_GUARD_IDLE_TIMEOUT (10*60)
  405. /**
  406. * If our configuration retains fewer than this fraction of guards from the
  407. * torrc, we are in a restricted setting.
  408. */
  409. #define DFLT_MEANINGFUL_RESTRICTION_PERCENT 20
  410. /**
  411. * If our configuration retains fewer than this fraction of guards from the
  412. * torrc, we are in an extremely restricted setting, and should warn.
  413. */
  414. #define DFLT_EXTREME_RESTRICTION_PERCENT 1
  415. /**@}*/
  416. STATIC double get_max_sample_threshold(void);
  417. STATIC int get_max_sample_size_absolute(void);
  418. STATIC int get_min_filtered_sample_size(void);
  419. STATIC int get_remove_unlisted_guards_after_days(void);
  420. STATIC int get_guard_lifetime(void);
  421. STATIC int get_guard_confirmed_min_lifetime(void);
  422. STATIC int get_n_primary_guards(void);
  423. STATIC int get_n_primary_guards_to_use(guard_usage_t usage);
  424. STATIC int get_internet_likely_down_interval(void);
  425. STATIC int get_nonprimary_guard_connect_timeout(void);
  426. STATIC int get_nonprimary_guard_idle_timeout(void);
  427. STATIC double get_meaningful_restriction_threshold(void);
  428. STATIC double get_extreme_restriction_threshold(void);
  429. HANDLE_DECL(entry_guard, entry_guard_t, STATIC)
  430. #define entry_guard_handle_free(h) \
  431. FREE_AND_NULL(entry_guard_handle_t, entry_guard_handle_free_, (h))
  432. STATIC guard_selection_type_t guard_selection_infer_type(
  433. guard_selection_type_t type_in,
  434. const char *name);
  435. STATIC guard_selection_t *guard_selection_new(const char *name,
  436. guard_selection_type_t type);
  437. STATIC guard_selection_t *get_guard_selection_by_name(
  438. const char *name, guard_selection_type_t type, int create_if_absent);
  439. STATIC void guard_selection_free_(guard_selection_t *gs);
  440. #define guard_selection_free(gs) \
  441. FREE_AND_NULL(guard_selection_t, guard_selection_free_, (gs))
  442. MOCK_DECL(STATIC int, entry_guard_is_listed,
  443. (guard_selection_t *gs, const entry_guard_t *guard));
  444. STATIC const char *choose_guard_selection(const or_options_t *options,
  445. const networkstatus_t *ns,
  446. const guard_selection_t *old_selection,
  447. guard_selection_type_t *type_out);
  448. STATIC entry_guard_t *get_sampled_guard_with_id(guard_selection_t *gs,
  449. const uint8_t *rsa_id);
  450. MOCK_DECL(STATIC time_t, randomize_time, (time_t now, time_t max_backdate));
  451. MOCK_DECL(STATIC circuit_guard_state_t *,
  452. circuit_guard_state_new,(entry_guard_t *guard, unsigned state,
  453. entry_guard_restriction_t *rst));
  454. STATIC entry_guard_t *entry_guard_add_to_sample(guard_selection_t *gs,
  455. const node_t *node);
  456. STATIC entry_guard_t *entry_guards_expand_sample(guard_selection_t *gs);
  457. STATIC char *entry_guard_encode_for_state(entry_guard_t *guard);
  458. STATIC entry_guard_t *entry_guard_parse_from_state(const char *s);
  459. #define entry_guard_free(e) \
  460. FREE_AND_NULL(entry_guard_t, entry_guard_free_, (e))
  461. STATIC void entry_guard_free_(entry_guard_t *e);
  462. STATIC void entry_guards_update_filtered_sets(guard_selection_t *gs);
  463. STATIC int entry_guards_all_primary_guards_are_down(guard_selection_t *gs);
  464. /**
  465. * @name Flags for sample_reachable_filtered_entry_guards()
  466. */
  467. /**@{*/
  468. #define SAMPLE_EXCLUDE_CONFIRMED (1u<<0)
  469. #define SAMPLE_EXCLUDE_PRIMARY (1u<<1)
  470. #define SAMPLE_EXCLUDE_PENDING (1u<<2)
  471. #define SAMPLE_NO_UPDATE_PRIMARY (1u<<3)
  472. #define SAMPLE_EXCLUDE_NO_DESCRIPTOR (1u<<4)
  473. /**@}*/
  474. STATIC entry_guard_t *sample_reachable_filtered_entry_guards(
  475. guard_selection_t *gs,
  476. const entry_guard_restriction_t *rst,
  477. unsigned flags);
  478. STATIC void entry_guard_consider_retry(entry_guard_t *guard);
  479. STATIC void make_guard_confirmed(guard_selection_t *gs, entry_guard_t *guard);
  480. STATIC void entry_guards_update_confirmed(guard_selection_t *gs);
  481. STATIC void entry_guards_update_primary(guard_selection_t *gs);
  482. STATIC int num_reachable_filtered_guards(const guard_selection_t *gs,
  483. const entry_guard_restriction_t *rst);
  484. STATIC void sampled_guards_update_from_consensus(guard_selection_t *gs);
  485. /**
  486. * @name Possible guard-states for a circuit.
  487. */
  488. /**@{*/
  489. /** State for a circuit that can (so far as the guard subsystem is
  490. * concerned) be used for actual traffic as soon as it is successfully
  491. * opened. */
  492. #define GUARD_CIRC_STATE_USABLE_ON_COMPLETION 1
  493. /** State for an non-open circuit that we shouldn't use for actual
  494. * traffic, when it completes, unless other circuits to preferable
  495. * guards fail. */
  496. #define GUARD_CIRC_STATE_USABLE_IF_NO_BETTER_GUARD 2
  497. /** State for an open circuit that we shouldn't use for actual traffic
  498. * unless other circuits to preferable guards fail. */
  499. #define GUARD_CIRC_STATE_WAITING_FOR_BETTER_GUARD 3
  500. /** State for a circuit that can (so far as the guard subsystem is
  501. * concerned) be used for actual traffic. */
  502. #define GUARD_CIRC_STATE_COMPLETE 4
  503. /** State for a circuit that is unusable, and will not become usable. */
  504. #define GUARD_CIRC_STATE_DEAD 5
  505. /**@}*/
  506. STATIC void entry_guards_note_guard_failure(guard_selection_t *gs,
  507. entry_guard_t *guard);
  508. STATIC entry_guard_t *select_entry_guard_for_circuit(guard_selection_t *gs,
  509. guard_usage_t usage,
  510. const entry_guard_restriction_t *rst,
  511. unsigned *state_out);
  512. STATIC void mark_primary_guards_maybe_reachable(guard_selection_t *gs);
  513. STATIC unsigned entry_guards_note_guard_success(guard_selection_t *gs,
  514. entry_guard_t *guard,
  515. unsigned old_state);
  516. STATIC int entry_guard_has_higher_priority(entry_guard_t *a, entry_guard_t *b);
  517. STATIC char *getinfo_helper_format_single_entry_guard(const entry_guard_t *e);
  518. STATIC entry_guard_restriction_t *guard_create_exit_restriction(
  519. const uint8_t *exit_id);
  520. STATIC entry_guard_restriction_t *guard_create_dirserver_md_restriction(void);
  521. STATIC void entry_guard_restriction_free_(entry_guard_restriction_t *rst);
  522. #define entry_guard_restriction_free(rst) \
  523. FREE_AND_NULL(entry_guard_restriction_t, \
  524. entry_guard_restriction_free_, (rst))
  525. #endif /* defined(ENTRYNODES_PRIVATE) */
  526. void remove_all_entry_guards_for_guard_selection(guard_selection_t *gs);
  527. void remove_all_entry_guards(void);
  528. struct bridge_info_t;
  529. void entry_guard_learned_bridge_identity(const tor_addr_port_t *addrport,
  530. const uint8_t *rsa_id_digest);
  531. int entry_list_is_constrained(const or_options_t *options);
  532. int guards_retry_optimistic(const or_options_t *options);
  533. int entry_guards_parse_state_for_guard_selection(
  534. guard_selection_t *gs, or_state_t *state, int set, char **msg);
  535. int entry_guards_parse_state(or_state_t *state, int set, char **msg);
  536. void entry_guards_update_state(or_state_t *state);
  537. int getinfo_helper_entry_guards(control_connection_t *conn,
  538. const char *question, char **answer,
  539. const char **errmsg);
  540. int entries_known_but_down(const or_options_t *options);
  541. void entries_retry_all(const or_options_t *options);
  542. char *entry_guards_get_err_str_if_dir_info_missing(int using_mds,
  543. int num_present, int num_usable);
  544. char *guard_selection_get_err_str_if_dir_info_missing(guard_selection_t *gs,
  545. int using_mds,
  546. int num_present, int num_usable);
  547. void entry_guards_free_all(void);
  548. double pathbias_get_close_success_count(entry_guard_t *guard);
  549. double pathbias_get_use_success_count(entry_guard_t *guard);
  550. /** Contains the bandwidth of a relay as a guard and as a non-guard
  551. * after the guardfraction has been considered. */
  552. typedef struct guardfraction_bandwidth_t {
  553. /** Bandwidth as a guard after guardfraction has been considered. */
  554. int guard_bw;
  555. /** Bandwidth as a non-guard after guardfraction has been considered. */
  556. int non_guard_bw;
  557. } guardfraction_bandwidth_t;
  558. int should_apply_guardfraction(const networkstatus_t *ns);
  559. void
  560. guard_get_guardfraction_bandwidth(guardfraction_bandwidth_t *guardfraction_bw,
  561. int orig_bandwidth,
  562. uint32_t guardfraction_percentage);
  563. #endif /* !defined(TOR_ENTRYNODES_H) */