circuitbuild.h File Reference

Header file for circuitbuild.c. More...

Go to the source code of this file.

Functions
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_t *	origin_circuit_init (uint8_t purpose, int flags)
origin_circuit_t *	circuit_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_t *	build_state_get_exit_node (cpath_build_state_t *state)
const char *	build_state_get_exit_nickname (cpath_build_state_t *state)
const node_t *	choose_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_t *	channel_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)

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 2509 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 2486 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 2497 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 98 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 2379 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 1493 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 2080 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 736 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 477 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 2101 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 332 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 341 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 351 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 634 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 1180 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 925 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 821 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 1278 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 2554 of file circuitbuild.c.

Referenced by second_elapsed_callback().

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, see circuit_launch_by_extend_info() for more details.

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

Referenced by new_route_len().