circuitbuild.h File Reference

Header file for circuitbuild.c. More...

Go to the source code of this file.


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 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_finish_handshake (origin_circuit_t *circ, const struct created_cell_t *created_cell)
int circuit_truncated (origin_circuit_t *circ, int reason)
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)
int circuit_can_use_tap (const origin_circuit_t *circ)
int circuit_has_usable_onion_key (const origin_circuit_t *circ)
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)
channel_tchannel_connect_for_circuit (const extend_info_t *ei)
int circuit_deliver_create_cell (circuit_t *circ, const struct create_cell_t *create_cell, int relayed)
int client_circ_negotiation_message (const extend_info_t *ei, uint8_t **msg_out, size_t *msg_len_out)

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

Referenced by guards_choose_guard().

◆ channel_connect_for_circuit()

channel_t* channel_connect_for_circuit ( const extend_info_t ei)

This function tries to get a channel to the specified endpoint, and then calls command_setup_channel() to give it the right callbacks.

Definition at line 102 of file circuitbuild.c.

◆ 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 2434 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 1536 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_ei, 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 2126 of file circuitbuild.c.

Referenced by circuit_extend_to_new_exit().

◆ circuit_deliver_create_cell()

int circuit_deliver_create_cell ( circuit_t circ,
const struct create_cell_t create_cell,
int  relayed 

Find a new circid that isn't currently in use on the circ->n_chan for the outgoing circuit circ, and deliver the cell create_cell to this circuit. If relayed is true, this is a create cell somebody gave us via an EXTEND cell, so we shouldn't worry if we don't understand it. Return -1 if we failed to find a suitable circid, else return 0.

Definition at line 740 of file circuitbuild.c.

◆ 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. The flags argument is a bitfield of CIRCLAUNCH_* flags, see circuit_launch_by_extend_info() for more details.

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

Definition at line 481 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 2147 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 543 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 336 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 345 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 355 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 638 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 1192 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 935 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 825 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 1326 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 2620 of file circuitbuild.c.

Referenced by second_elapsed_callback().

◆ client_circ_negotiation_message()

int client_circ_negotiation_message ( const extend_info_t ei,
uint8_t **  msg_out,
size_t *  msg_len_out 

Try to generate a circuit-negotiation message for communication with a given relay. Assumes we are using ntor v3, or some later version that supports parameter negotiatoin.

On success, return 0 and pass back a message in the out parameters. Otherwise, return -1.

Definition at line 2648 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 512 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, see circuit_launch_by_extend_info() for more details.

Definition at line 452 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.

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

  • We are a hidden service connecting to an introduction point (CIRCUIT_PURPOSE_S_ESTABLISH_INTRO).
  • We are a router testing its own reachabiity (CIRCUIT_PURPOSE_TESTING, via router_do_reachability_checks())

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

Referenced by new_route_len().