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