Data Structures | Enumerations | Functions
hs_client.h File Reference

Header file containing client data for the HS subsytem. More...

#include "lib/crypt_ops/crypto_ed25519.h"
#include "feature/hs/hs_descriptor.h"
#include "feature/hs/hs_ident.h"

Go to the source code of this file.

Data Structures

struct  hs_client_service_authorization_t


enum  hs_client_fetch_status_t {


void hs_client_note_connection_attempt_succeeded (const edge_connection_t *conn)
void hs_client_launch_v3_desc_fetch (const ed25519_public_key_t *onion_identity_pk, const smartlist_t *hsdirs)
int hs_client_decode_descriptor (const char *desc_str, const ed25519_public_key_t *service_identity_pk, hs_descriptor_t **desc)
int hs_client_any_intro_points_usable (const ed25519_public_key_t *service_pk, const hs_descriptor_t *desc)
int hs_client_refetch_hsdesc (const ed25519_public_key_t *identity_pk)
void hs_client_dir_info_changed (void)
int hs_client_send_introduce1 (origin_circuit_t *intro_circ, origin_circuit_t *rend_circ)
void hs_client_circuit_has_opened (origin_circuit_t *circ)
int hs_client_receive_rendezvous_acked (origin_circuit_t *circ, const uint8_t *payload, size_t payload_len)
int hs_client_receive_introduce_ack (origin_circuit_t *circ, const uint8_t *payload, size_t payload_len)
int hs_client_receive_rendezvous2 (origin_circuit_t *circ, const uint8_t *payload, size_t payload_len)
void hs_client_desc_has_arrived (const hs_ident_dir_conn_t *ident)
extend_info_ths_client_get_random_intro_from_edge (const edge_connection_t *edge_conn)
int hs_config_client_authorization (const or_options_t *options, int validate_only)
int hs_client_reextend_intro_circuit (origin_circuit_t *circ)
void hs_client_close_intro_circuits_from_desc (const hs_descriptor_t *desc)
void hs_client_purge_state (void)
void hs_client_free_all (void)

Detailed Description

Header file containing client data for the HS subsytem.

Definition in file hs_client.h.

Enumeration Type Documentation

◆ hs_client_fetch_status_t

Status code of a descriptor fetch request.


Something internally went wrong.


The fetch request has been launched successfully.


We already have a usable descriptor. No fetch.


No more HSDir available to query.


The fetch request is not allowed.


We are missing information to be able to launch a request.


There is a pending fetch for the requested service.

Definition at line 17 of file hs_client.h.

Function Documentation

◆ hs_client_any_intro_points_usable()

int hs_client_any_intro_points_usable ( const ed25519_public_key_t service_pk,
const hs_descriptor_t desc 

Return true iff there are at least one usable intro point in the service descriptor desc.

Definition at line 1325 of file hs_client.c.

Referenced by client_get_random_intro().

◆ hs_client_circuit_has_opened()

void hs_client_circuit_has_opened ( origin_circuit_t circ)

Called when the client circuit circ has been established. It can be either an introduction or rendezvous circuit. This function handles all hidden service versions.

Definition at line 1391 of file hs_client.c.

◆ hs_client_close_intro_circuits_from_desc()

void hs_client_close_intro_circuits_from_desc ( const hs_descriptor_t desc)

Close all client introduction circuits related to the given descriptor. This is called with a descriptor that is about to get replaced in the client cache.

Even though the introduction point might be exactly the same, we'll rebuild them if needed but the odds are very low that an existing matching introduction circuit exists at that stage.

Definition at line 1879 of file hs_client.c.

◆ hs_client_decode_descriptor()

int hs_client_decode_descriptor ( const char *  desc_str,
const ed25519_public_key_t service_identity_pk,
hs_descriptor_t **  desc 

With the given encoded descriptor in desc_str and the service key in service_identity_pk, decode the descriptor and set the desc pointer with a newly allocated descriptor object.

Return 0 on success else a negative value and desc is set to NULL.

Definition at line 1269 of file hs_client.c.

Referenced by cache_client_desc_new().

◆ hs_client_desc_has_arrived()

void hs_client_desc_has_arrived ( const hs_ident_dir_conn_t ident)

This is called when a descriptor has arrived following a fetch request and has been stored in the client cache. Every entry connection that matches the service identity key in the ident will get attached to the hidden service circuit.

Definition at line 1693 of file hs_client.c.

◆ hs_client_dir_info_changed()

void hs_client_dir_info_changed ( void  )

Called when our directory information has changed.

Definition at line 1935 of file hs_client.c.

Referenced by router_dir_info_changed().

◆ hs_client_free_all()

void hs_client_free_all ( void  )

Release all the storage held by the client subsystem.

Definition at line 1905 of file hs_client.c.

Referenced by hs_free_all().

◆ hs_client_get_random_intro_from_edge()

extend_info_t* hs_client_get_random_intro_from_edge ( const edge_connection_t edge_conn)

Return a newly allocated extend_info_t for a randomly chosen introduction point for the given edge connection identifier ident. Return NULL if we can't pick any usable introduction points.

Definition at line 1750 of file hs_client.c.

◆ hs_client_launch_v3_desc_fetch()

void hs_client_launch_v3_desc_fetch ( const ed25519_public_key_t onion_identity_pk,
const smartlist_t hsdirs 

With a given onion_identity_pk, fetch its descriptor. If hsdirs is specified, use the directory servers specified in the list. Else, use a random server.

Definition at line 458 of file hs_client.c.

Referenced by hs_control_hsfetch_command().

◆ hs_client_note_connection_attempt_succeeded()

void hs_client_note_connection_attempt_succeeded ( const edge_connection_t conn)

A circuit just finished connecting to a hidden service that the stream conn has been waiting for. Let the HS subsystem know about this.

Definition at line 1245 of file hs_client.c.

◆ hs_client_purge_state()

void hs_client_purge_state ( void  )

Purge all potentially remotely-detectable state held in the hidden service client code. Called on SIGNAL NEWNYM.

Definition at line 1915 of file hs_client.c.

◆ hs_client_receive_introduce_ack()

int hs_client_receive_introduce_ack ( origin_circuit_t circ,
const uint8_t *  payload,
size_t  payload_len 

Called when get an INTRODUCE_ACK cell on the introduction circuit circ. Return 0 on success else a negative value is returned. The circuit will be closed or reuse to extend again to another intro point.

Definition at line 1763 of file hs_client.c.

◆ hs_client_receive_rendezvous2()

int hs_client_receive_rendezvous2 ( origin_circuit_t circ,
const uint8_t *  payload,
size_t  payload_len 

Called when get a RENDEZVOUS2 cell on the rendezvous circuit circ. Return 0 on success else a negative value is returned. The circuit will be closed on error.

Definition at line 1792 of file hs_client.c.

◆ hs_client_receive_rendezvous_acked()

int hs_client_receive_rendezvous_acked ( origin_circuit_t circ,
const uint8_t *  payload,
size_t  payload_len 

Called when we receive a RENDEZVOUS_ESTABLISHED cell. Change the state of the circuit to CIRCUIT_PURPOSE_C_REND_READY. Return 0 on success else a negative value and the circuit marked for close.

Definition at line 1421 of file hs_client.c.

◆ hs_client_reextend_intro_circuit()

int hs_client_reextend_intro_circuit ( origin_circuit_t circ)

Extend the introduction circuit circ to another valid introduction point for the hidden service it is trying to connect to, or mark it and launch a new circuit if we can't extend it. Return 0 on success or possible success. Return -1 and mark the introduction circuit for close on permanent failure.

On failure, the caller is responsible for marking the associated rendezvous circuit for close.

Definition at line 1830 of file hs_client.c.

◆ hs_client_refetch_hsdesc()

int hs_client_refetch_hsdesc ( const ed25519_public_key_t identity_pk)

Launch a connection to a hidden service directory to fetch a hidden service descriptor using identity_pk to get the necessary keys.

A hs_client_fetch_status_t code is returned.

Definition at line 1348 of file hs_client.c.

Referenced by connection_dir_client_refetch_hsdesc_if_needed().

◆ hs_client_send_introduce1()

int hs_client_send_introduce1 ( origin_circuit_t intro_circ,
origin_circuit_t rend_circ 

This is called when we are trying to attach an AP connection to these hidden service circuits from connection_ap_handshake_attach_circuit(). Return 0 on success, -1 for a transient error that is actions were triggered to recover or -2 for a permenent error where both circuits will marked for close.

The following supports every hidden service version.

Definition at line 1379 of file hs_client.c.

◆ hs_config_client_authorization()

int hs_config_client_authorization ( const or_options_t options,
int  validate_only 

From a set of options, setup every client authorization detail found. Return 0 on success or -1 on failure. If validate_only is set, parse, warn and return as normal, but don't actually change the configuration.

Definition at line 1578 of file hs_client.c.

Referenced by hs_config_client_auth_all().