Macros | Functions
circuituse.h File Reference

Go to the source code of this file.


#define CIRCLAUNCH_IS_V3_RP   (1<<4)


void circuit_expire_building (void)
void circuit_expire_waiting_for_better_guard (void)
void circuit_remove_handled_ports (smartlist_t *needed_ports)
int circuit_stream_is_being_handled (entry_connection_t *conn, uint16_t port, int min)
void circuit_log_ancient_one_hop_circuits (int age)
void circuit_build_needed_circs (time_t now)
void circuit_expire_old_circs_as_needed (time_t now)
void circuit_detach_stream (circuit_t *circ, edge_connection_t *conn)
void circuit_expire_old_circuits_serverside (time_t now)
void reset_bandwidth_test (void)
int circuit_enough_testing_circs (void)
void circuit_has_opened (origin_circuit_t *circ)
void circuit_try_attaching_streams (origin_circuit_t *circ)
void circuit_build_failed (origin_circuit_t *circ)
origin_circuit_tcircuit_launch_by_extend_info (uint8_t purpose, extend_info_t *info, int flags)
origin_circuit_tcircuit_launch (uint8_t purpose, int flags)
void circuit_reset_failure_count (int timeout)
int connection_ap_handshake_attach_chosen_circuit (entry_connection_t *conn, origin_circuit_t *circ, crypt_path_t *cpath)
int connection_ap_handshake_attach_circuit (entry_connection_t *conn)
void circuit_change_purpose (circuit_t *circ, uint8_t new_purpose)
int hostname_in_track_host_exits (const or_options_t *options, const char *address)
void mark_circuit_unusable_for_new_conns (origin_circuit_t *circ)
int circuit_purpose_is_hidden_service (uint8_t)
int circuit_should_use_vanguards (uint8_t)
void circuit_sent_valid_data (origin_circuit_t *circ, uint16_t relay_body_len)
void circuit_read_valid_data (origin_circuit_t *circ, uint16_t relay_body_len)

Detailed Description

Header file for circuituse.c.

Definition in file circuituse.h.

Macro Definition Documentation



Flag to set when the last hop of a circuit doesn't need to be an exit node.

Definition at line 46 of file circuituse.h.


#define CIRCLAUNCH_IS_V3_RP   (1<<4)

Flag to set when we are trying to launch a v3 rendezvous circuit. We need to apply some additional filters on the node picked.

Definition at line 49 of file circuituse.h.



Flag to set when a circuit needs to be built of high-capacity nodes

Definition at line 43 of file circuituse.h.



Flag to set when a circuit needs to be built of high-uptime nodes

Definition at line 41 of file circuituse.h.



Flag to set when a circuit should have only a single hop.

Definition at line 39 of file circuituse.h.

Function Documentation

◆ circuit_build_failed()

void circuit_build_failed ( origin_circuit_t circ)

Called whenever a circuit could not be successfully built.

Definition at line 1776 of file circuituse.c.

References origin_circuit_t::build_state, circuit_get_cpath_len(), and cpath_build_state_t::desired_path_len.

Referenced by circuit_about_to_free().

◆ circuit_build_needed_circs()

void circuit_build_needed_circs ( time_t  now)

This function is called once a second, if router_have_minimum_dir_info() is true. Its job is to make sure all services we offer have enough circuits available. Some services just want enough circuits for current tasks, whereas others want a minimum set of idle circuits hanging around.

Definition at line 1338 of file circuituse.c.

Referenced by second_elapsed_callback().

◆ circuit_change_purpose()

void circuit_change_purpose ( circuit_t circ,
uint8_t  new_purpose 

Change circ's purpose to new_purpose.

Definition at line 3061 of file circuituse.c.

References CIRCUIT_IS_ORIGIN, CIRCUIT_PURPOSE_IS_ORIGIN, circuit_purpose_to_string(), circuit_t::purpose, and tor_assert().

◆ circuit_detach_stream()

void circuit_detach_stream ( circuit_t circ,
edge_connection_t conn 

If the stream conn is a member of any of the linked lists of circ, then remove it from the list.

Definition at line 1392 of file circuituse.c.

References CONN_TYPE_AP, tor_assert(), and connection_t::type.

Referenced by connection_exit_about_to_close().

◆ circuit_enough_testing_circs()

int circuit_enough_testing_circs ( void  )

Return 1 if we've already exercised our bandwidth, or if we have fewer than NUM_PARALLEL_TESTING_CIRCS testing circuits established or on the way. Else return 0.

Definition at line 1621 of file circuituse.c.


Referenced by rep_hist_circbuilding_dormant(), and router_do_reachability_checks().

◆ circuit_expire_building()

void circuit_expire_building ( void  )

Close all circuits that start at us, aren't open, and were born at least CircuitBuildTimeout seconds ago.

TODO: This function is now partially redundant to circuit_build_times_handle_completed_hop(), but that function only covers circuits up to and including 3 hops that are still actually completing hops. However, circuit_expire_building() also handles longer circuits, as well as circuits that are completely stalled. In the future (after prop247/other path selection revamping), we probably want to eliminate this rats nest in favor of a simpler approach.

Because circuit build timeout is calculated only based on 3 hop general purpose circuit construction, we need to scale the timeout to make it properly apply to longer circuits, and circuits of certain usage types. The following diagram illustrates how we derive the scaling below. In short, we calculate the number of times our telescoping-based circuit construction causes cells to traverse each link for the circuit purpose types in question, and then assume each link is equivalent.

OP –a--> A –b--> B –c--> C OP –a--> A –b--> B –c--> C –d--> D

Let h = a = b = c = d

Three hops (general_cutoff) RTTs = 3a + 2b + c RTTs = 6h Cannibalized: RTTs = a+b+c+d RTTs = 4h Four hops: RTTs = 4a + 3b + 2c + d RTTs = 10h Client INTRODUCE1+ACK: // XXX: correct? RTTs = 5a + 4b + 3c + 2d RTTs = 14h Server intro: RTTs = 4a + 3b + 2c RTTs = 9h

Definition at line 456 of file circuituse.c.

References circuit_any_opened_circuits().

Referenced by second_elapsed_callback().

◆ circuit_expire_old_circs_as_needed()

void circuit_expire_old_circs_as_needed ( time_t  now)

Called once a second either directly or from circuit_build_needed_circs(). As appropriate (once per NewCircuitPeriod) resets failure counts and expires old circuits.

Definition at line 1361 of file circuituse.c.

References addressmap_clean(), circuit_expire_old_circuits_clientside(), circuit_launch(), CIRCUIT_PURPOSE_C_GENERAL, circuit_reset_failure_count(), log_fn, LOG_INFO, proxy_mode(), and TESTING_CIRCUIT_INTERVAL.

Referenced by second_elapsed_callback().

◆ circuit_expire_old_circuits_serverside()

void circuit_expire_old_circuits_serverside ( time_t  now)

Find each non-origin circuit that has been unused for too long, has no streams on it, came from a client, and ends here: mark it for close.

Definition at line 1572 of file circuituse.c.

References channel_is_client(), channel_when_last_xmit(), CIRCUIT_IS_ORIGIN, IDLE_ONE_HOP_CIRC_TIMEOUT, or_circuit_t::n_streams, or_circuit_t::p_chan, or_circuit_t::rend_splice, or_circuit_t::resolving_streams, SMARTLIST_FOREACH_BEGIN, and TO_OR_CIRCUIT().

Referenced by expire_old_circuits_serverside_callback().

◆ circuit_expire_waiting_for_better_guard()

void circuit_expire_waiting_for_better_guard ( void  )

Mark for close all circuits that start here, that were built through a guard we weren't sure if we wanted to use, and that have been waiting around for way too long.

Definition at line 858 of file circuituse.c.

References circuit_get_global_origin_circuit_list(), entry_guard_state_should_expire(), origin_circuit_t::guard_state, SMARTLIST_FOREACH_BEGIN, and TO_CIRCUIT.

Referenced by second_elapsed_callback().

◆ circuit_has_opened()

void circuit_has_opened ( origin_circuit_t circ)

The circuit circ has just become open. Take the next step: for rendezvous circuits, we pass circ to the appropriate function in rendclient or rendservice. For general circuits, we call connection_ap_attach_pending, which looks for pending streams that could use circ.

Definition at line 1685 of file circuituse.c.

References circuit_event_status().

◆ circuit_launch()

origin_circuit_t* circuit_launch ( uint8_t  purpose,
int  flags 

Launch a new circuit; see circuit_launch_by_extend_info() for details on arguments.

Definition at line 1942 of file circuituse.c.

References circuit_launch_by_extend_info().

Referenced by circuit_expire_old_circs_as_needed(), and circuit_launch_predicted_hs_circ().

◆ circuit_launch_by_extend_info()

origin_circuit_t* circuit_launch_by_extend_info ( uint8_t  purpose,
extend_info_t extend_info,
int  flags 

Launch a new circuit with purpose purpose and exit node extend_info (or NULL to select a random exit node). If flags contains CIRCLAUNCH_NEED_UPTIME, choose among routers with high uptime. If CIRCLAUNCH_NEED_CAPACITY is set, choose among routers with high bandwidth. If CIRCLAUNCH_IS_INTERNAL is true, the last hop need not be an exit node. If CIRCLAUNCH_ONEHOP_TUNNEL is set, the circuit will have only one hop. Return the newly allocated circuit on success, or NULL on failure.

Definition at line 2067 of file circuituse.c.


Referenced by circuit_launch().

◆ circuit_log_ancient_one_hop_circuits()

void circuit_log_ancient_one_hop_circuits ( int  age)

As a diagnostic for bug 8387, log information about how many one-hop circuits we have around that have been there for at least age seconds. Log a few of them. Ignores Single Onion Service intro, it is expected to be long-term one-hop circuits.

Definition at line 882 of file circuituse.c.


◆ circuit_purpose_is_hidden_service()

int circuit_purpose_is_hidden_service ( uint8_t  purpose)

Tell us if a circuit is a hidden service circuit.

Definition at line 1965 of file circuituse.c.


Referenced by circuit_should_use_vanguards(), and middle_node_must_be_vanguard().

◆ circuit_read_valid_data()

void circuit_read_valid_data ( origin_circuit_t circ,
uint16_t  relay_body_len 

Add relay_body_len and RELAY_PAYLOAD_SIZE-relay_body_len to the valid delivered read field and the overhead field, respectively.

Definition at line 3150 of file circuituse.c.

◆ circuit_remove_handled_ports()

void circuit_remove_handled_ports ( smartlist_t needed_ports)

Remove any elements in needed_ports that are handled by an open or in-progress circuit.

Definition at line 1014 of file circuituse.c.

Referenced by circuit_get_unhandled_ports().

◆ circuit_reset_failure_count()

void circuit_reset_failure_count ( int  timeout)

Reset the failure count for opening general circuits. This means we will try MAX_CIRCUIT_FAILURES times more (if necessary) before stopping again.

Definition at line 2194 of file circuituse.c.

References did_circs_fail_last_period, MAX_CIRCUIT_FAILURES, and n_circuit_failures.

Referenced by circuit_expire_old_circs_as_needed().

◆ circuit_sent_valid_data()

void circuit_sent_valid_data ( origin_circuit_t circ,
uint16_t  relay_body_len 

Add relay_body_len and RELAY_PAYLOAD_SIZE-relay_body_len to the valid delivered written fields and the overhead field, respectively.

Definition at line 3129 of file circuituse.c.

◆ circuit_should_use_vanguards()

int circuit_should_use_vanguards ( uint8_t  purpose)

Return true if this circuit purpose should use vanguards or pinned Layer2 or Layer3 guards.

This function takes both the circuit purpose and the torrc options for pinned middles/vanguards into account (ie: the circuit must be a hidden service circuit and vanguards/pinned middles must be enabled for it to return true).

Definition at line 1997 of file circuituse.c.

References circuit_purpose_is_hidden_service(), or_options_t::HSLayer2Nodes, and or_options_t::HSLayer3Nodes.

Referenced by build_middle_exclude_list(), circuit_launch_predicted_hs_circ(), circuit_should_cannibalize_to_build(), get_circuit_purpose_needed_to_cannibalize(), guards_choose_guard(), and route_len_for_purpose().

◆ circuit_stream_is_being_handled()

int circuit_stream_is_being_handled ( entry_connection_t conn,
uint16_t  port,
int  min 

◆ circuit_try_attaching_streams()

void circuit_try_attaching_streams ( origin_circuit_t circ)

Called when a circuit becomes ready for streams to be attached to it.

Definition at line 1759 of file circuituse.c.

References circuit_try_clearing_isolation_state(), and connection_ap_attach_pending().

◆ connection_ap_handshake_attach_chosen_circuit()

int connection_ap_handshake_attach_chosen_circuit ( entry_connection_t conn,
origin_circuit_t circ,
crypt_path_t cpath 

Attempt to attach the connection conn to circ, and send a begin or resolve cell as appropriate. Return values are as for connection_ap_handshake_attach_circuit. The stream will exit from the hop indicated by cpath, or from the last hop in circ's cpath if cpath is NULL.

Definition at line 2728 of file circuituse.c.

References AP_CONN_STATE_CIRCUIT_WAIT, AP_CONN_STATE_CONTROLLER_WAIT, approx_time(), CIRCUIT_STATE_OPEN, socks_request_t::command, connection_ap_handshake_send_resolve(), consider_recording_trackhost(), ENTRY_TO_CONN, ISO_SOCKSAUTH, entry_port_cfg_t::isolation_flags, link_apconn_to_circ(), socks_request_t::passwordlen, pathbias_count_use_attempt(), entry_port_cfg_t::socks_iso_keep_alive, entry_connection_t::socks_request, connection_t::state, circuit_t::state, circuit_t::timestamp_dirty, tor_assert(), entry_connection_t::use_begindir, and socks_request_t::usernamelen.

◆ connection_ap_handshake_attach_circuit()

int connection_ap_handshake_attach_circuit ( entry_connection_t conn)

Try to find a safe live circuit for stream conn. If we find one, attach the stream, send appropriate cells, and return 1. Otherwise, try to launch new circuit(s) for the stream. If we can launch circuits, return 0. Otherwise, if we simply can't proceed with this stream, return -1. (conn needs to die, and is maybe already marked).

Definition at line 2813 of file circuituse.c.

References connection_t::addr, AP_CONN_STATE_CIRCUIT_WAIT, ENTRY_TO_CONN, LD_APP, log_fn, LOG_INFO, LOG_NOTICE, connection_t::port, entry_connection_t::socks_request, connection_t::state, connection_t::timestamp_created, tor_addr_is_null(), tor_assert(), and entry_connection_t::want_onehop.

◆ hostname_in_track_host_exits()

int hostname_in_track_host_exits ( const or_options_t options,
const char *  address 

Return true iff address is matched by one of the entries in TrackHostExits.

Definition at line 2668 of file circuituse.c.

References SMARTLIST_FOREACH_BEGIN, strcasecmpend(), and or_options_t::TrackHostExits.

Referenced by consider_recording_trackhost().

◆ mark_circuit_unusable_for_new_conns()

void mark_circuit_unusable_for_new_conns ( origin_circuit_t circ)

Mark circ so that no more connections can be attached to it.

Definition at line 3105 of file circuituse.c.

References approx_time(), or_options_t::MaxCircuitDirtiness, circuit_t::timestamp_dirty, and tor_assert().

Referenced by circuit_mark_all_dirty_circs_as_unusable().

◆ reset_bandwidth_test()

void reset_bandwidth_test ( void  )

Reset have_performed_bandwidth_test, so we'll start building testing circuits again so we can exercise our bandwidth.

Definition at line 1611 of file circuituse.c.

References have_performed_bandwidth_test.