Data Structures | Macros | Enumerations | Functions
hs_client.h File Reference

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

#include "lib/crypt_ops/crypto_ed25519.h"
#include "feature/hs/hs_circuit.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


#define client_service_authorization_free(auth)


enum  hs_client_fetch_status_t {
enum  hs_client_register_auth_status_t {
enum  hs_client_removal_auth_status_t { REMOVAL_SUCCESS , REMOVAL_SUCCESS_NOT_FOUND , REMOVAL_BAD_ADDRESS }


const hs_desc_intro_point_tfind_desc_intro_point_by_ident (const hs_ident_circuit_t *ident, const hs_descriptor_t *desc)
hs_client_register_auth_status_t hs_client_register_auth_credentials (hs_client_service_authorization_t *creds)
hs_client_removal_auth_status_t hs_client_remove_auth_credentials (const char *hsaddress)
digest256map_t * get_hs_client_auths_map (void)
void client_service_authorization_free_ (hs_client_service_authorization_t *auth)
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 send_introduce1 (origin_circuit_t *intro_circ, origin_circuit_t *rend_circ, const hs_descriptor_t *desc, hs_pow_solution_t *pow_solution, const hs_desc_intro_point_t *ip)
hs_desc_decode_status_t 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_setup_intro_circ_auth_key (origin_circuit_t *circ)
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)
void hs_client_circuit_cleanup_on_close (const circuit_t *circ)
void hs_client_circuit_cleanup_on_free (const 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_dir_fetch_done (dir_connection_t *dir_conn, const char *reason, const char *body, const int status_code)
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 subsystem.

Definition in file hs_client.h.

Macro Definition Documentation



Flag to set when a client auth is permanent (saved on disk).

Definition at line 63 of file hs_client.h.

◆ client_service_authorization_free

#define client_service_authorization_free (   auth)
client_service_authorization_free_, (auth))

Definition at line 93 of 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 19 of file hs_client.h.

◆ hs_client_register_auth_status_t

enum hs_client_register_auth_status_t

Definition at line 37 of file hs_client.h.

◆ hs_client_removal_auth_status_t

enum hs_client_removal_auth_status_t

Definition at line 53 of file hs_client.h.

Function Documentation

◆ client_service_authorization_free_()

void client_service_authorization_free_ ( hs_client_service_authorization_t auth)

Definition at line 2332 of file hs_client.c.

◆ find_desc_intro_point_by_ident()

const hs_desc_intro_point_t * find_desc_intro_point_by_ident ( const hs_ident_circuit_t ident,
const hs_descriptor_t desc 

Find a descriptor intro point object that matches the given ident in the given descriptor desc. Return NULL if not found.

Definition at line 545 of file hs_client.c.

Referenced by hs_client_close_intro_circuits_from_desc(), and pow_worker_replyfn().

◆ get_hs_client_auths_map()

digest256map_t * get_hs_client_auths_map ( void  )

Get the HS client auth map.

Definition at line 2036 of file hs_client.c.

◆ 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 2205 of file hs_client.c.

Referenced by client_get_random_intro(), and close_or_reextend_intro_circ().

◆ hs_client_circuit_cleanup_on_close()

void hs_client_circuit_cleanup_on_close ( const circuit_t circ)

Called when a circuit was just cleaned up. This is done right before the circuit is marked for close.

Definition at line 2048 of file hs_client.c.

Referenced by cleanup_on_close_client_circ().

◆ hs_client_circuit_cleanup_on_free()

void hs_client_circuit_cleanup_on_free ( const circuit_t circ)

Called when a circuit was just cleaned up. This is done right before the circuit is freed.

Definition at line 2079 of file hs_client.c.

Referenced by cleanup_on_free_client_circ().

◆ 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 2269 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 2713 of file hs_client.c.

Referenced by hs_cache_remove_as_client().

◆ hs_client_decode_descriptor()

hs_desc_decode_status_t 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.

On success, HS_DESC_DECODE_OK is returned and desc is set to the decoded descriptor. On error, desc is set to NULL and a decoding error status is returned depending on what was the issue.

Definition at line 2148 of file hs_client.c.

Referenced by cache_client_desc_new().

◆ hs_client_dir_fetch_done()

void hs_client_dir_fetch_done ( dir_connection_t dir_conn,
const char *  reason,
const char *  body,
const int  status_code 

Called when a descriptor directory fetch is done.

Act accordingly on all entry connections depending on the HTTP status code we got. In case of an error, the SOCKS error is set (if ExtendedErrors is set).

The reason is a human readable string returned by the directory server which can describe the status of the request. The body is the response content, on 200 code it is the descriptor itself. Finally, the status_code is the HTTP code returned by the directory server.

Definition at line 2557 of file hs_client.c.

◆ hs_client_dir_info_changed()

void hs_client_dir_info_changed ( void  )

Called when our directory information has changed.

The work done in that function has to either be kept within the HS subsystem or else scheduled as a mainloop event. In other words, this function can't call outside to another subsystem to avoid risking recursion problems.

Definition at line 2775 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 2739 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 2591 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 499 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 2130 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 2752 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 2602 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 2629 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 2293 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 2666 of file hs_client.c.

Referenced by close_or_reextend_intro_circ().

◆ 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 2228 of file hs_client.c.

Referenced by connection_dir_client_refetch_hsdesc_if_needed().

◆ hs_client_register_auth_credentials()

hs_client_register_auth_status_t hs_client_register_auth_credentials ( hs_client_service_authorization_t creds)

Register the credential creds as part of the client auth subsystem.

Takes ownership of creds.

Now that we set the new credentials, also try to decrypt any cached descriptors.

Definition at line 1833 of file hs_client.c.

◆ hs_client_remove_auth_credentials()

hs_client_removal_auth_status_t hs_client_remove_auth_credentials ( const char *  hsaddress)

Remove client auth credentials for the service hs_address.

Definition at line 2002 of file hs_client.c.

◆ 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 2259 of file hs_client.c.

◆ hs_client_setup_intro_circ_auth_key()

int hs_client_setup_intro_circ_auth_key ( origin_circuit_t circ)

Using the introduction circuit circ, setup the authentication key of the intro point this circuit has extended to.

Return 0 if everything went well, otherwise return -1 in the case of errors.

Definition at line 847 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 2467 of file hs_client.c.

Referenced by hs_config_client_auth_all().

◆ send_introduce1()

int send_introduce1 ( origin_circuit_t intro_circ,
origin_circuit_t rend_circ,
const hs_descriptor_t desc,
hs_pow_solution_t pow_solution,
const hs_desc_intro_point_t ip 

Phase two for client-side introducing: Send an INTRODUCE1 cell along the intro circuit and populate the rend circuit identifier with the needed key material for the e2e encryption.

Definition at line 609 of file hs_client.c.