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

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

#include "lib/crypt_ops/crypto_curve25519.h"
#include "lib/crypt_ops/crypto_ed25519.h"
#include "lib/metrics/metrics_store.h"
#include "feature/hs/hs_common.h"
#include "feature/hs/hs_descriptor.h"
#include "feature/hs/hs_ident.h"
#include "feature/hs/hs_intropoint.h"
#include "feature/hs_common/replaycache.h"
#include "trunnel/hs/cell_establish_intro.h"
#include "ext/ht.h"

Go to the source code of this file.

Data Structures

struct  hs_service_metrics_t
struct  hs_service_intro_point_t
struct  hs_service_intropoints_t
struct  hs_service_descriptor_t
struct  hs_service_keys_t
struct  hs_service_authorized_client_t
struct  hs_service_config_t
struct  hs_service_state_t
struct  hs_service_t


#define HS_SERVICE_NEXT_UPLOAD_TIME_MAX   (120 * 60)
#define HS_SERVICE_POW_SEED_ROTATE_TIME_MIN   (7200 - 900)
#define hs_service_free(s)   FREE_AND_NULL(hs_service_t, hs_service_free_, (s))
#define service_authorized_client_free(c)




typedef HT_HEAD (hs_service_ht, hs_service_t) hs_service_ht
void hs_service_init (void)
void hs_service_free_all (void)
hs_service_ths_service_new (const or_options_t *options)
void hs_service_free_ (hs_service_t *service)
hs_service_ths_service_find (const ed25519_public_key_t *ident_pk)
unsigned int hs_service_get_num_services (void)
void hs_service_stage_services (const smartlist_t *service_list)
int hs_service_load_all_keys (void)
int hs_service_get_version_from_key (const hs_service_t *service)
void hs_service_lists_fnames_for_sandbox (smartlist_t *file_list, smartlist_t *dir_list)
int hs_service_set_conn_addr_port (const origin_circuit_t *circ, edge_connection_t *conn)
smartlist_ths_service_get_metrics_stores (void)
void hs_service_map_has_changed (void)
void hs_service_dir_info_changed (void)
void hs_service_new_consensus_params (const networkstatus_t *ns)
void hs_service_run_scheduled_events (time_t now)
void hs_service_circuit_has_opened (origin_circuit_t *circ)
int hs_service_receive_intro_established (origin_circuit_t *circ, const uint8_t *payload, size_t payload_len)
int hs_service_receive_introduce2 (origin_circuit_t *circ, const uint8_t *payload, size_t payload_len)
char * hs_service_lookup_current_desc (const ed25519_public_key_t *pk)
hs_service_add_ephemeral_status_t hs_service_add_ephemeral (ed25519_secret_key_t *sk, smartlist_t *ports, int max_streams_per_rdv_circuit, int max_streams_close_circuit, smartlist_t *auth_clients_v3, char **address_out)
int hs_service_del_ephemeral (const char *address)
void hs_service_upload_desc_to_dir (const char *encoded_desc, const uint8_t version, const ed25519_public_key_t *identity_pk, const ed25519_public_key_t *blinded_pk, const routerstatus_t *hsdir_rs)
hs_circuit_id_protocol_t hs_service_exports_circuit_id (const ed25519_public_key_t *pk)
void hs_service_dump_stats (int severity)
void hs_service_circuit_cleanup_on_close (const circuit_t *circ)
hs_service_authorized_client_tparse_authorized_client_key (const char *key_str, int severity)
void service_authorized_client_free_ (hs_service_authorized_client_t *client)
int hs_service_allow_non_anonymous_connection (const or_options_t *options)
int hs_service_non_anonymous_mode_enabled (const or_options_t *options)
int hs_service_reveal_startup_time (const or_options_t *options)

Detailed Description

Header file containing service data for the HS subsystem.

Definition in file hs_service.h.

Macro Definition Documentation



When loading and configuring a service, this is the default version it will be configured for as it is possible that no HiddenServiceVersion is present.

Definition at line 30 of file hs_service.h.

◆ hs_service_free

#define hs_service_free (   s)    FREE_AND_NULL(hs_service_t, hs_service_free_, (s))

Free the given service object and all its content. This function also takes care of wiping service keys from memory. It is safe to pass a NULL pointer.

Additionally, set the pointer s to NULL.

Definition at line 361 of file hs_service.h.


#define HS_SERVICE_NEXT_UPLOAD_TIME_MAX   (120 * 60)

Maximum interval for uploading next descriptor (in seconds).

Definition at line 36 of file hs_service.h.



As described in the specification, service publishes their next descriptor at a random time between those two values (in seconds).

Definition at line 34 of file hs_service.h.



Definition at line 41 of file hs_service.h.


#define HS_SERVICE_POW_SEED_ROTATE_TIME_MIN   (7200 - 900)

PoW seed expiration time is set to RAND_TIME(now+7200, 900) seconds.

Definition at line 40 of file hs_service.h.

◆ service_authorized_client_free

#define service_authorized_client_free (   c)
void service_authorized_client_free_(hs_service_authorized_client_t *client)
Definition: hs_service.c:1388

Definition at line 413 of file hs_service.h.

Enumeration Type Documentation

◆ hs_circuit_id_protocol_t

Which protocol to use for exporting HS client circuit ID.


Don't expose the circuit id.


Use the HAProxy proxy protocol.

Definition at line 203 of file hs_service.h.

Function Documentation

◆ hs_service_add_ephemeral()

hs_service_add_ephemeral_status_t hs_service_add_ephemeral ( ed25519_secret_key_t sk,
smartlist_t ports,
int  max_streams_per_rdv_circuit,
int  max_streams_close_circuit,
smartlist_t auth_clients_v3,
char **  address_out 

Add the ephemeral service using the secret key sk and ports. Both max streams parameter will be set in the newly created service.

Ownership of sk, ports, and auth_clients_v3 is passed to this routine. Regardless of success/failure, callers should not touch these values after calling this routine, and may assume that correct cleanup has been done on failure.

Return an appropriate hs_service_add_ephemeral_status_t.

Definition at line 4080 of file hs_service.c.

◆ hs_service_allow_non_anonymous_connection()

int hs_service_allow_non_anonymous_connection ( const or_options_t options)

Definition at line 3922 of file hs_service.c.

◆ hs_service_circuit_cleanup_on_close()

void hs_service_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 3957 of file hs_service.c.

Referenced by hs_circ_cleanup_on_close().

◆ hs_service_circuit_has_opened()

void hs_service_circuit_has_opened ( origin_circuit_t circ)

Called when any kind of hidden service circuit is done building thus opened. This is the entry point from the circuit subsystem.

Definition at line 4455 of file hs_service.c.

◆ hs_service_del_ephemeral()

int hs_service_del_ephemeral ( const char *  address)

For the given onion address, delete the ephemeral service. Return 0 on success else -1 on error.

Definition at line 4171 of file hs_service.c.

Referenced by connection_control_closed().

◆ hs_service_dir_info_changed()

void hs_service_dir_info_changed ( void  )

Called when our internal view of the directory has changed. We might have received a new batch of descriptors which might affect the shape of the HSDir hash ring. Signal that we should reexamine the hash ring and re-upload our HS descriptors if needed.

Definition at line 4379 of file hs_service.c.

Referenced by router_dir_info_changed().

◆ hs_service_dump_stats()

void hs_service_dump_stats ( int  severity)

Log the status of introduction points for all version 3 onion services at log severity severity.

Definition at line 4533 of file hs_service.c.

◆ hs_service_exports_circuit_id()

hs_circuit_id_protocol_t hs_service_exports_circuit_id ( const ed25519_public_key_t pk)

Does the service with identity pubkey pk export the circuit IDs of its clients?

Definition at line 4342 of file hs_service.c.

◆ hs_service_find()

hs_service_t * hs_service_find ( const ed25519_public_key_t identity_pk)

Lookup the global service map for the given identitiy public key and return the service object if found, NULL if not.

Definition at line 4608 of file hs_service.c.

Referenced by hs_metrics_update_by_ident().

◆ hs_service_free_()

void hs_service_free_ ( hs_service_t service)

Free the given service object and all its content. This function also takes care of wiping service keys from memory. It is safe to pass a NULL pointer.

Definition at line 4640 of file hs_service.c.

◆ hs_service_free_all()

void hs_service_free_all ( void  )

Release all global storage of the hidden service subsystem.

Definition at line 4715 of file hs_service.c.

Referenced by hs_free_all().

◆ hs_service_get_metrics_stores()

smartlist_t * hs_service_get_metrics_stores ( void  )

Return a newly allocated list of all the service's metrics store.

Definition at line 4592 of file hs_service.c.

◆ hs_service_get_num_services()

unsigned int hs_service_get_num_services ( void  )

Return the number of service we have configured and usable.

Definition at line 4246 of file hs_service.c.

Referenced by check_network_participation_callback(), hs_service_dir_info_changed(), and log_onion_service_stats().

◆ hs_service_get_version_from_key()

int hs_service_get_version_from_key ( const hs_service_t service)

Return the service version by looking at the key in the service directory. If the key is not found or unrecognized, -1 is returned. Else, the service version is returned.

Definition at line 4479 of file hs_service.c.

Referenced by config_learn_service_version().

◆ hs_service_init()

void hs_service_init ( void  )

Initialize the service HS subsystem.

Definition at line 4701 of file hs_service.c.

Referenced by hs_init().

◆ hs_service_lists_fnames_for_sandbox()

void hs_service_lists_fnames_for_sandbox ( smartlist_t file_list,
smartlist_t dir_list 

Add to file_list every filename used by a configured hidden service, and to dir_list every directory path used by a configured hidden service. This is used by the sandbox subsystem to allowlist those.

Definition at line 4356 of file hs_service.c.

◆ hs_service_load_all_keys()

int hs_service_load_all_keys ( void  )

Load and/or generate keys for all onion services including the client authorization if any. Return 0 on success, -1 on failure.

Definition at line 4503 of file hs_service.c.

◆ hs_service_lookup_current_desc()

char * hs_service_lookup_current_desc ( const ed25519_public_key_t pk)

Using the ed25519 public key pk, find a service for that key and return the current encoded descriptor as a newly allocated string or NULL if not found. This is used by the control port subsystem.

Definition at line 4222 of file hs_service.c.

◆ hs_service_map_has_changed()

void hs_service_map_has_changed ( void  )

This is called every time the service map changes that is if an element is added or removed.

Definition at line 3986 of file hs_service.c.

Referenced by register_service().

◆ hs_service_new()

hs_service_t * hs_service_new ( const or_options_t options)

Allocate and initialize a service object. The service configuration will contain the default values. Return the newly allocated object pointer. This function can't fail.

Definition at line 4622 of file hs_service.c.

Referenced by config_service(), and hs_service_add_ephemeral().

◆ hs_service_new_consensus_params()

void hs_service_new_consensus_params ( const networkstatus_t ns)

Called when a new consensus has arrived and has been set globally. The new consensus is pointed by ns.

Definition at line 3997 of file hs_service.c.

◆ hs_service_non_anonymous_mode_enabled()

int hs_service_non_anonymous_mode_enabled ( const or_options_t options)

Definition at line 3948 of file hs_service.c.

◆ hs_service_receive_intro_established()

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

Called when we get an INTRO_ESTABLISHED cell. Mark the circuit as an established introduction point. Return 0 on success else a negative value and the circuit is closed.

Definition at line 4423 of file hs_service.c.

◆ hs_service_receive_introduce2()

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

Called when we get an INTRODUCE2 cell on the circ. Respond to the cell and launch a circuit to the rendezvous point.

Definition at line 4394 of file hs_service.c.

◆ hs_service_reveal_startup_time()

int hs_service_reveal_startup_time ( const or_options_t options)

Definition at line 3936 of file hs_service.c.

◆ hs_service_run_scheduled_events()

void hs_service_run_scheduled_events ( time_t  now)

Periodic callback. Entry point from the main loop to the HS service subsystem. This is call every second. This is skipped if tor can't build a circuit or the network is disabled.

Definition at line 4680 of file hs_service.c.

◆ hs_service_set_conn_addr_port()

int hs_service_set_conn_addr_port ( const origin_circuit_t circ,
edge_connection_t conn 

Given conn, a rendezvous edge connection acting as an exit stream, look up the hidden service for the circuit circ, and look up the port and address based on the connection port. Assign the actual connection address.

Return 0 on success. Return -1 on failure and the caller should NOT close the circuit. Return -2 on failure and the caller MUST close the circuit for security reasons.

Definition at line 4262 of file hs_service.c.

◆ hs_service_stage_services()

void hs_service_stage_services ( const smartlist_t service_list)

Put all service object in the given service list. After this, the caller looses ownership of every elements in the list and responsible to free the list pointer.

Definition at line 4577 of file hs_service.c.

Referenced by stage_services().

◆ hs_service_upload_desc_to_dir()

void hs_service_upload_desc_to_dir ( const char *  encoded_desc,
const uint8_t  version,
const ed25519_public_key_t identity_pk,
const ed25519_public_key_t blinded_pk,
const routerstatus_t hsdir_rs 

Upload an encoded descriptor in encoded_desc of the given version. This descriptor is for the service identity_pk and blinded_pk used to setup the directory connection identifier. It is uploaded to the directory hsdir_rs routerstatus_t object.

NOTE: This function does NOT check for PublishHidServDescriptors because it is only used by the control port command HSPOST outside of this subsystem. Inside this code, upload_descriptor_to_hsdir() should be used.

Definition at line 4031 of file hs_service.c.


typedef HT_HEAD ( hs_service_ht  ,

For the service global hash map, we define a specific type for it which will make it safe to use and specific to some controlled parameters such as the hashing function and how to compare services.

◆ parse_authorized_client_key()

hs_service_authorized_client_t * parse_authorized_client_key ( const char *  key_str,
int  severity 

Parse an base32-encoded authorized client from a string.

Return the key on success, return NULL, otherwise.

Definition at line 1189 of file hs_service.c.

◆ service_authorized_client_free_()

void service_authorized_client_free_ ( hs_service_authorized_client_t client)

Release all storage held in client.

Definition at line 1388 of file hs_service.c.