Header file containing circuit data for the whole HS subsystem. More...

#include "core/or/or.h"
#include "lib/crypt_ops/crypto_ed25519.h"
#include "feature/hs/hs_service.h"

Functions
void	hs_circ_cleanup_on_close (circuit_t *circ)

void	hs_circ_cleanup_on_free (circuit_t *circ)

void	hs_circ_cleanup_on_repurpose (circuit_t *circ)

int	hs_circ_service_intro_has_opened (hs_service_t service, hs_service_intro_point_t ip, const hs_service_descriptor_t desc, origin_circuit_t circ)

void	hs_circ_service_rp_has_opened (const hs_service_t service, origin_circuit_t circ)

int	hs_circ_launch_intro_point (hs_service_t service, const hs_service_intro_point_t ip, extend_info_t *ei, bool direct_conn)

int	hs_circ_launch_rendezvous_point (const hs_service_t service, const curve25519_public_key_t onion_key, const uint8_t *rendezvous_cookie)

void	hs_circ_retry_service_rendezvous_point (const origin_circuit_t *circ)

origin_circuit_t *	hs_circ_service_get_intro_circ (const hs_service_intro_point_t *ip)

origin_circuit_t *	hs_circ_service_get_established_intro_circ (const hs_service_intro_point_t *ip)

int	hs_circ_handle_intro_established (const hs_service_t service, const hs_service_intro_point_t ip, origin_circuit_t circ, const uint8_t payload, size_t payload_len)

int	hs_circ_handle_introduce2 (const hs_service_t service, const origin_circuit_t circ, hs_service_intro_point_t ip, const struct hs_subcredential_t subcredential, const uint8_t *payload, size_t payload_len)

int	hs_circ_send_introduce1 (origin_circuit_t intro_circ, origin_circuit_t rend_circ, const hs_desc_intro_point_t ip, const struct hs_subcredential_t subcredential)

int	hs_circ_send_establish_rendezvous (origin_circuit_t *circ)

int	hs_circuit_setup_e2e_rend_circ (origin_circuit_t circ, const uint8_t ntor_key_seed, size_t seed_len, int is_service_side)

int	hs_circuit_setup_e2e_rend_circ_legacy_client (origin_circuit_t circ, const uint8_t rend_cell_body)

bool	hs_circ_is_rend_sent_in_intro1 (const origin_circuit_t *circ)

void	hs_circ_setup_congestion_control (origin_circuit_t *origin_circ, uint8_t sendme_inc, bool is_single_onion)

Detailed Description

Header file containing circuit data for the whole HS subsystem.

Definition in file hs_circuit.h.

Function Documentation

◆ hs_circ_cleanup_on_close()

void hs_circ_cleanup_on_close ( circuit_t * circ )

Circuit cleanup strategy:

What follows is a series of functions that notifies the HS subsystem of 3 different circuit cleanup phase: close, free and repurpose.

Tor can call any of those in any orders so they have to be safe between each other. In other words, the free should never depend on close to be called before.

The "on_close()" is called from circuit_mark_for_close() which is considered the tor fast path and thus as little work as possible should done in that function. Currently, we only remove the circuit from the HS circuit map and move on.

The "on_free()" is called from circuit circuit_free_() and it is very important that at the end of the function, no state or objects related to this circuit remains alive.

The "on_repurpose()" is called from circuit_change_purpose() for which we simply remove it from the HS circuit map. We do not have other cleanup requirements after that.

NOTE: The onion service code, specifically the service code, cleans up lingering objects or state if any of its circuit disappear which is why our cleanup strategy doesn't involve any service specific actions. As long as the circuit is removed from the HS circuit map, it won't be used. We are about to close this circ. Clean it up from any related HS data structures. This function can be called multiple times safely for the same circuit.

Definition at line 1260 of file hs_circuit.c.

◆ hs_circ_cleanup_on_free()

void hs_circ_cleanup_on_free ( circuit_t * circ )

We are about to free this circ. Clean it up from any related HS data structures. This function can be called multiple times safely for the same circuit.

Definition at line 1286 of file hs_circuit.c.

Referenced by circuit_free_().

◆ hs_circ_cleanup_on_repurpose()

void hs_circ_cleanup_on_repurpose ( circuit_t * circ )

We are about to repurpose this circ. Clean it up from any related HS data structures. This function can be called multiple times safely for the same circuit.

Definition at line 1307 of file hs_circuit.c.

◆ hs_circ_handle_intro_established()

int hs_circ_handle_intro_established	(	const hs_service_t *	service,
		const hs_service_intro_point_t *	ip,
		origin_circuit_t *	circ,
		const uint8_t *	payload,
		size_t	payload_len
	)

Circ has been expecting an INTRO_ESTABLISHED cell that just arrived. Handle the INTRO_ESTABLISHED cell payload of length payload_len arriving on the given introduction circuit circ. The service is only used for logging purposes. Return 0 on success else a negative value.

Definition at line 905 of file hs_circuit.c.

◆ hs_circ_is_rend_sent_in_intro1()

bool hs_circ_is_rend_sent_in_intro1 ( const origin_circuit_t * circ )

Return true iff the given established client rendezvous circuit was sent into the INTRODUCE1 cell. This is called so we can take a decision on expiring or not the circuit.

The caller MUST make sure the circuit is an established client rendezvous circuit (purpose: CIRCUIT_PURPOSE_C_REND_READY).

This function supports all onion service versions.

Definition at line 1340 of file hs_circuit.c.

◆ hs_circ_launch_intro_point()

int hs_circ_launch_intro_point	(	hs_service_t *	service,
		const hs_service_intro_point_t *	ip,
		extend_info_t *	ei,
		bool	direct_conn
	)

For a given service and a service intro point, launch a circuit to the extend info ei. If the service is a single onion, and direct_conn is true, a one-hop circuit will be requested.

Return 0 if the circuit was successfully launched and tagged with the correct identifier. On error, a negative value is returned.

Definition at line 707 of file hs_circuit.c.

◆ hs_circ_retry_service_rendezvous_point()

void hs_circ_retry_service_rendezvous_point ( const origin_circuit_t * circ )

Called when we fail building a rendezvous circuit at some point other than the last hop: launches a new circuit to the same rendezvous point.

We currently relaunch connections to rendezvous points if:

A rendezvous circuit timed out before connecting to RP.
The rendezvous circuit failed to connect to the RP.

We avoid relaunching a connection to this rendezvous point if:

We have already tried MAX_REND_FAILURES times to connect to this RP,
We've been trying to connect to this RP for more than MAX_REND_TIMEOUT seconds, or
We've already retried this specific rendezvous circuit.

Definition at line 681 of file hs_circuit.c.

Referenced by hs_circ_cleanup_on_repurpose().

◆ hs_circ_send_establish_rendezvous()

int hs_circ_send_establish_rendezvous ( origin_circuit_t * circ )

Send an ESTABLISH_RENDEZVOUS cell along the rendezvous circuit circ. On success, 0 is returned else -1 and the circuit is marked for close.

Definition at line 1180 of file hs_circuit.c.

◆ hs_circ_service_get_established_intro_circ()

origin_circuit_t* hs_circ_service_get_established_intro_circ ( const hs_service_intro_point_t * ip )

Return an introduction point established circuit matching the given intro point object. The circuit purpose has to be CIRCUIT_PURPOSE_S_INTRO. NULL is returned is no such circuit can be found.

Definition at line 654 of file hs_circuit.c.

◆ hs_circ_service_get_intro_circ()

origin_circuit_t* hs_circ_service_get_intro_circ ( const hs_service_intro_point_t * ip )

Return an introduction point circuit matching the given intro point object. NULL is returned is no such circuit can be found.

Definition at line 643 of file hs_circuit.c.

Referenced by should_remove_intro_point().

◆ hs_circ_service_intro_has_opened()

int hs_circ_service_intro_has_opened	(	hs_service_t *	service,
		hs_service_intro_point_t *	ip,
		const hs_service_descriptor_t *	desc,
		origin_circuit_t *	circ
	)

Called when a service introduction point circuit is done building. Given the service and intro point object, this function will send the ESTABLISH_INTRO cell on the circuit. Return 0 on success. Return 1 if the circuit has been repurposed to General because we already have too many opened.

Definition at line 765 of file hs_circuit.c.

◆ hs_circ_service_rp_has_opened()

void hs_circ_service_rp_has_opened	(	const hs_service_t *	service,
		origin_circuit_t *	circ
	)

Called when a service rendezvous point circuit is done building. Given the service and the circuit, this function will send a RENDEZVOUS1 cell on the circuit using the information in the circuit identifier. If the cell can't be sent, the circuit is closed.

Definition at line 833 of file hs_circuit.c.

◆ hs_circ_setup_congestion_control()

void hs_circ_setup_congestion_control	(	origin_circuit_t *	origin_circ,
		uint8_t	sendme_inc,
		bool	is_single_onion
	)

Setup on the given circuit congestion control with the given parameters.

This function assumes that congestion control is enabled on the network and so it is the caller responsability to make sure of it.

Definition at line 610 of file hs_circuit.c.

Referenced by setup_rendezvous_circ_congestion_control().

◆ hs_circuit_setup_e2e_rend_circ()

int hs_circuit_setup_e2e_rend_circ	(	origin_circuit_t *	circ,
		const uint8_t *	ntor_key_seed,
		size_t	seed_len,
		int	is_service_side
	)

Circuit circ just finished the rend ntor key exchange. Use the key exchange output material at ntor_key_seed and setup circ to serve as a rendezvous end-to-end circuit between the client and the service. If is_service_side is set, then we are the hidden service and the other side is the client.

Return 0 if the operation went well; in case of error return -1.

Definition at line 1064 of file hs_circuit.c.

Functions