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-2016, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
9 * \brief Header file for circuitbuild.c.
12 #ifndef TOR_ENTRYNODES_H
13 #define TOR_ENTRYNODES_H
17 /* Forward declare for guard_selection_t; entrynodes.c has the real struct */
18 typedef struct guard_selection_s guard_selection_t
;
20 /* Forward declare for entry_guard_t; the real declaration is private. */
21 typedef struct entry_guard_t entry_guard_t
;
23 /* Forward declaration for circuit_guard_state_t; the real declaration is
25 typedef struct circuit_guard_state_t circuit_guard_state_t
;
27 /* Information about a guard's pathbias status.
28 * These fields are used in circpathbias.c to try to detect entry
29 * nodes that are failing circuits at a suspicious frequency.
31 typedef struct guard_pathbias_t
{
32 unsigned int path_bias_noticed
: 1; /**< Did we alert the user about path
33 * bias for this node already? */
34 unsigned int path_bias_warned
: 1; /**< Did we alert the user about path bias
35 * for this node already? */
36 unsigned int path_bias_extreme
: 1; /**< Did we alert the user about path
37 * bias for this node already? */
38 unsigned int path_bias_disabled
: 1; /**< Have we disabled this node because
39 * of path bias issues? */
40 unsigned int path_bias_use_noticed
: 1; /**< Did we alert the user about path
41 * use bias for this node already? */
42 unsigned int path_bias_use_extreme
: 1; /**< Did we alert the user about path
43 * use bias for this node already? */
45 double circ_attempts
; /**< Number of circuits this guard has "attempted" */
46 double circ_successes
; /**< Number of successfully built circuits using
47 * this guard as first hop. */
48 double successful_circuits_closed
; /**< Number of circuits that carried
49 * streams successfully. */
50 double collapsed_circuits
; /**< Number of fully built circuits that were
51 * remotely closed before any streams were
53 double unusable_circuits
; /**< Number of circuits for which streams were
54 * attempted, but none succeeded. */
55 double timeouts
; /**< Number of 'right-censored' circuit timeouts for this
57 double use_attempts
; /**< Number of circuits we tried to use with streams */
58 double use_successes
; /**< Number of successfully used circuits using
59 * this guard as first hop. */
62 #if defined(ENTRYNODES_PRIVATE)
64 * @name values for entry_guard_t.is_reachable.
66 * See entry_guard_t.is_reachable for more information.
69 #define GUARD_REACHABLE_NO 0
70 #define GUARD_REACHABLE_YES 1
71 #define GUARD_REACHABLE_MAYBE 2
74 /** An entry_guard_t represents our information about a chosen long-term
75 * first hop, known as a "helper" node in the literature. We can't just
76 * use a node_t, since we want to remember these even when we
77 * don't have any directory info. */
78 struct entry_guard_t
{
79 HANDLE_ENTRY(entry_guard
, entry_guard_t
);
81 char nickname
[MAX_HEX_NICKNAME_LEN
+1];
82 char identity
[DIGEST_LEN
];
83 ed25519_public_key_t ed_id
;
86 * @name new guard selection algorithm fields.
88 * Only the new (prop271) algorithm uses these. For a more full
89 * description of the algorithm, see the module documentation for
94 /* == Persistent fields, present for all sampled guards. */
95 /** When was this guard added to the sample? */
96 time_t sampled_on_date
;
97 /** Since what date has this guard been "unlisted"? A guard counts as
98 * unlisted if we have a live consensus that does not include it, or
99 * if we have a live consensus that does not include it as a usable
100 * guard. This field is zero when the guard is listed. */
101 time_t unlisted_since_date
; // can be zero
102 /** What version of Tor added this guard to the sample? */
103 char *sampled_by_version
;
104 /** Is this guard listed right now? If this is set, then
105 * unlisted_since_date should be set too. */
106 unsigned currently_listed
: 1;
108 /* == Persistent fields, for confirmed guards only */
109 /** When was this guard confirmed? (That is, when did we first use it
110 * successfully and decide to keep it?) This field is zero if this is not a
111 * confirmed guard. */
112 time_t confirmed_on_date
; /* 0 if not confirmed */
114 * In what order was this guard confirmed? Guards with lower indices
115 * appear earlier on the confirmed list. If the confirmed list is compacted,
116 * this field corresponds to the index of this guard on the confirmed list.
118 * This field is set to -1 if this guard is not confirmed.
120 int confirmed_idx
; /* -1 if not confirmed; otherwise the order that this
121 * item should occur in the CONFIRMED_GUARDS ordered
125 * Which selection does this guard belong to?
127 char *selection_name
;
128 guard_selection_t
*in_selection
;
130 /* ==== Non-persistent fields. */
131 /* == These are used by sampled guards */
132 /** When did we last decide to try using this guard for a circuit? 0 for
133 * "not since we started up." */
134 time_t last_tried_to_connect
;
135 /** How reachable do we consider this guard to be? One of
136 * GUARD_REACHABLE_NO, GUARD_REACHABLE_YES, or GUARD_REACHABLE_MAYBE. */
137 unsigned is_reachable
: 2;
138 /** Boolean: true iff this guard is pending. A pending guard is one
139 * that we have an in-progress circuit through, and which we do not plan
140 * to try again until it either succeeds or fails. Primary guards can
141 * never be pending. */
142 unsigned is_pending
: 1;
143 /** When did we get the earliest connection failure for this guard?
144 * We clear this field on a successful connect. We do _not_ clear it
145 * when we mark the guard as "MAYBE" reachable.
147 time_t failing_since
;
149 /* == Set inclusion flags. */
150 /** If true, this guard is in the filtered set. The filtered set includes
151 * all sampled guards that our configuration allows us to use. */
152 unsigned is_filtered_guard
: 1;
153 /** If true, this guard is in the usable filtered set. The usable filtered
154 * set includes all filtered guards that are not believed to be
155 * unreachable. (That is, those for which is_reachable is not
156 * GUARD_REACHABLE_NO) */
157 unsigned is_usable_filtered_guard
: 1;
158 unsigned is_primary
:1;
160 /** This string holds any fields that we are maintaining because
161 * we saw them in the state, even if we don't understand them. */
162 char *extra_state_fields
;
166 * @name legacy guard selection algorithm fields
168 * These are used and maintained by the legacy (pre-prop271) entry guard
169 * algorithm. Most of them we will remove as prop271 gets implemented.
170 * The rest we'll migrate over, if they are 100% semantically identical to
171 * their prop271 equivalents. XXXXprop271
174 time_t chosen_on_date
; /**< Approximately when was this guard added?
175 * "0" if we don't know. */
176 char *chosen_by_version
; /**< What tor version added this guard? NULL
177 * if we don't know. */
178 unsigned int made_contact
: 1; /**< 0 if we have never connected to this
179 * router, 1 if we have. */
180 unsigned int can_retry
: 1; /**< Should we retry connecting to this entry,
181 * in spite of having it marked as unreachable?*/
182 unsigned int is_dir_cache
: 1; /**< Is this node a directory cache? */
183 time_t bad_since
; /**< 0 if this guard is currently usable, or the time at
184 * which it was observed to become (according to the
185 * directory or the user configuration) unusable. */
186 time_t unreachable_since
; /**< 0 if we can connect to this guard, or the
187 * time at which we first noticed we couldn't
189 time_t last_attempted
; /**< 0 if we can connect to this guard, or the time
190 * at which we last failed to connect to it. */
194 /** Path bias information for this guard. */
199 * Possible rules for a guard selection to follow
201 typedef enum guard_selection_type_t
{
202 /** Infer the type of this selection from its name. */
204 /** Use the normal guard selection algorithm, taking our sample from the
205 * complete list of guards in the consensus. */
207 /** Use the normal guard selection algorithm, taking our sample from the
208 * configured bridges, and allowing it to grow as large as all the configured
211 /** Use the normal guard selection algorithm, taking our sample from the
212 * set of filtered nodes. */
214 /** Use the legacy (pre-prop271) guard selection algorithm and fields */
216 } guard_selection_type_t
;
219 * All of the the context for guard selection on a particular client.
221 * (XXXX prop271 this paragraph below is not actually implemented yet.)
222 * We maintain multiple guard selection contexts for a client, depending
223 * aspects on its current configuration -- whether an extremely
224 * restrictive EntryNodes is used, whether UseBridges is enabled, and so
227 * See the module documentation for entrynodes.c for more information
228 * about guard selection algorithms.
230 struct guard_selection_s
{
232 * The name for this guard-selection object. (Must not contain spaces).
237 * What rules does this guard-selection object follow?
239 guard_selection_type_t type
;
242 * A value of 1 means that primary_entry_guards is up-to-date; 0
243 * means we need to recalculate it before using primary_entry_guards
244 * or the is_primary flag on any guard.
246 int primary_guards_up_to_date
;
249 * A list of the sampled entry guards, as entry_guard_t structures.
250 * Not in any particular order. When we 'sample' a guard, we are
251 * noting it as a possible guard to pick in the future. The use of
252 * sampling here prevents us from being forced by an attacker to try
253 * every guard on the network. This list is persistent.
255 smartlist_t
*sampled_entry_guards
;
258 * Ordered list (from highest to lowest priority) of guards that we
259 * have successfully contacted and decided to use. Every member of
260 * this list is a member of sampled_entry_guards. Every member should
261 * have confirmed_on_date set, and have confirmed_idx greater than
262 * any earlier member of the list.
264 * This list is persistent. It is a subset of the elements in
265 * sampled_entry_guards, and its pointers point to elements of
266 * sampled_entry_guards.
268 smartlist_t
*confirmed_entry_guards
;
271 * Ordered list (from highest to lowest priority) of guards that we
272 * are willing to use the most happily. These guards may or may not
273 * yet be confirmed yet. If we can use one of these guards, we are
274 * probably not on a network that is trying to restrict our guard
277 * This list is a subset of the elements in
278 * sampled_entry_guards, and its pointers point to elements of
279 * sampled_entry_guards.
281 smartlist_t
*primary_entry_guards
;
283 /** When did we last successfully build a circuit or use a circuit? */
284 time_t last_time_on_internet
;
286 /** What confirmed_idx value should the next-added member of
287 * confirmed_entry_guards receive? */
288 int next_confirmed_idx
;
291 * A list of our chosen entry guards, as entry_guard_t structures; this
292 * preserves the pre-Prop271 behavior.
294 smartlist_t
*chosen_entry_guards
;
297 * When we try to choose an entry guard, should we parse and add
298 * config's EntryNodes first? This was formerly a global. This
299 * preserves the pre-Prop271 behavior.
301 int should_add_entry_nodes
;
304 struct entry_guard_handle_t
;
307 * Per-circuit state to track whether we'll be able to use the circuit.
309 struct circuit_guard_state_t
{
310 /** Handle to the entry guard object for this circuit. */
311 struct entry_guard_handle_t
*guard
;
312 /** The time at which <b>state</b> last changed. */
314 /** One of GUARD_CIRC_STATE_* */
319 /* Common entry points for old and new guard code */
320 int guards_update_all(void);
321 const node_t
*guards_choose_guard(cpath_build_state_t
*state
,
322 circuit_guard_state_t
**guard_state_out
);
323 const node_t
*guards_choose_dirguard(dirinfo_type_t info
,
324 circuit_guard_state_t
**guard_state_out
);
327 /* XXXX NM I would prefer that all of this stuff be private to
329 entry_guard_t
*entry_guard_get_by_id_digest_for_guard_selection(
330 guard_selection_t
*gs
, const char *digest
);
331 entry_guard_t
*entry_guard_get_by_id_digest(const char *digest
);
332 void entry_guards_changed_for_guard_selection(guard_selection_t
*gs
);
333 void entry_guards_changed(void);
334 guard_selection_t
* get_guard_selection_info(void);
335 const smartlist_t
*get_entry_guards_for_guard_selection(
336 guard_selection_t
*gs
);
337 const smartlist_t
*get_entry_guards(void);
338 int num_live_entry_guards_for_guard_selection(
339 guard_selection_t
*gs
,
341 int num_live_entry_guards(int for_directory
);
344 const node_t
*entry_guard_find_node(const entry_guard_t
*guard
);
345 void entry_guard_mark_bad(entry_guard_t
*guard
);
346 const char *entry_guard_get_rsa_id_digest(const entry_guard_t
*guard
);
347 const char *entry_guard_describe(const entry_guard_t
*guard
);
348 guard_pathbias_t
*entry_guard_get_pathbias_state(entry_guard_t
*guard
);
350 void circuit_guard_state_free(circuit_guard_state_t
*state
);
351 int entry_guard_pick_for_circuit(guard_selection_t
*gs
,
352 const node_t
**chosen_node_out
,
353 circuit_guard_state_t
**guard_state_out
);
354 int entry_guard_succeeded(guard_selection_t
*gs
,
355 circuit_guard_state_t
**guard_state_p
);
356 void entry_guard_failed(guard_selection_t
*gs
,
357 circuit_guard_state_t
**guard_state_p
);
358 void entry_guard_cancel(guard_selection_t
*gs
,
359 circuit_guard_state_t
**guard_state_p
);
360 void entry_guard_chan_failed(guard_selection_t
*gs
,
362 int entry_guards_update_all(guard_selection_t
*gs
);
363 int entry_guards_upgrade_waiting_circuits(guard_selection_t
*gs
,
364 const smartlist_t
*all_circuits
,
365 smartlist_t
*newly_complete_out
);
366 int entry_guard_state_should_expire(circuit_guard_state_t
*guard_state
);
367 void entry_guards_note_internet_connectivity(guard_selection_t
*gs
);
369 int update_guard_selection_choice(const or_options_t
*options
);
371 /* Used by bridges.c only. */
372 void add_bridge_as_entry_guard(guard_selection_t
*gs
,
373 const node_t
*chosen
);
374 int num_bridges_usable(void);
376 #ifdef ENTRYNODES_PRIVATE
378 * @name Default values for the parameters for the new (prop271) entry guard
383 * We never let our sampled guard set grow larger than this percentage
384 * of the guards on the network.
386 #define DFLT_MAX_SAMPLE_THRESHOLD_PERCENT 30
388 * We always try to make our sample contain at least this many guards.
390 * XXXX prop271 There was a MIN_SAMPLE_THRESHOLD in the proposal, but I
391 * removed it in favor of MIN_FILTERED_SAMPLE_SIZE. -NM
393 #define DFLT_MIN_FILTERED_SAMPLE_SIZE 20
395 * If a guard is unlisted for this many days in a row, we remove it.
397 #define DFLT_REMOVE_UNLISTED_GUARDS_AFTER_DAYS 20
399 * We remove unconfirmed guards from the sample after this many days,
400 * regardless of whether they are listed or unlisted.
402 #define DFLT_GUARD_LIFETIME_DAYS 120
404 * We remove confirmed guards from the sample if they were sampled
405 * GUARD_LIFETIME_DAYS ago and confirmed this many days ago.
407 #define DFLT_GUARD_CONFIRMED_MIN_LIFETIME_DAYS 60
409 * How many guards do we try to keep on our primary guard list?
411 #define DFLT_N_PRIMARY_GUARDS 3
413 * If we haven't successfully built or used a circuit in this long, then
414 * consider that the internet is probably down.
416 #define DFLT_INTERNET_LIKELY_DOWN_INTERVAL (10*60)
418 * If we're trying to connect to a nonprimary guard for at least this
419 * many seconds, and we haven't gotten the connection to work, we will treat
420 * lower-priority guards as usable.
422 #define DFLT_NONPRIMARY_GUARD_CONNECT_TIMEOUT 15
424 * If a circuit has been sitting around in 'waiting for better guard' state
425 * for at least this long, we'll expire it.
427 #define DFLT_NONPRIMARY_GUARD_IDLE_TIMEOUT (10*60)
429 * If our configuration retains fewer than this fraction of guards from the
430 * torrc, we are in a restricted setting.
432 #define DFLT_MEANINGFUL_RESTRICTION_PERCENT 20
434 * If our configuration retains fewer than this fraction of guards from the
435 * torrc, we are in an extremely restricted setting, and should warn.
437 #define DFLT_EXTREME_RESTRICTION_PERCENT 1
440 STATIC
double get_max_sample_threshold(void);
441 STATIC
int get_min_filtered_sample_size(void);
442 STATIC
int get_remove_unlisted_guards_after_days(void);
443 STATIC
int get_guard_lifetime_days(void);
444 STATIC
int get_guard_confirmed_min_lifetime_days(void);
445 STATIC
int get_n_primary_guards(void);
446 STATIC
int get_internet_likely_down_interval(void);
447 STATIC
int get_nonprimary_guard_connect_timeout(void);
448 STATIC
int get_nonprimary_guard_idle_timeout(void);
449 STATIC
double get_meaningful_restriction_threshold(void);
450 STATIC
double get_extreme_restriction_threshold(void);
452 // ---------- XXXX these functions and definitions are post-prop271.
453 HANDLE_DECL(entry_guard
, entry_guard_t
, STATIC
)
454 STATIC guard_selection_t
*guard_selection_new(const char *name
,
455 guard_selection_type_t type
);
456 STATIC guard_selection_t
*get_guard_selection_by_name(
457 const char *name
, guard_selection_type_t type
, int create_if_absent
);
458 STATIC
void guard_selection_free(guard_selection_t
*gs
);
459 STATIC
const char *choose_guard_selection(const or_options_t
*options
,
460 const networkstatus_t
*ns
,
461 const char *old_selection
,
462 guard_selection_type_t
*type_out
);
463 STATIC entry_guard_t
*get_sampled_guard_with_id(guard_selection_t
*gs
,
464 const uint8_t *rsa_id
);
466 MOCK_DECL(STATIC
time_t, randomize_time
, (time_t now
, time_t max_backdate
));
467 STATIC entry_guard_t
*entry_guard_add_to_sample(guard_selection_t
*gs
,
469 STATIC entry_guard_t
*entry_guards_expand_sample(guard_selection_t
*gs
);
470 STATIC
char *entry_guard_encode_for_state(entry_guard_t
*guard
);
471 STATIC entry_guard_t
*entry_guard_parse_from_state(const char *s
);
472 STATIC
void entry_guard_free(entry_guard_t
*e
);
473 STATIC
void entry_guards_update_filtered_sets(guard_selection_t
*gs
);
474 STATIC
int entry_guards_all_primary_guards_are_down(guard_selection_t
*gs
);
476 * @name Flags for sample_reachable_filtered_entry_guards()
479 #define SAMPLE_EXCLUDE_CONFIRMED (1u<<0)
480 #define SAMPLE_EXCLUDE_PRIMARY (1u<<1)
481 #define SAMPLE_EXCLUDE_PENDING (1u<<2)
482 #define SAMPLE_NO_UPDATE_PRIMARY (1u<<3)
484 STATIC entry_guard_t
*sample_reachable_filtered_entry_guards(
485 guard_selection_t
*gs
,
487 STATIC
void entry_guard_consider_retry(entry_guard_t
*guard
);
488 STATIC
void make_guard_confirmed(guard_selection_t
*gs
, entry_guard_t
*guard
);
489 STATIC
void entry_guards_update_confirmed(guard_selection_t
*gs
);
490 STATIC
void entry_guards_update_primary(guard_selection_t
*gs
);
491 STATIC
int num_reachable_filtered_guards(guard_selection_t
*gs
);
492 STATIC
void sampled_guards_update_from_consensus(guard_selection_t
*gs
);
494 * @name Possible guard-states for a circuit.
497 /** State for a circuit that can (so far as the guard subsystem is
498 * concerned) be used for actual traffic as soon as it is successfully
500 #define GUARD_CIRC_STATE_USABLE_ON_COMPLETION 1
501 /** State for an non-open circuit that we shouldn't use for actual
502 * traffic, when it completes, unless other circuits to preferable
504 #define GUARD_CIRC_STATE_USABLE_IF_NO_BETTER_GUARD 2
505 /** State for an open circuit that we shouldn't use for actual traffic
506 * unless other circuits to preferable guards fail. */
507 #define GUARD_CIRC_STATE_WAITING_FOR_BETTER_GUARD 3
508 /** State for a circuit that can (so far as the guard subsystem is
509 * concerned) be used for actual traffic. */
510 #define GUARD_CIRC_STATE_COMPLETE 4
511 /** State for a circuit that is unusable, and will not become usable. */
512 #define GUARD_CIRC_STATE_DEAD 5
514 STATIC
void entry_guards_note_guard_failure(guard_selection_t
*gs
,
515 entry_guard_t
*guard
);
516 STATIC entry_guard_t
*select_entry_guard_for_circuit(guard_selection_t
*gs
,
517 unsigned *state_out
);
518 STATIC
void mark_primary_guards_maybe_reachable(guard_selection_t
*gs
);
519 STATIC
unsigned entry_guards_note_guard_success(guard_selection_t
*gs
,
520 entry_guard_t
*guard
,
522 STATIC
int entry_guard_has_higher_priority(entry_guard_t
*a
, entry_guard_t
*b
);
524 // ---------- XXXX this stuff is pre-prop271.
526 STATIC
const node_t
*add_an_entry_guard(guard_selection_t
*gs
,
527 const node_t
*chosen
,
528 int reset_status
, int prepend
,
529 int for_discovery
, int for_directory
);
530 STATIC
int populate_live_entry_guards(smartlist_t
*live_entry_guards
,
531 const smartlist_t
*all_entry_guards
,
532 const node_t
*chosen_exit
,
533 dirinfo_type_t dirinfo_type
,
535 int need_uptime
, int need_capacity
);
536 STATIC
int decide_num_guards(const or_options_t
*options
, int for_directory
);
538 STATIC
void entry_guards_set_from_config(guard_selection_t
*gs
,
539 const or_options_t
*options
);
541 /** Flags to be passed to entry_is_live() to indicate what kind of
542 * entry nodes we are looking for. */
544 ENTRY_NEED_UPTIME
= 1<<0,
545 ENTRY_NEED_CAPACITY
= 1<<1,
546 ENTRY_ASSUME_REACHABLE
= 1<<2,
547 ENTRY_NEED_DESCRIPTOR
= 1<<3,
548 } entry_is_live_flags_t
;
550 STATIC
const node_t
*entry_is_live(const entry_guard_t
*e
,
551 entry_is_live_flags_t flags
,
554 STATIC
int entry_is_time_to_retry(const entry_guard_t
*e
, time_t now
);
558 void remove_all_entry_guards_for_guard_selection(guard_selection_t
*gs
);
559 void remove_all_entry_guards(void);
561 void entry_guards_compute_status_for_guard_selection(
562 guard_selection_t
*gs
, const or_options_t
*options
, time_t now
);
563 void entry_guards_compute_status(const or_options_t
*options
, time_t now
);
564 int entry_guard_register_connect_status_for_guard_selection(
565 guard_selection_t
*gs
, const char *digest
, int succeeded
,
566 int mark_relay_status
, time_t now
);
567 int entry_guard_register_connect_status(const char *digest
, int succeeded
,
568 int mark_relay_status
, time_t now
);
569 void entry_nodes_should_be_added_for_guard_selection(guard_selection_t
*gs
);
570 void entry_nodes_should_be_added(void);
571 int entry_list_is_constrained(const or_options_t
*options
);
572 const node_t
*choose_random_entry(cpath_build_state_t
*state
);
573 const node_t
*choose_random_dirguard(dirinfo_type_t t
);
574 int entry_guards_parse_state_for_guard_selection(
575 guard_selection_t
*gs
, or_state_t
*state
, int set
, char **msg
);
576 int entry_guards_parse_state(or_state_t
*state
, int set
, char **msg
);
577 void entry_guards_update_state(or_state_t
*state
);
578 int getinfo_helper_entry_guards(control_connection_t
*conn
,
579 const char *question
, char **answer
,
580 const char **errmsg
);
581 int is_node_used_as_guard_for_guard_selection(guard_selection_t
*gs
,
583 MOCK_DECL(int, is_node_used_as_guard
, (const node_t
*node
));
585 int entries_known_but_down(const or_options_t
*options
);
586 void entries_retry_all(const or_options_t
*options
);
588 void entry_guards_free_all(void);
590 double pathbias_get_close_success_count(entry_guard_t
*guard
);
591 double pathbias_get_use_success_count(entry_guard_t
*guard
);
593 /** Contains the bandwidth of a relay as a guard and as a non-guard
594 * after the guardfraction has been considered. */
595 typedef struct guardfraction_bandwidth_t
{
596 /** Bandwidth as a guard after guardfraction has been considered. */
598 /** Bandwidth as a non-guard after guardfraction has been considered. */
600 } guardfraction_bandwidth_t
;
602 int should_apply_guardfraction(const networkstatus_t
*ns
);
605 guard_get_guardfraction_bandwidth(guardfraction_bandwidth_t
*guardfraction_bw
,
607 uint32_t guardfraction_percentage
);