Macros | Functions
circuitbuild.h File Reference

Header file for circuitbuild.c. More...

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_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)
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)
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 2846 of file circuitbuild.c.

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 2823 of file circuitbuild.c.

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

◆ 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 2834 of file circuitbuild.c.

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 2575 of file circuitbuild.c.

◆ circuit_all_predicted_ports_handled()

int circuit_all_predicted_ports_handled ( time_t  now,
int *  need_uptime,
int *  need_capacity 

Return 1 if we already have circuits present or on the way for all anticipated ports. Return 0 if we should make more.

If we're returning 0, set need_uptime and need_capacity to indicate any requirements that the unhandled ports have.

Definition at line 1702 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 2269 of file circuitbuild.c.

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 479 of file circuitbuild.c.

◆ 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 1212 of file circuitbuild.c.

◆ 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 2290 of file circuitbuild.c.

◆ 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 539 of file circuitbuild.c.

◆ 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 338 of file circuitbuild.c.

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 347 of file circuitbuild.c.

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 357 of file circuitbuild.c.

◆ 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 627 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 1173 of file circuitbuild.c.

◆ 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 937 of file circuitbuild.c.

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 841 of file circuitbuild.c.

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 1429 of file circuitbuild.c.

◆ 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 2937 of file circuitbuild.c.

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 2855 of file circuitbuild.c.

◆ 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 2805 of file circuitbuild.c.

◆ extend_info_free_()

void extend_info_free_ ( extend_info_t info)

Release storage held by an extend_info_t struct.

Definition at line 2794 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 2717 of file circuitbuild.c.

Referenced by get_extend_info_from_intro_point().

◆ 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 774 of file circuitbuild.c.

◆ 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 508 of file circuitbuild.c.

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 453 of file circuitbuild.c.

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 1566 of file circuitbuild.c.

Referenced by new_route_len().