Macros | Functions
circuitbuild.h File Reference

Go to the source code of this file.


#define extend_info_free(info)   FREE_AND_NULL(extend_info_t, extend_info_free_, (info))


int route_len_for_purpose (uint8_t purpose, extend_info_t *exit_ei)
char * circuit_list_path (origin_circuit_t *circ, int verbose)
char * circuit_list_path_for_controller (origin_circuit_t *circ)
void circuit_log_path (int severity, unsigned int domain, origin_circuit_t *circ)
origin_circuit_torigin_circuit_init (uint8_t purpose, int flags)
origin_circuit_tcircuit_establish_circuit (uint8_t purpose, extend_info_t *exit, int flags)
struct circuit_guard_state_t * origin_circuit_get_guard_state (origin_circuit_t *circ)
int circuit_handle_first_hop (origin_circuit_t *circ)
void circuit_n_chan_done (channel_t *chan, int status, int close_origin_circuits)
int inform_testing_reachability (void)
int circuit_timeout_want_to_count_circ (const origin_circuit_t *circ)
int circuit_send_next_onion_skin (origin_circuit_t *circ)
void circuit_note_clock_jumped (int64_t seconds_elapsed, bool was_idle)
int circuit_extend (cell_t *cell, circuit_t *circ)
int circuit_init_cpath_crypto (crypt_path_t *cpath, const char *key_data, size_t key_data_len, int reverse, int is_hs_v3)
int circuit_finish_handshake (origin_circuit_t *circ, const struct created_cell_t *created_cell)
int circuit_truncated (origin_circuit_t *circ, int reason)
int onionskin_answer (or_circuit_t *circ, const struct created_cell_t *created_cell, const char *keys, size_t keys_len, const uint8_t *rend_circ_nonce)
 MOCK_DECL (int, circuit_all_predicted_ports_handled,(time_t now, int *need_uptime, int *need_capacity))
int circuit_append_new_exit (origin_circuit_t *circ, extend_info_t *info)
int circuit_extend_to_new_exit (origin_circuit_t *circ, extend_info_t *info)
void onion_append_to_cpath (crypt_path_t **head_ptr, crypt_path_t *new_hop)
extend_info_textend_info_new (const char *nickname, const char *rsa_id_digest, const struct ed25519_public_key_t *ed_id, crypto_pk_t *onion_key, const struct curve25519_public_key_t *ntor_key, const tor_addr_t *addr, uint16_t port)
extend_info_textend_info_from_node (const node_t *r, int for_direct_connect)
extend_info_textend_info_dup (extend_info_t *info)
void extend_info_free_ (extend_info_t *info)
int extend_info_addr_is_allowed (const tor_addr_t *addr)
int extend_info_supports_tap (const extend_info_t *ei)
int extend_info_supports_ntor (const extend_info_t *ei)
int circuit_can_use_tap (const origin_circuit_t *circ)
int circuit_has_usable_onion_key (const origin_circuit_t *circ)
int extend_info_has_preferred_onion_key (const extend_info_t *ei)
const uint8_t * build_state_get_exit_rsa_id (cpath_build_state_t *state)
const node_tbuild_state_get_exit_node (cpath_build_state_t *state)
const char * build_state_get_exit_nickname (cpath_build_state_t *state)
const node_tchoose_good_entry_server (uint8_t purpose, cpath_build_state_t *state, struct circuit_guard_state_t **guard_state_out)
void circuit_upgrade_circuits_from_guard_wait (void)

Detailed Description

Header file for circuitbuild.c.

Definition in file circuitbuild.h.

Function Documentation

◆ build_state_get_exit_nickname()

const char* build_state_get_exit_nickname ( cpath_build_state_t state)

Return the nickname for the chosen exit router in state. If there is no chosen exit, or if we don't know the routerinfo_t for the chosen exit, return NULL.

Definition at line 2952 of file circuitbuild.c.

References cpath_build_state_t::chosen_exit, and extend_info_t::nickname.

Referenced by circuit_list_path_impl().

◆ build_state_get_exit_node()

const node_t* build_state_get_exit_node ( cpath_build_state_t state)

Return the node_t for the chosen exit router in state. If there is no chosen exit, or if we don't know the node_t for the chosen exit, return NULL.

Definition at line 2929 of file circuitbuild.c.

References cpath_build_state_t::chosen_exit, and extend_info_t::identity_digest.

Referenced by build_middle_exclude_list(), build_vanguard_middle_exclude_list(), circuit_is_acceptable(), and circuit_stream_is_being_handled().

◆ build_state_get_exit_rsa_id()

const uint8_t* build_state_get_exit_rsa_id ( cpath_build_state_t state)

Return the RSA ID digest for the chosen exit router in state. If there is no chosen exit, return NULL.

Definition at line 2940 of file circuitbuild.c.

References cpath_build_state_t::chosen_exit, and extend_info_t::identity_digest.

Referenced by guards_choose_guard().

◆ choose_good_entry_server()

const node_t* choose_good_entry_server ( uint8_t  purpose,
cpath_build_state_t state,
circuit_guard_state_t **  guard_state_out 

Pick a good entry server for the circuit to be built according to state. Don't reuse a chosen exit (if any), don't use this router (if we're an OR), and respect firewall settings; if we're configured to use entry guards, return one.

Set *guard_state_out to information about the guard that we're selecting, which we'll use later to remember whether the guard worked or not.

Definition at line 2645 of file circuitbuild.c.

◆ circuit_append_new_exit()

int circuit_append_new_exit ( origin_circuit_t circ,
extend_info_t exit_ei 

Give circ a new exit destination to exit, and add a hop to the cpath reflecting this. Don't send the next extend cell – the caller will do this if it wants to.

Definition at line 2298 of file circuitbuild.c.

References origin_circuit_t::build_state, and tor_assert().

Referenced by circuit_extend_to_new_exit().

◆ circuit_establish_circuit()

origin_circuit_t* circuit_establish_circuit ( uint8_t  purpose,
extend_info_t exit_ei,
int  flags 

Build a new circuit for purpose. If exit is defined, then use that as your exit router, else choose a suitable exit node.

Also launch a connection to the first OR in the chosen path, if it's not open already.

Definition at line 480 of file circuitbuild.c.

References CIRCLAUNCH_IS_V3_RP, onion_pick_cpath_exit(), onion_populate_cpath(), and origin_circuit_init().

◆ circuit_extend()

int circuit_extend ( cell_t cell,
circuit_t circ 

Take the 'extend' cell, pull out addr/port plus the onion skin and identity digest for the next hop. If we're already connected, pass the onion skin to the next hop using a create cell; otherwise launch a new OR connection, and circ will notice when the connection succeeds or fails.

Return -1 if we want to warn and tear down the circuit, else return 0.

Definition at line 1214 of file circuitbuild.c.

References log_fn, and circuit_t::n_chan.

◆ circuit_extend_to_new_exit()

int circuit_extend_to_new_exit ( origin_circuit_t circ,
extend_info_t exit_ei 

Take an open circ, and add a new hop at the end, based on info. Set its state back to CIRCUIT_STATE_BUILDING, and then send the next extend cell to begin connecting to that hop.

Definition at line 2319 of file circuitbuild.c.

References circuit_append_new_exit(), circuit_send_next_onion_skin(), circuit_set_state(), CIRCUIT_STATE_BUILDING, circuit_t::timestamp_began, TO_CIRCUIT, and warn_if_last_router_excluded().

◆ circuit_handle_first_hop()

int circuit_handle_first_hop ( origin_circuit_t circ)

Start establishing the first hop of our circuit. Figure out what OR we should connect to, and if necessary start the connection to it. If we're already connected, then send the 'create' cell. Return 0 for ok, -reason if circ should be marked-for-close.

Definition at line 541 of file circuitbuild.c.

References origin_circuit_t::cpath, crypt_path_t::extend_info, onion_next_hop_in_cpath(), and tor_assert().

◆ circuit_init_cpath_crypto()

int circuit_init_cpath_crypto ( crypt_path_t cpath,
const char *  key_data,
size_t  key_data_len,
int  reverse,
int  is_hs_v3 

Initialize cpath->{f|b}_{crypto|digest} from the key material in key_data.

If is_hs_v3 is set, this cpath will be used for next gen hidden service circuits and key_data must be at least HS_NTOR_KEY_EXPANSION_KDF_OUT_LEN bytes in length.

If is_hs_v3 is not set, key_data must contain CPATH_KEY_MATERIAL_LEN bytes, which are used as follows:

  • 20 to initialize f_digest
  • 20 to initialize b_digest
  • 16 to key f_crypto
  • 16 to key b_crypto

(If 'reverse' is true, then f_XX and b_XX are swapped.)

Return 0 if init was successful, else -1 if it failed.

Definition at line 1381 of file circuitbuild.c.

References crypt_path_t::crypto, and tor_assert().

◆ circuit_list_path()

char* circuit_list_path ( origin_circuit_t circ,
int  verbose 

If verbose is false, allocate and return a comma-separated list of the currently built elements of circ. If verbose is true, also list information about link status in a more verbose format using spaces.

Definition at line 339 of file circuitbuild.c.

References circuit_list_path_impl().

Referenced by circuit_log_path().

◆ circuit_list_path_for_controller()

char* circuit_list_path_for_controller ( origin_circuit_t circ)

Allocate and return a comma-separated list of the currently built elements of circ, giving each as a verbose nickname.

Definition at line 348 of file circuitbuild.c.

References circuit_list_path_impl().

Referenced by circuit_describe_status_for_controller().

◆ circuit_log_path()

void circuit_log_path ( int  severity,
unsigned int  domain,
origin_circuit_t circ 

Log, at severity severity, the nicknames of each router in circ's cpath. Also log the length of the cpath, and the intended exit point.

Definition at line 358 of file circuitbuild.c.

References circuit_list_path(), tor_free, and tor_log().

◆ circuit_n_chan_done()

void circuit_n_chan_done ( channel_t chan,
int  status,
int  close_origin_circuits 

Find any circuits that are waiting on or_conn to become open and get them to send their create cells forward.

Status is 1 if connect succeeded, or 0 if connect failed.

Close_origin_circuits is 1 if we should close all the origin circuits through this channel, or 0 otherwise. (This happens when we want to retry an older guard.)

Definition at line 629 of file circuitbuild.c.

◆ circuit_note_clock_jumped()

void circuit_note_clock_jumped ( int64_t  seconds_elapsed,
bool  was_idle 

Our clock just jumped by seconds_elapsed. If was_idle is true, then the monotonic time matches; otherwise it doesn't. Assume something has also gone wrong with our network: notify the user, and abandon all not-yet-used circuits.

Definition at line 1175 of file circuitbuild.c.

References circuit_mark_all_dirty_circs_as_unusable(), circuit_mark_all_unused_circs(), control_event_client_status(), control_event_general_status(), LD_GENERAL, LOG_NOTICE, LOG_WARN, note_that_we_maybe_cant_complete_circuits(), reset_all_main_loop_timers(), and tor_log().

◆ circuit_send_next_onion_skin()

int circuit_send_next_onion_skin ( origin_circuit_t circ)

This is the backbone function for building circuits.

If circ's first hop is closed, then we need to build a create cell and send it forward.

Otherwise, if circ's cpath still has any non-open hops, we need to build a relay extend cell and send it forward to the next non-open hop.

If all hops on the cpath are open, we're done building the circuit and we should do housekeeping for the newly opened circuit.

Return -reason if we want to tear down circ, else return 0.

Definition at line 939 of file circuitbuild.c.

References circpad_machine_event_circ_added_hop(), circpad_machine_event_circ_built(), circuit_build_no_more_hops(), circuit_build_times_handle_completed_hop(), circuit_send_first_onion_skin(), circuit_send_intermediate_onion_skin(), CIRCUIT_STATE_BUILDING, origin_circuit_t::cpath, onion_next_hop_in_cpath(), crypt_path_t::state, circuit_t::state, and tor_assert().

Referenced by circuit_extend_to_new_exit().

◆ circuit_timeout_want_to_count_circ()

int circuit_timeout_want_to_count_circ ( const origin_circuit_t circ)

Return true if circ is the type of circuit we want to count timeouts from.

In particular, we want to consider any circuit that plans to build at least 3 hops (but maybe more), but has 3 or fewer hops built so far.

We still want to consider circuits before 3 hops, because we need to decide if we should convert them to a measurement circuit in circuit_build_times_handle_completed_hop(), rather than letting slow circuits get killed right away.

Definition at line 843 of file circuitbuild.c.

References origin_circuit_t::build_state, circuit_get_cpath_opened_len(), DEFAULT_ROUTE_LEN, cpath_build_state_t::desired_path_len, and origin_circuit_t::has_opened.

Referenced by circuit_build_times_handle_completed_hop().

◆ circuit_truncated()

int circuit_truncated ( origin_circuit_t circ,
int  reason 

We received a relay truncated cell on circ.

Since we don't send truncates currently, getting a truncated means that a connection broke or an extend failed. For now, just give up: force circ to close, and return 0.

Definition at line 1459 of file circuitbuild.c.

References tor_assert().

◆ circuit_upgrade_circuits_from_guard_wait()

void circuit_upgrade_circuits_from_guard_wait ( void  )

Find the circuits that are waiting to find out whether their guards are usable, and if any are ready to become usable, mark them open and try attaching streams as appropriate.

Definition at line 3043 of file circuitbuild.c.

References circuit_find_circuits_to_upgrade_from_guard_wait().

Referenced by second_elapsed_callback().

◆ extend_info_addr_is_allowed()

int extend_info_addr_is_allowed ( const tor_addr_t addr)

Return true iff the given address can be used to extend to.

Definition at line 2961 of file circuitbuild.c.

References tor_assert().

◆ extend_info_dup()

extend_info_t* extend_info_dup ( extend_info_t info)

Allocate and return a new extend_info_t with the same contents as info.

Definition at line 2911 of file circuitbuild.c.

References tor_assert().

◆ extend_info_free_()

void extend_info_free_ ( extend_info_t info)

Release storage held by an extend_info_t struct.

Definition at line 2900 of file circuitbuild.c.

◆ extend_info_from_node()

extend_info_t* extend_info_from_node ( const node_t node,
int  for_direct_connect 

Allocate and return a new extend_info that can be used to build a circuit to or through the node node. Use the primary address of the node (i.e. its IPv4 address) unless for_direct_connect is true, in which case the preferred address is used instead. May return NULL if there is not enough info about node to extend to it–for example, if the preferred routerinfo_t or microdesc_t is missing, or if for_direct_connect is true and none of the node's addresses is allowed by tor's firewall and IP version config.

Definition at line 2823 of file circuitbuild.c.

References fascist_firewall_choose_address_node(), and node_has_preferred_descriptor().

◆ inform_testing_reachability()

int inform_testing_reachability ( void  )

We've decided to start our reachability testing. If all is set, log this to the user. Return 1 if we did, or 0 if we chose not to log anything.

Definition at line 776 of file circuitbuild.c.

References routerinfo_t::addr, control_event_server_status(), routerinfo_t::dir_port, LOG_NOTICE, routerinfo_t::or_port, tor_dup_ip(), and tor_snprintf().

◆ onion_append_to_cpath()

void onion_append_to_cpath ( crypt_path_t **  head_ptr,
crypt_path_t new_hop 

Add new_hop to the end of the doubly-linked-list head_ptr. This function is used to extend cpath by another hop.

Definition at line 2379 of file circuitbuild.c.

References crypt_path_t::next, and crypt_path_t::prev.

◆ origin_circuit_get_guard_state()

struct circuit_guard_state_t* origin_circuit_get_guard_state ( origin_circuit_t circ)

Return the guard state associated with circ, which may be NULL.

Definition at line 509 of file circuitbuild.c.

References origin_circuit_t::guard_state.

Referenced by circ_state_has_higher_priority().

◆ origin_circuit_init()

origin_circuit_t* origin_circuit_init ( uint8_t  purpose,
int  flags 

Create and return a new origin circuit. Initialize its purpose and build-state based on our arguments. The flags argument is a bitfield of CIRCLAUNCH_* flags.

Definition at line 454 of file circuitbuild.c.

References origin_circuit_t::build_state, circuit_set_state(), CIRCUIT_STATE_CHAN_WAIT, origin_circuit_new(), and TO_CIRCUIT.

Referenced by circuit_establish_circuit().

◆ route_len_for_purpose()

int route_len_for_purpose ( uint8_t  purpose,
extend_info_t exit_ei 

Helper for new_route_len(). Choose a circuit length for purpose purpose: DEFAULT_ROUTE_LEN (+ 1 if someone else chose the exit). If someone else chose the exit, they could be colluding with the exit, so add a randomly selected node to preserve anonymity.

Here, "exit node" sometimes means an OR acting as an internal endpoint, rather than as a relay to an external endpoint. This means there need to be at least DEFAULT_ROUTE_LEN routers between us and the internal endpoint to preserve the same anonymity properties that we would get when connecting to an external endpoint. These internal endpoints can include:

  • Connections to a directory of hidden services (CIRCUIT_PURPOSE_C_GENERAL)
  • A client connecting to an introduction point, which the hidden service picked (CIRCUIT_PURPOSE_C_INTRODUCING, via circuit_get_open_circ_or_launch() which rewrites it from CIRCUIT_PURPOSE_C_INTRODUCE_ACK_WAIT)
  • A hidden service connecting to a rendezvous point, which the client picked (CIRCUIT_PURPOSE_S_CONNECT_REND, via rend_service_receive_introduction() and rend_service_relaunch_rendezvous)

There are currently two situations where we picked the exit node ourselves, making DEFAULT_ROUTE_LEN a safe circuit length:

onion_pick_cpath_exit() bypasses us (by not calling new_route_len()) in the one-hop tunnel case, so we don't need to handle that.

Definition at line 1596 of file circuitbuild.c.


Referenced by new_route_len().