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 }


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)
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_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 89 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.

Function Documentation

◆ get_hs_client_auths_map()

digest256map_t* get_hs_client_auths_map ( void  )

Get the HS client auth map.

Definition at line 1846 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 2014 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 1858 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 1889 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 2078 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 2522 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 1957 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 2366 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 2577 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 2548 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 2400 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 476 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 1939 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 2558 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 2411 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 2438 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 2102 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 2475 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 2037 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 1643 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 1812 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 2068 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 2276 of file hs_client.c.

Referenced by hs_config_client_auth_all().