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

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

#include "lib/crypt_ops/crypto_curve25519.h"
#include "lib/crypt_ops/crypto_ed25519.h"
#include "feature/hs_common/replaycache.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 "trunnel/hs/cell_establish_intro.h"
#include "ext/ht.h"

Go to the source code of this file.

Data Structures

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_free(s)   FREE_AND_NULL(hs_service_t, hs_service_free_, (s))




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)
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)
void hs_service_map_has_changed (void)
void hs_service_dir_info_changed (void)
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, 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)

Detailed Description

Header file containing service data for the HS subsytem.

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 29 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 336 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 35 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 33 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 187 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,
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 and ports 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 3644 of file hs_service.c.

◆ 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 4018 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 3724 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 3935 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 4114 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 3895 of file hs_service.c.

◆ 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 4193 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 4265 of file hs_service.c.

Referenced by hs_free_all().

◆ 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 3799 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 4048 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 4248 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 3909 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 4077 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 3775 of file hs_service.c.

◆ hs_service_map_has_changed()

void hs_service_map_has_changed ( void  )

This is called everytime the service map (v2 or v3) changes that is if an element is added or removed.

Definition at line 3579 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 initilize 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 4175 of file hs_service.c.

Referenced by config_service(), and hs_service_add_ephemeral().

◆ 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 3982 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 3950 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 4227 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 3815 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 4158 of file hs_service.c.

◆ 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 3596 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.