nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-11 05:33:47 +01:00
Code Issues Packages Projects Releases Wiki Activity

Fix various doxygen comments in feature/hs.

Browse Source
This commit is contained in:
Nick Mathewson 2019-11-07 08:13:31 -05:00
parent 45698e89ed
commit 582cee723a
13 changed files with 147 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
src/feature/hs/hs_circuit.c
View File

@ -40,7 +40,7 @@
#include "feature/nodelist/node_st.h" #include "feature/nodelist/node_st.h"
#include "core/or/origin_circuit_st.h" #include "core/or/origin_circuit_st.h"
/* A circuit is about to become an e2e rendezvous circuit. Check /** A circuit is about to become an e2e rendezvous circuit. Check
* <b>circ_purpose</b> and ensure that it's properly set. Return true iff * <b>circ_purpose</b> and ensure that it's properly set. Return true iff
* circuit purpose is properly set, otherwise return false. */ * circuit purpose is properly set, otherwise return false. */
static int static int
@ -67,7 +67,7 @@ circuit_purpose_is_correct_for_rend(unsigned int circ_purpose,
return 1; return 1;
} }
/* Create and return a crypt path for the final hop of a v3 prop224 rendezvous /** Create and return a crypt path for the final hop of a v3 prop224 rendezvous
* circuit. Initialize the crypt path crypto using the output material from the * circuit. Initialize the crypt path crypto using the output material from the
* ntor key exchange at <b>ntor_key_seed</b>. * ntor key exchange at <b>ntor_key_seed</b>.
* *
@ -101,7 +101,7 @@ create_rend_cpath(const uint8_t *ntor_key_seed, size_t seed_len,
return cpath; return cpath;
} }
/* We are a v2 legacy HS client: Create and return a crypt path for the hidden /** We are a v2 legacy HS client: Create and return a crypt path for the hidden
* service on the other side of the rendezvous circuit <b>circ</b>. Initialize * service on the other side of the rendezvous circuit <b>circ</b>. Initialize
* the crypt path crypto using the body of the RENDEZVOUS1 cell at * the crypt path crypto using the body of the RENDEZVOUS1 cell at
* <b>rend_cell_body</b> (which must be at least DH1024_KEY_LEN+DIGEST_LEN * <b>rend_cell_body</b> (which must be at least DH1024_KEY_LEN+DIGEST_LEN
@ -152,7 +152,7 @@ create_rend_cpath_legacy(origin_circuit_t *circ, const uint8_t *rend_cell_body)
return hop; return hop;
} }
/* Append the final <b>hop</b> to the cpath of the rend <b>circ</b>, and mark /** Append the final <b>hop</b> to the cpath of the rend <b>circ</b>, and mark
* <b>circ</b> ready for use to transfer HS relay cells. */ * <b>circ</b> ready for use to transfer HS relay cells. */
static void static void
finalize_rend_circuit(origin_circuit_t *circ, crypt_path_t *hop, finalize_rend_circuit(origin_circuit_t *circ, crypt_path_t *hop,
@ -193,7 +193,7 @@ finalize_rend_circuit(origin_circuit_t *circ, crypt_path_t *hop,
} }
} }
/* For a given circuit and a service introduction point object, register the /** For a given circuit and a service introduction point object, register the
* intro circuit to the circuitmap. This supports legacy intro point. */ * intro circuit to the circuitmap. This supports legacy intro point. */
static void static void
register_intro_circ(const hs_service_intro_point_t *ip, register_intro_circ(const hs_service_intro_point_t *ip,
@ -211,7 +211,7 @@ register_intro_circ(const hs_service_intro_point_t *ip,
} }
} }
/* Return the number of opened introduction circuit for the given circuit that /** Return the number of opened introduction circuit for the given circuit that
* is matching its identity key. */ * is matching its identity key. */
static unsigned int static unsigned int
count_opened_desc_intro_point_circuits(const hs_service_t *service, count_opened_desc_intro_point_circuits(const hs_service_t *service,
@ -243,7 +243,7 @@ count_opened_desc_intro_point_circuits(const hs_service_t *service,
return count; return count;
} }
/* From a given service, rendezvous cookie and handshake info, create a /** From a given service, rendezvous cookie and handshake info, create a
* rendezvous point circuit identifier. This can't fail. */ * rendezvous point circuit identifier. This can't fail. */
STATIC hs_ident_circuit_t * STATIC hs_ident_circuit_t *
create_rp_circuit_identifier(const hs_service_t *service, create_rp_circuit_identifier(const hs_service_t *service,
@ -282,7 +282,7 @@ create_rp_circuit_identifier(const hs_service_t *service,
return ident; return ident;
} }
/* From a given service and service intro point, create an introduction point /** From a given service and service intro point, create an introduction point
* circuit identifier. This can't fail. */ * circuit identifier. This can't fail. */
static hs_ident_circuit_t * static hs_ident_circuit_t *
create_intro_circuit_identifier(const hs_service_t *service, create_intro_circuit_identifier(const hs_service_t *service,
@ -299,7 +299,7 @@ create_intro_circuit_identifier(const hs_service_t *service,
return ident; return ident;
} }
/* For a given introduction point and an introduction circuit, send the /** For a given introduction point and an introduction circuit, send the
* ESTABLISH_INTRO cell. The service object is used for logging. This can fail * ESTABLISH_INTRO cell. The service object is used for logging. This can fail
* and if so, the circuit is closed and the intro point object is flagged * and if so, the circuit is closed and the intro point object is flagged
* that the circuit is not established anymore which is important for the * that the circuit is not established anymore which is important for the
@ -349,7 +349,7 @@ send_establish_intro(const hs_service_t *service,
memwipe(payload, 0, sizeof(payload)); memwipe(payload, 0, sizeof(payload));
} }
/* Return a string constant describing the anonymity of service. */ /** Return a string constant describing the anonymity of service. */
static const char * static const char *
get_service_anonymity_string(const hs_service_t *service) get_service_anonymity_string(const hs_service_t *service)
{ {
@ -360,7 +360,7 @@ get_service_anonymity_string(const hs_service_t *service)
} }
} }
/* For a given service, the ntor onion key and a rendezvous cookie, launch a /** For a given service, the ntor onion key and a rendezvous cookie, launch a
* circuit to the rendezvous point specified by the link specifiers. On * circuit to the rendezvous point specified by the link specifiers. On
* success, a circuit identifier is attached to the circuit with the needed * success, a circuit identifier is attached to the circuit with the needed
* data. This function will try to open a circuit for a maximum value of * data. This function will try to open a circuit for a maximum value of
@ -469,7 +469,7 @@ launch_rendezvous_point_circuit(const hs_service_t *service,
extend_info_free(info); extend_info_free(info);
} }
/* Return true iff the given service rendezvous circuit circ is allowed for a /** Return true iff the given service rendezvous circuit circ is allowed for a
* relaunch to the rendezvous point. */ * relaunch to the rendezvous point. */
static int static int
can_relaunch_service_rendezvous_point(const origin_circuit_t *circ) can_relaunch_service_rendezvous_point(const origin_circuit_t *circ)
@ -516,7 +516,7 @@ can_relaunch_service_rendezvous_point(const origin_circuit_t *circ)
return 0; return 0;
} }
/* Retry the rendezvous point of circ by launching a new circuit to it. */ /** Retry the rendezvous point of circ by launching a new circuit to it. */
static void static void
retry_service_rendezvous_point(const origin_circuit_t *circ) retry_service_rendezvous_point(const origin_circuit_t *circ)
{ {
@ -565,7 +565,7 @@ retry_service_rendezvous_point(const origin_circuit_t *circ)
return; return;
} }
/* Using the given descriptor intro point ip, the node of the /** Using the given descriptor intro point ip, the node of the
* rendezvous point rp_node and the service's subcredential, populate the * rendezvous point rp_node and the service's subcredential, populate the
* already allocated intro1_data object with the needed key material and link * already allocated intro1_data object with the needed key material and link
* specifiers. * specifiers.
@ -622,7 +622,7 @@ setup_introduce1_data(const hs_desc_intro_point_t *ip,
/* Public API */ /* Public API */
/* ========== */ /* ========== */
/* Return an introduction point circuit matching the given intro point object. /** Return an introduction point circuit matching the given intro point object.
* NULL is returned is no such circuit can be found. */ * NULL is returned is no such circuit can be found. */
origin_circuit_t * origin_circuit_t *
hs_circ_service_get_intro_circ(const hs_service_intro_point_t *ip) hs_circ_service_get_intro_circ(const hs_service_intro_point_t *ip)
@ -637,7 +637,7 @@ hs_circ_service_get_intro_circ(const hs_service_intro_point_t *ip)
} }
} }
/* Return an introduction point established circuit matching the given intro /** Return an introduction point established circuit matching the given intro
* point object. The circuit purpose has to be CIRCUIT_PURPOSE_S_INTRO. NULL * point object. The circuit purpose has to be CIRCUIT_PURPOSE_S_INTRO. NULL
* is returned is no such circuit can be found. */ * is returned is no such circuit can be found. */
origin_circuit_t * origin_circuit_t *
@ -658,7 +658,7 @@ hs_circ_service_get_established_intro_circ(const hs_service_intro_point_t *ip)
return (TO_CIRCUIT(circ)->purpose == CIRCUIT_PURPOSE_S_INTRO) ? circ : NULL; return (TO_CIRCUIT(circ)->purpose == CIRCUIT_PURPOSE_S_INTRO) ? circ : NULL;
} }
/* Called when we fail building a rendezvous circuit at some point other than /** Called when we fail building a rendezvous circuit at some point other than
* the last hop: launches a new circuit to the same rendezvous point. This * the last hop: launches a new circuit to the same rendezvous point. This
* supports legacy service. * supports legacy service.
* *
@ -698,7 +698,7 @@ hs_circ_retry_service_rendezvous_point(origin_circuit_t *circ)
return; return;
} }
/* For a given service and a service intro point, launch a circuit to the /** For a given service and a service intro point, launch a circuit to the
* extend info ei. If the service is a single onion, and direct_conn is true, * extend info ei. If the service is a single onion, and direct_conn is true,
* a one-hop circuit will be requested. * a one-hop circuit will be requested.
* *
@ -759,7 +759,7 @@ hs_circ_launch_intro_point(hs_service_t *service,
return ret; return ret;
} }
/* Called when a service introduction point circuit is done building. Given /** Called when a service introduction point circuit is done building. Given
* the service and intro point object, this function will send the * the service and intro point object, this function will send the
* ESTABLISH_INTRO cell on the circuit. Return 0 on success. Return 1 if the * ESTABLISH_INTRO cell on the circuit. Return 0 on success. Return 1 if the
* circuit has been repurposed to General because we already have too many * circuit has been repurposed to General because we already have too many
@ -828,7 +828,7 @@ hs_circ_service_intro_has_opened(hs_service_t *service,
return ret; return ret;
} }
/* Called when a service rendezvous point circuit is done building. Given the /** Called when a service rendezvous point circuit is done building. Given the
* service and the circuit, this function will send a RENDEZVOUS1 cell on the * service and the circuit, this function will send a RENDEZVOUS1 cell on the
* circuit using the information in the circuit identifier. If the cell can't * circuit using the information in the circuit identifier. If the cell can't
* be sent, the circuit is closed. */ * be sent, the circuit is closed. */
@ -894,7 +894,7 @@ hs_circ_service_rp_has_opened(const hs_service_t *service,
memwipe(payload, 0, sizeof(payload)); memwipe(payload, 0, sizeof(payload));
} }
/* Circ has been expecting an INTRO_ESTABLISHED cell that just arrived. Handle /** Circ has been expecting an INTRO_ESTABLISHED cell that just arrived. Handle
* the INTRO_ESTABLISHED cell payload of length payload_len arriving on the * the INTRO_ESTABLISHED cell payload of length payload_len arriving on the
* given introduction circuit circ. The service is only used for logging * given introduction circuit circ. The service is only used for logging
* purposes. Return 0 on success else a negative value. */ * purposes. Return 0 on success else a negative value. */
@ -939,7 +939,7 @@ hs_circ_handle_intro_established(const hs_service_t *service,
return ret; return ret;
} }
/* We just received an INTRODUCE2 cell on the established introduction circuit /** We just received an INTRODUCE2 cell on the established introduction circuit
* circ. Handle the INTRODUCE2 payload of size payload_len for the given * circ. Handle the INTRODUCE2 payload of size payload_len for the given
* circuit and service. This cell is associated with the intro point object ip * circuit and service. This cell is associated with the intro point object ip
* and the subcredential. Return 0 on success else a negative value. */ * and the subcredential. Return 0 on success else a negative value. */
@ -1006,7 +1006,7 @@ hs_circ_handle_introduce2(const hs_service_t *service,
return ret; return ret;
} }
/* Circuit <b>circ</b> just finished the rend ntor key exchange. Use the key /** Circuit <b>circ</b> just finished the rend ntor key exchange. Use the key
* exchange output material at <b>ntor_key_seed</b> and setup <b>circ</b> to * exchange output material at <b>ntor_key_seed</b> and setup <b>circ</b> to
* serve as a rendezvous end-to-end circuit between the client and the * serve as a rendezvous end-to-end circuit between the client and the
* service. If <b>is_service_side</b> is set, then we are the hidden service * service. If <b>is_service_side</b> is set, then we are the hidden service
@ -1036,7 +1036,7 @@ hs_circuit_setup_e2e_rend_circ(origin_circuit_t *circ,
return 0; return 0;
} }
/* We are a v2 legacy HS client and we just received a RENDEZVOUS1 cell /** We are a v2 legacy HS client and we just received a RENDEZVOUS1 cell
* <b>rend_cell_body</b> on <b>circ</b>. Finish up the DH key exchange and then * <b>rend_cell_body</b> on <b>circ</b>. Finish up the DH key exchange and then
* extend the crypt path of <b>circ</b> so that the hidden service is on the * extend the crypt path of <b>circ</b> so that the hidden service is on the
* other side. */ * other side. */
@ -1061,7 +1061,7 @@ hs_circuit_setup_e2e_rend_circ_legacy_client(origin_circuit_t *circ,
return 0; return 0;
} }
/* Given the introduction circuit intro_circ, the rendezvous circuit /** Given the introduction circuit intro_circ, the rendezvous circuit
* rend_circ, a descriptor intro point object ip and the service's * rend_circ, a descriptor intro point object ip and the service's
* subcredential, send an INTRODUCE1 cell on intro_circ. * subcredential, send an INTRODUCE1 cell on intro_circ.
* *
@ -1146,7 +1146,7 @@ hs_circ_send_introduce1(origin_circuit_t *intro_circ,
return ret; return ret;
} }
/* Send an ESTABLISH_RENDEZVOUS cell along the rendezvous circuit circ. On /** Send an ESTABLISH_RENDEZVOUS cell along the rendezvous circuit circ. On
* success, 0 is returned else -1 and the circuit is marked for close. */ * success, 0 is returned else -1 and the circuit is marked for close. */
int int
hs_circ_send_establish_rendezvous(origin_circuit_t *circ) hs_circ_send_establish_rendezvous(origin_circuit_t *circ)
@ -1197,7 +1197,7 @@ hs_circ_send_establish_rendezvous(origin_circuit_t *circ)
return -1; return -1;
} }
/* We are about to close or free this <b>circ</b>. Clean it up from any /** We are about to close or free this <b>circ</b>. Clean it up from any
* related HS data structures. This function can be called multiple times * related HS data structures. This function can be called multiple times
* safely for the same circuit. */ * safely for the same circuit. */
void void

63
src/feature/hs/hs_circuitmap.c
View File

@ -23,13 +23,13 @@
/************************** HS circuitmap code *******************************/ /************************** HS circuitmap code *******************************/
/* This is the hidden service circuitmap. It's a hash table that maps /** This is the hidden service circuitmap. It's a hash table that maps
introduction and rendezvous tokens to specific circuits such that given a introduction and rendezvous tokens to specific circuits such that given a
token it's easy to find the corresponding circuit. */ token it's easy to find the corresponding circuit. */
static struct hs_circuitmap_ht *the_hs_circuitmap = NULL; static struct hs_circuitmap_ht *the_hs_circuitmap = NULL;
/* This is a helper function used by the hash table code (HT_). It returns 1 if /** This is a helper function used by the hash table code (HT_). It returns 1
* two circuits have the same HS token. */ * if two circuits have the same HS token. */
static int static int
hs_circuits_have_same_token(const circuit_t *first_circuit, hs_circuits_have_same_token(const circuit_t *first_circuit,
const circuit_t *second_circuit) const circuit_t *second_circuit)
@ -60,8 +60,9 @@ hs_circuits_have_same_token(const circuit_t *first_circuit,
first_token->token_len); first_token->token_len);
} }
/* This is a helper function for the hash table code (HT_). It hashes a circuit /** This is a helper function for the hash table code (HT_). It hashes a
* HS token into an unsigned int for use as a key by the hash table routines.*/ * circuit HS token into an unsigned int for use as a key by the hash table
* routines.*/
static inline unsigned int static inline unsigned int
hs_circuit_hash_token(const circuit_t *circuit) hs_circuit_hash_token(const circuit_t *circuit)
{ {
@ -71,7 +72,7 @@ hs_circuit_hash_token(const circuit_t *circuit)
circuit->hs_token->token_len); circuit->hs_token->token_len);
} }
/* Register the circuitmap hash table */ /** Register the circuitmap hash table */
HT_PROTOTYPE(hs_circuitmap_ht, // The name of the hashtable struct HT_PROTOTYPE(hs_circuitmap_ht, // The name of the hashtable struct
circuit_t, // The name of the element struct, circuit_t, // The name of the element struct,
hs_circuitmap_node, // The name of HT_ENTRY member hs_circuitmap_node, // The name of HT_ENTRY member
@ -83,7 +84,7 @@ HT_GENERATE2(hs_circuitmap_ht, circuit_t, hs_circuitmap_node,
#ifdef TOR_UNIT_TESTS #ifdef TOR_UNIT_TESTS
/* Return the global HS circuitmap. Used by unittests. */ /** Return the global HS circuitmap. Used by unittests. */
hs_circuitmap_ht * hs_circuitmap_ht *
get_hs_circuitmap(void) get_hs_circuitmap(void)
{ {
@ -136,7 +137,7 @@ get_circuit_with_token(hs_token_t *search_token)
return HT_FIND(hs_circuitmap_ht, the_hs_circuitmap, &search_circ); return HT_FIND(hs_circuitmap_ht, the_hs_circuitmap, &search_circ);
} }
/* Helper function that registers <b>circ</b> with <b>token</b> on the HS /** Helper function that registers <b>circ</b> with <b>token</b> on the HS
circuitmap. This function steals reference of <b>token</b>. */ circuitmap. This function steals reference of <b>token</b>. */
static void static void
hs_circuitmap_register_impl(circuit_t *circ, hs_token_t *token) hs_circuitmap_register_impl(circuit_t *circ, hs_token_t *token)
@ -186,7 +187,7 @@ hs_circuitmap_register_circuit(circuit_t *circ,
hs_circuitmap_register_impl(circ, hs_token); hs_circuitmap_register_impl(circ, hs_token);
} }
/* Helper function for hs_circuitmap_get_origin_circuit() and /** Helper function for hs_circuitmap_get_origin_circuit() and
* hs_circuitmap_get_or_circuit(). Because only circuit_t are indexed in the * hs_circuitmap_get_or_circuit(). Because only circuit_t are indexed in the
* circuitmap, this function returns object type so the specialized functions * circuitmap, this function returns object type so the specialized functions
* using this helper can upcast it to the right type. * using this helper can upcast it to the right type.
@ -220,7 +221,7 @@ hs_circuitmap_get_circuit_impl(hs_token_type_t type,
return found_circ; return found_circ;
} }
/* Helper function: Query circuitmap for origin circuit with <b>token</b> of /** Helper function: Query circuitmap for origin circuit with <b>token</b> of
* size <b>token_len</b> and <b>type</b>. Only returns a circuit with purpose * size <b>token_len</b> and <b>type</b>. Only returns a circuit with purpose
* equal to the <b>wanted_circ_purpose</b> parameter and if it is NOT marked * equal to the <b>wanted_circ_purpose</b> parameter and if it is NOT marked
* for close. Return NULL if no such circuit is found. */ * for close. Return NULL if no such circuit is found. */
@ -244,7 +245,7 @@ hs_circuitmap_get_origin_circuit(hs_token_type_t type,
return TO_ORIGIN_CIRCUIT(circ); return TO_ORIGIN_CIRCUIT(circ);
} }
/* Helper function: Query circuitmap for OR circuit with <b>token</b> of size /** Helper function: Query circuitmap for OR circuit with <b>token</b> of size
* <b>token_len</b> and <b>type</b>. Only returns a circuit with purpose equal * <b>token_len</b> and <b>type</b>. Only returns a circuit with purpose equal
* to the <b>wanted_circ_purpose</b> parameter and if it is NOT marked for * to the <b>wanted_circ_purpose</b> parameter and if it is NOT marked for
* close. Return NULL if no such circuit is found. */ * close. Return NULL if no such circuit is found. */
@ -272,7 +273,7 @@ hs_circuitmap_get_or_circuit(hs_token_type_t type,
/**** Public relay-side getters: */ /**** Public relay-side getters: */
/* Public function: Return v2 and v3 introduction circuit to this relay. /** Public function: Return v2 and v3 introduction circuit to this relay.
* Always return a newly allocated list for which it is the caller's * Always return a newly allocated list for which it is the caller's
* responsability to free it. */ * responsability to free it. */
smartlist_t * smartlist_t *
@ -299,7 +300,7 @@ hs_circuitmap_get_all_intro_circ_relay_side(void)
return circuit_list; return circuit_list;
} }
/* Public function: Return a v3 introduction circuit to this relay with /** Public function: Return a v3 introduction circuit to this relay with
* <b>auth_key</b>. Return NULL if no such circuit is found in the * <b>auth_key</b>. Return NULL if no such circuit is found in the
* circuitmap. */ * circuitmap. */
or_circuit_t * or_circuit_t *
@ -311,7 +312,7 @@ hs_circuitmap_get_intro_circ_v3_relay_side(
CIRCUIT_PURPOSE_INTRO_POINT); CIRCUIT_PURPOSE_INTRO_POINT);
} }
/* Public function: Return v2 introduction circuit to this relay with /** Public function: Return v2 introduction circuit to this relay with
* <b>digest</b>. Return NULL if no such circuit is found in the circuitmap. */ * <b>digest</b>. Return NULL if no such circuit is found in the circuitmap. */
or_circuit_t * or_circuit_t *
hs_circuitmap_get_intro_circ_v2_relay_side(const uint8_t *digest) hs_circuitmap_get_intro_circ_v2_relay_side(const uint8_t *digest)
@ -321,7 +322,7 @@ hs_circuitmap_get_intro_circ_v2_relay_side(const uint8_t *digest)
CIRCUIT_PURPOSE_INTRO_POINT); CIRCUIT_PURPOSE_INTRO_POINT);
} }
/* Public function: Return rendezvous circuit to this relay with rendezvous /** Public function: Return rendezvous circuit to this relay with rendezvous
* <b>cookie</b>. Return NULL if no such circuit is found in the circuitmap. */ * <b>cookie</b>. Return NULL if no such circuit is found in the circuitmap. */
or_circuit_t * or_circuit_t *
hs_circuitmap_get_rend_circ_relay_side(const uint8_t *cookie) hs_circuitmap_get_rend_circ_relay_side(const uint8_t *cookie)
@ -333,7 +334,7 @@ hs_circuitmap_get_rend_circ_relay_side(const uint8_t *cookie)
/** Public relay-side setters: */ /** Public relay-side setters: */
/* Public function: Register rendezvous circuit with key <b>cookie</b> to the /** Public function: Register rendezvous circuit with key <b>cookie</b> to the
* circuitmap. */ * circuitmap. */
void void
hs_circuitmap_register_rend_circ_relay_side(or_circuit_t *circ, hs_circuitmap_register_rend_circ_relay_side(or_circuit_t *circ,
@ -343,7 +344,7 @@ hs_circuitmap_register_rend_circ_relay_side(or_circuit_t *circ,
HS_TOKEN_REND_RELAY_SIDE, HS_TOKEN_REND_RELAY_SIDE,
REND_TOKEN_LEN, cookie); REND_TOKEN_LEN, cookie);
} }
/* Public function: Register v2 intro circuit with key <b>digest</b> to the /** Public function: Register v2 intro circuit with key <b>digest</b> to the
* circuitmap. */ * circuitmap. */
void void
hs_circuitmap_register_intro_circ_v2_relay_side(or_circuit_t *circ, hs_circuitmap_register_intro_circ_v2_relay_side(or_circuit_t *circ,
@ -354,7 +355,7 @@ hs_circuitmap_register_intro_circ_v2_relay_side(or_circuit_t *circ,
REND_TOKEN_LEN, digest); REND_TOKEN_LEN, digest);
} }
/* Public function: Register v3 intro circuit with key <b>auth_key</b> to the /** Public function: Register v3 intro circuit with key <b>auth_key</b> to the
* circuitmap. */ * circuitmap. */
void void
hs_circuitmap_register_intro_circ_v3_relay_side(or_circuit_t *circ, hs_circuitmap_register_intro_circ_v3_relay_side(or_circuit_t *circ,
@ -367,7 +368,7 @@ hs_circuitmap_register_intro_circ_v3_relay_side(or_circuit_t *circ,
/**** Public servide-side getters: */ /**** Public servide-side getters: */
/* Public function: Return v3 introduction circuit with <b>auth_key</b> /** Public function: Return v3 introduction circuit with <b>auth_key</b>
* originating from this hidden service. Return NULL if no such circuit is * originating from this hidden service. Return NULL if no such circuit is
* found in the circuitmap. */ * found in the circuitmap. */
origin_circuit_t * origin_circuit_t *
@ -392,9 +393,9 @@ hs_circuitmap_get_intro_circ_v3_service_side(const
return circ; return circ;
} }
/* Public function: Return v2 introduction circuit originating from this hidden /** Public function: Return v2 introduction circuit originating from this
* service with <b>digest</b>. Return NULL if no such circuit is found in the * hidden service with <b>digest</b>. Return NULL if no such circuit is found
* circuitmap. */ * in the circuitmap. */
origin_circuit_t * origin_circuit_t *
hs_circuitmap_get_intro_circ_v2_service_side(const uint8_t *digest) hs_circuitmap_get_intro_circ_v2_service_side(const uint8_t *digest)
{ {
@ -416,7 +417,7 @@ hs_circuitmap_get_intro_circ_v2_service_side(const uint8_t *digest)
return circ; return circ;
} }
/* Public function: Return rendezvous circuit originating from this hidden /** Public function: Return rendezvous circuit originating from this hidden
* service with rendezvous <b>cookie</b>. Return NULL if no such circuit is * service with rendezvous <b>cookie</b>. Return NULL if no such circuit is
* found in the circuitmap. */ * found in the circuitmap. */
origin_circuit_t * origin_circuit_t *
@ -439,7 +440,7 @@ hs_circuitmap_get_rend_circ_service_side(const uint8_t *cookie)
return circ; return circ;
} }
/* Public function: Return client-side rendezvous circuit with rendezvous /** Public function: Return client-side rendezvous circuit with rendezvous
* <b>cookie</b>. It will look for circuits with the following purposes: * <b>cookie</b>. It will look for circuits with the following purposes:
* a) CIRCUIT_PURPOSE_C_REND_READY: Established rend circuit (received * a) CIRCUIT_PURPOSE_C_REND_READY: Established rend circuit (received
@ -472,7 +473,7 @@ hs_circuitmap_get_rend_circ_client_side(const uint8_t *cookie)
return circ; return circ;
} }
/* Public function: Return client-side established rendezvous circuit with /** Public function: Return client-side established rendezvous circuit with
* rendezvous <b>cookie</b>. It will look for circuits with the following * rendezvous <b>cookie</b>. It will look for circuits with the following
* purposes: * purposes:
* *
@ -514,7 +515,7 @@ hs_circuitmap_get_established_rend_circ_client_side(const uint8_t *cookie)
/**** Public servide-side setters: */ /**** Public servide-side setters: */
/* Public function: Register v2 intro circuit with key <b>digest</b> to the /** Public function: Register v2 intro circuit with key <b>digest</b> to the
* circuitmap. */ * circuitmap. */
void void
hs_circuitmap_register_intro_circ_v2_service_side(origin_circuit_t *circ, hs_circuitmap_register_intro_circ_v2_service_side(origin_circuit_t *circ,
@ -525,7 +526,7 @@ hs_circuitmap_register_intro_circ_v2_service_side(origin_circuit_t *circ,
REND_TOKEN_LEN, digest); REND_TOKEN_LEN, digest);
} }
/* Public function: Register v3 intro circuit with key <b>auth_key</b> to the /** Public function: Register v3 intro circuit with key <b>auth_key</b> to the
* circuitmap. */ * circuitmap. */
void void
hs_circuitmap_register_intro_circ_v3_service_side(origin_circuit_t *circ, hs_circuitmap_register_intro_circ_v3_service_side(origin_circuit_t *circ,
@ -536,7 +537,7 @@ hs_circuitmap_register_intro_circ_v3_service_side(origin_circuit_t *circ,
ED25519_PUBKEY_LEN, auth_key->pubkey); ED25519_PUBKEY_LEN, auth_key->pubkey);
} }
/* Public function: Register rendezvous circuit with key <b>cookie</b> to the /** Public function: Register rendezvous circuit with key <b>cookie</b> to the
* circuitmap. */ * circuitmap. */
void void
hs_circuitmap_register_rend_circ_service_side(origin_circuit_t *circ, hs_circuitmap_register_rend_circ_service_side(origin_circuit_t *circ,
@ -547,7 +548,7 @@ hs_circuitmap_register_rend_circ_service_side(origin_circuit_t *circ,
REND_TOKEN_LEN, cookie); REND_TOKEN_LEN, cookie);
} }
/* Public function: Register rendezvous circuit with key <b>cookie</b> to the /** Public function: Register rendezvous circuit with key <b>cookie</b> to the
* client-side circuitmap. */ * client-side circuitmap. */
void void
hs_circuitmap_register_rend_circ_client_side(origin_circuit_t *or_circ, hs_circuitmap_register_rend_circ_client_side(origin_circuit_t *or_circ,
@ -591,7 +592,7 @@ hs_circuitmap_remove_circuit(circuit_t *circ)
circ->hs_token = NULL; circ->hs_token = NULL;
} }
/* Public function: Initialize the global HS circuitmap. */ /** Public function: Initialize the global HS circuitmap. */
void void
hs_circuitmap_init(void) hs_circuitmap_init(void)
{ {
@ -601,7 +602,7 @@ hs_circuitmap_init(void)
HT_INIT(hs_circuitmap_ht, the_hs_circuitmap); HT_INIT(hs_circuitmap_ht, the_hs_circuitmap);
} }
/* Public function: Free all memory allocated by the global HS circuitmap. */ /** Public function: Free all memory allocated by the global HS circuitmap. */
void void
hs_circuitmap_free_all(void) hs_circuitmap_free_all(void)
{ {

8
src/feature/hs/hs_common.c
View File

@ -305,9 +305,9 @@ hs_get_next_time_period_num(time_t now)
return hs_get_time_period_num(now) + 1; return hs_get_time_period_num(now) + 1;
} }
/* Get the number of the _previous_ HS time period, given that the current time /** Get the number of the _previous_ HS time period, given that the current
* is <b>now</b>. If <b>now</b> is not set, we try to get the time from a live * time is <b>now</b>. If <b>now</b> is not set, we try to get the time from a
* consensus. */ * live consensus. */
uint64_t uint64_t
hs_get_previous_time_period_num(time_t now) hs_get_previous_time_period_num(time_t now)
{ {
@ -725,7 +725,7 @@ build_blinded_key_param(const ed25519_public_key_t *pubkey,
memwipe(nonce, 0, sizeof(nonce)); memwipe(nonce, 0, sizeof(nonce));
} }
/* Using an ed25519 public key and version to build the checksum of an /** Using an ed25519 public key and version to build the checksum of an
* address. Put in checksum_out. Format is: * address. Put in checksum_out. Format is:
* SHA3-256(".onion checksum" || PUBKEY || VERSION) * SHA3-256(".onion checksum" || PUBKEY || VERSION)
* *

22
src/feature/hs/hs_config.c
View File

@ -34,7 +34,7 @@
#include "lib/encoding/confline.h" #include "lib/encoding/confline.h"
#include "app/config/or_options_st.h" #include "app/config/or_options_st.h"
/* Using the given list of services, stage them into our global state. Every /** Using the given list of services, stage them into our global state. Every
* service version are handled. This function can remove entries in the given * service version are handled. This function can remove entries in the given
* service_list. * service_list.
* *
@ -70,7 +70,7 @@ stage_services(smartlist_t *service_list)
hs_service_stage_services(service_list); hs_service_stage_services(service_list);
} }
/* Validate the given service against all service in the given list. If the /** Validate the given service against all service in the given list. If the
* service is ephemeral, this function ignores it. Services with the same * service is ephemeral, this function ignores it. Services with the same
* directory path aren't allowed and will return an error. If a duplicate is * directory path aren't allowed and will return an error. If a duplicate is
* found, 1 is returned else 0 if none found. */ * found, 1 is returned else 0 if none found. */
@ -118,7 +118,7 @@ service_is_duplicate_in_list(const smartlist_t *service_list,
return ret; return ret;
} }
/* Helper function: Given an configuration option name, its value, a minimum /** Helper function: Given an configuration option name, its value, a minimum
* min and a maxium max, parse the value as a uint64_t. On success, ok is set * min and a maxium max, parse the value as a uint64_t. On success, ok is set
* to 1 and ret is the parsed value. On error, ok is set to 0 and ret must be * to 1 and ret is the parsed value. On error, ok is set to 0 and ret must be
* ignored. This function logs both on error and success. */ * ignored. This function logs both on error and success. */
@ -173,7 +173,7 @@ helper_parse_circuit_id_protocol(const char *key, const char *value, int *ok)
return ret; return ret;
} }
/* Return the service version by trying to learn it from the key on disk if /** Return the service version by trying to learn it from the key on disk if
* any. If nothing is found, the current service configured version is * any. If nothing is found, the current service configured version is
* returned. */ * returned. */
static int static int
@ -191,7 +191,7 @@ config_learn_service_version(hs_service_t *service)
return version; return version;
} }
/* Return true iff the given options starting at line_ for a hidden service /** Return true iff the given options starting at line_ for a hidden service
* contains at least one invalid option. Each hidden service option don't * contains at least one invalid option. Each hidden service option don't
* apply to all versions so this function can find out. The line_ MUST start * apply to all versions so this function can find out. The line_ MUST start
* right after the HiddenServiceDir line of this service. * right after the HiddenServiceDir line of this service.
@ -273,7 +273,7 @@ config_has_invalid_options(const config_line_t *line_,
return ret; return ret;
} }
/* Validate service configuration. This is used when loading the configuration /** Validate service configuration. This is used when loading the configuration
* and once we've setup a service object, it's config object is passed to this * and once we've setup a service object, it's config object is passed to this
* function for further validation. This does not validate service key * function for further validation. This does not validate service key
* material. Return 0 if valid else -1 if invalid. */ * material. Return 0 if valid else -1 if invalid. */
@ -304,7 +304,7 @@ config_validate_service(const hs_service_config_t *config)
return -1; return -1;
} }
/* Configuration funcion for a version 3 service. The line_ must be pointing /** Configuration funcion for a version 3 service. The line_ must be pointing
* to the directive directly after a HiddenServiceDir. That way, when hitting * to the directive directly after a HiddenServiceDir. That way, when hitting
* the next HiddenServiceDir line or reaching the end of the list of lines, we * the next HiddenServiceDir line or reaching the end of the list of lines, we
* know that we have to stop looking for more options. The given service * know that we have to stop looking for more options. The given service
@ -423,7 +423,7 @@ config_service_v3(const config_line_t *line_,
return -1; return -1;
} }
/* Configure a service using the given options in line_ and options. This is /** Configure a service using the given options in line_ and options. This is
* called for any service regardless of its version which means that all * called for any service regardless of its version which means that all
* directives in this function are generic to any service version. This * directives in this function are generic to any service version. This
* function will also check the validity of the service directory path. * function will also check the validity of the service directory path.
@ -577,7 +577,7 @@ config_generic_service(const config_line_t *line_,
return -1; return -1;
} }
/* Configure a service using the given line and options. This function will /** Configure a service using the given line and options. This function will
* call the corresponding configuration function for a specific service * call the corresponding configuration function for a specific service
* version and validate the service against the other ones. On success, add * version and validate the service against the other ones. On success, add
* the service to the given list and return 0. On error, nothing is added to * the service to the given list and return 0. On error, nothing is added to
@ -663,7 +663,7 @@ config_service(const config_line_t *line, const or_options_t *options,
return -1; return -1;
} }
/* From a set of <b>options</b>, setup every hidden service found. Return 0 on /** From a set of <b>options</b>, setup every hidden service found. Return 0 on
* success or -1 on failure. If <b>validate_only</b> is set, parse, warn and * success or -1 on failure. If <b>validate_only</b> is set, parse, warn and
* return as normal, but don't actually change the configured services. */ * return as normal, but don't actually change the configured services. */
int int
@ -731,7 +731,7 @@ hs_config_service_all(const or_options_t *options, int validate_only)
return ret; return ret;
} }
/* From a set of <b>options</b>, setup every client authorization found. /** From a set of <b>options</b>, setup every client authorization found.
* Return 0 on success or -1 on failure. If <b>validate_only</b> is set, * Return 0 on success or -1 on failure. If <b>validate_only</b> is set,
* parse, warn and return as normal, but don't actually change the * parse, warn and return as normal, but don't actually change the
* configured state. */ * configured state. */

18
src/feature/hs/hs_control.c
View File

@ -20,7 +20,7 @@
#include "feature/nodelist/node_st.h" #include "feature/nodelist/node_st.h"
#include "feature/nodelist/routerstatus_st.h" #include "feature/nodelist/routerstatus_st.h"
/* Send on the control port the "HS_DESC REQUESTED [...]" event. /** Send on the control port the "HS_DESC REQUESTED [...]" event.
* *
* The onion_pk is the onion service public key, base64_blinded_pk is the * The onion_pk is the onion service public key, base64_blinded_pk is the
* base64 encoded blinded key for the service and hsdir_rs is the routerstatus * base64 encoded blinded key for the service and hsdir_rs is the routerstatus
@ -57,7 +57,7 @@ hs_control_desc_event_requested(const ed25519_public_key_t *onion_pk,
memwipe(onion_address, 0, sizeof(onion_address)); memwipe(onion_address, 0, sizeof(onion_address));
} }
/* Send on the control port the "HS_DESC FAILED [...]" event. /** Send on the control port the "HS_DESC FAILED [...]" event.
* *
* Using a directory connection identifier, the HSDir identity digest and a * Using a directory connection identifier, the HSDir identity digest and a
* reason for the failure. None can be NULL. */ * reason for the failure. None can be NULL. */
@ -81,7 +81,7 @@ hs_control_desc_event_failed(const hs_ident_dir_conn_t *ident,
hsdir_id_digest, reason); hsdir_id_digest, reason);
} }
/* Send on the control port the "HS_DESC RECEIVED [...]" event. /** Send on the control port the "HS_DESC RECEIVED [...]" event.
* *
* Using a directory connection identifier and the HSDir identity digest. * Using a directory connection identifier and the HSDir identity digest.
* None can be NULL. */ * None can be NULL. */
@ -103,7 +103,7 @@ hs_control_desc_event_received(const hs_ident_dir_conn_t *ident,
hsdir_id_digest); hsdir_id_digest);
} }
/* Send on the control port the "HS_DESC CREATED [...]" event. /** Send on the control port the "HS_DESC CREATED [...]" event.
* *
* Using the onion address of the descriptor's service and the blinded public * Using the onion address of the descriptor's service and the blinded public
* key of the descriptor as a descriptor ID. None can be NULL. */ * key of the descriptor as a descriptor ID. None can be NULL. */
@ -124,7 +124,7 @@ hs_control_desc_event_created(const char *onion_address,
control_event_hs_descriptor_created(onion_address, base64_blinded_pk, -1); control_event_hs_descriptor_created(onion_address, base64_blinded_pk, -1);
} }
/* Send on the control port the "HS_DESC UPLOAD [...]" event. /** Send on the control port the "HS_DESC UPLOAD [...]" event.
* *
* Using the onion address of the descriptor's service, the HSDir identity * Using the onion address of the descriptor's service, the HSDir identity
* digest, the blinded public key of the descriptor as a descriptor ID and the * digest, the blinded public key of the descriptor as a descriptor ID and the
@ -151,7 +151,7 @@ hs_control_desc_event_upload(const char *onion_address,
DIGEST256_LEN)); DIGEST256_LEN));
} }
/* Send on the control port the "HS_DESC UPLOADED [...]" event. /** Send on the control port the "HS_DESC UPLOADED [...]" event.
* *
* Using the directory connection identifier and the HSDir identity digest. * Using the directory connection identifier and the HSDir identity digest.
* None can be NULL. */ * None can be NULL. */
@ -169,7 +169,7 @@ hs_control_desc_event_uploaded(const hs_ident_dir_conn_t *ident,
control_event_hs_descriptor_uploaded(hsdir_id_digest, onion_address); control_event_hs_descriptor_uploaded(hsdir_id_digest, onion_address);
} }
/* Send on the control port the "HS_DESC_CONTENT [...]" event. /** Send on the control port the "HS_DESC_CONTENT [...]" event.
* *
* Using the directory connection identifier, the HSDir identity digest and * Using the directory connection identifier, the HSDir identity digest and
* the body of the descriptor (as it was received from the directory). None * the body of the descriptor (as it was received from the directory). None
@ -193,7 +193,7 @@ hs_control_desc_event_content(const hs_ident_dir_conn_t *ident,
hsdir_id_digest, body); hsdir_id_digest, body);
} }
/* Handle the "HSPOST [...]" command. The body is an encoded descriptor for /** Handle the "HSPOST [...]" command. The body is an encoded descriptor for
* the given onion_address. The descriptor will be uploaded to each directory * the given onion_address. The descriptor will be uploaded to each directory
* in hsdirs_rs. If NULL, the responsible directories for the current time * in hsdirs_rs. If NULL, the responsible directories for the current time
* period will be selected. * period will be selected.
@ -248,7 +248,7 @@ hs_control_hspost_command(const char *body, const char *onion_address,
return ret; return ret;
} }
/* With a given <b>onion_identity_pk</b>, fetch its descriptor, optionally /** With a given <b>onion_identity_pk</b>, fetch its descriptor, optionally
* using the list of directory servers given in <b>hsdirs</b>, or a random * using the list of directory servers given in <b>hsdirs</b>, or a random
* server if it is NULL. This function calls hs_client_launch_v3_desc_fetch(). * server if it is NULL. This function calls hs_client_launch_v3_desc_fetch().
*/ */

26
src/feature/hs/hs_dos.c
View File

@ -31,21 +31,21 @@
#include "feature/hs/hs_dos.h" #include "feature/hs/hs_dos.h"
/* Default value of the allowed INTRODUCE2 cell rate per second. Above that /** Default value of the allowed INTRODUCE2 cell rate per second. Above that
* value per second, the introduction is denied. */ * value per second, the introduction is denied. */
#define HS_DOS_INTRODUCE_DEFAULT_CELL_RATE_PER_SEC 25 #define HS_DOS_INTRODUCE_DEFAULT_CELL_RATE_PER_SEC 25
/* Default value of the allowed INTRODUCE2 cell burst per second. This is the /** Default value of the allowed INTRODUCE2 cell burst per second. This is the
* maximum value a token bucket has per second. We thus allow up to this value * maximum value a token bucket has per second. We thus allow up to this value
* of INTRODUCE2 cell per second but the bucket is refilled by the rate value * of INTRODUCE2 cell per second but the bucket is refilled by the rate value
* but never goes above that burst value. */ * but never goes above that burst value. */
#define HS_DOS_INTRODUCE_DEFAULT_CELL_BURST_PER_SEC 200 #define HS_DOS_INTRODUCE_DEFAULT_CELL_BURST_PER_SEC 200
/* Default value of the consensus parameter enabling or disabling the /** Default value of the consensus parameter enabling or disabling the
* introduction DoS defense. Disabled by default. */ * introduction DoS defense. Disabled by default. */
#define HS_DOS_INTRODUCE_ENABLED_DEFAULT 0 #define HS_DOS_INTRODUCE_ENABLED_DEFAULT 0
/* INTRODUCE2 rejected request counter. */ /** INTRODUCE2 rejected request counter. */
static uint64_t intro2_rejected_count = 0; static uint64_t intro2_rejected_count = 0;
/* Consensus parameters. The ESTABLISH_INTRO DoS cell extension have higher /* Consensus parameters. The ESTABLISH_INTRO DoS cell extension have higher
@ -65,7 +65,7 @@ get_intro2_enable_consensus_param(const networkstatus_t *ns)
HS_DOS_INTRODUCE_ENABLED_DEFAULT, 0, 1); HS_DOS_INTRODUCE_ENABLED_DEFAULT, 0, 1);
} }
/* Return the parameter for the introduction rate per sec. */ /** Return the parameter for the introduction rate per sec. */
STATIC uint32_t STATIC uint32_t
get_intro2_rate_consensus_param(const networkstatus_t *ns) get_intro2_rate_consensus_param(const networkstatus_t *ns)
{ {
@ -74,7 +74,7 @@ get_intro2_rate_consensus_param(const networkstatus_t *ns)
0, INT32_MAX); 0, INT32_MAX);
} }
/* Return the parameter for the introduction burst per sec. */ /** Return the parameter for the introduction burst per sec. */
STATIC uint32_t STATIC uint32_t
get_intro2_burst_consensus_param(const networkstatus_t *ns) get_intro2_burst_consensus_param(const networkstatus_t *ns)
{ {
@ -83,7 +83,7 @@ get_intro2_burst_consensus_param(const networkstatus_t *ns)
0, INT32_MAX); 0, INT32_MAX);
} }
/* Go over all introduction circuit relay side and adjust their rate/burst /** Go over all introduction circuit relay side and adjust their rate/burst
* values using the global parameters. This is called right after the * values using the global parameters. This is called right after the
* consensus parameters might have changed. */ * consensus parameters might have changed. */
static void static void
@ -105,7 +105,7 @@ update_intro_circuits(void)
smartlist_free(intro_circs); smartlist_free(intro_circs);
} }
/* Set consensus parameters. */ /** Set consensus parameters. */
static void static void
set_consensus_parameters(const networkstatus_t *ns) set_consensus_parameters(const networkstatus_t *ns)
{ {
@ -125,7 +125,7 @@ set_consensus_parameters(const networkstatus_t *ns)
* Public API. * Public API.
*/ */
/* Initialize the INTRODUCE2 token bucket for the DoS defenses using the /** Initialize the INTRODUCE2 token bucket for the DoS defenses using the
* consensus/default values. We might get a cell extension that changes those * consensus/default values. We might get a cell extension that changes those
* later but if we don't, the default or consensus parameters are used. */ * later but if we don't, the default or consensus parameters are used. */
void void
@ -141,7 +141,7 @@ hs_dos_setup_default_intro2_defenses(or_circuit_t *circ)
(uint32_t) approx_time()); (uint32_t) approx_time());
} }
/* Called when the consensus has changed. We might have new consensus /** Called when the consensus has changed. We might have new consensus
* parameters to look at. */ * parameters to look at. */
void void
hs_dos_consensus_has_changed(const networkstatus_t *ns) hs_dos_consensus_has_changed(const networkstatus_t *ns)
@ -155,7 +155,7 @@ hs_dos_consensus_has_changed(const networkstatus_t *ns)
set_consensus_parameters(ns); set_consensus_parameters(ns);
} }
/* Return true iff an INTRODUCE2 cell can be sent on the given service /** Return true iff an INTRODUCE2 cell can be sent on the given service
* introduction circuit. */ * introduction circuit. */
bool bool
hs_dos_can_send_intro2(or_circuit_t *s_intro_circ) hs_dos_can_send_intro2(or_circuit_t *s_intro_circ)
@ -206,14 +206,14 @@ hs_dos_can_send_intro2(or_circuit_t *s_intro_circ)
return true; return true;
} }
/* Return rolling count of rejected INTRO2. */ /** Return rolling count of rejected INTRO2. */
uint64_t uint64_t
hs_dos_get_intro2_rejected_count(void) hs_dos_get_intro2_rejected_count(void)
{ {
return intro2_rejected_count; return intro2_rejected_count;
} }
/* Initialize the onion service Denial of Service subsystem. */ /** Initialize the onion service Denial of Service subsystem. */
void void
hs_dos_init(void) hs_dos_init(void)
{ {

30
src/feature/hs/hs_intropoint.c
View File

@ -147,7 +147,7 @@ verify_establish_intro_cell(const trn_cell_establish_intro_t *cell,
return 0; return 0;
} }
/* Send an INTRO_ESTABLISHED cell to <b>circ</b>. */ /** Send an INTRO_ESTABLISHED cell to <b>circ</b>. */
MOCK_IMPL(int, MOCK_IMPL(int,
hs_intro_send_intro_established_cell,(or_circuit_t *circ)) hs_intro_send_intro_established_cell,(or_circuit_t *circ))
{ {
@ -182,7 +182,7 @@ hs_intro_send_intro_established_cell,(or_circuit_t *circ))
return ret; return ret;
} }
/* Validate the cell DoS extension parameters. Return true iff they've been /** Validate the cell DoS extension parameters. Return true iff they've been
* bound check and can be used. Else return false. See proposal 305 for * bound check and can be used. Else return false. See proposal 305 for
* details and reasons about this validation. */ * details and reasons about this validation. */
STATIC bool STATIC bool
@ -244,7 +244,7 @@ cell_dos_extension_parameters_are_valid(uint64_t intro2_rate_per_sec,
return ret; return ret;
} }
/* Parse the cell DoS extension and apply defenses on the given circuit if /** Parse the cell DoS extension and apply defenses on the given circuit if
* validation passes. If the cell extension is malformed or contains unusable * validation passes. If the cell extension is malformed or contains unusable
* values, the DoS defenses is disabled on the circuit. */ * values, the DoS defenses is disabled on the circuit. */
static void static void
@ -321,7 +321,7 @@ handle_establish_intro_cell_dos_extension(
return; return;
} }
/* Parse every cell extension in the given ESTABLISH_INTRO cell. */ /** Parse every cell extension in the given ESTABLISH_INTRO cell. */
static void static void
handle_establish_intro_cell_extensions( handle_establish_intro_cell_extensions(
const trn_cell_establish_intro_t *parsed_cell, const trn_cell_establish_intro_t *parsed_cell,
@ -457,7 +457,7 @@ handle_establish_intro(or_circuit_t *circ, const uint8_t *request,
return retval; return retval;
} }
/* Return True if circuit is suitable for being an intro circuit. */ /** Return True if circuit is suitable for being an intro circuit. */
static int static int
circuit_is_suitable_intro_point(const or_circuit_t *circ, circuit_is_suitable_intro_point(const or_circuit_t *circ,
const char *log_cell_type_str) const char *log_cell_type_str)
@ -482,14 +482,14 @@ circuit_is_suitable_intro_point(const or_circuit_t *circ,
return 1; return 1;
} }
/* Return True if circuit is suitable for being service-side intro circuit. */ /** Return True if circuit is suitable for being service-side intro circuit. */
int int
hs_intro_circuit_is_suitable_for_establish_intro(const or_circuit_t *circ) hs_intro_circuit_is_suitable_for_establish_intro(const or_circuit_t *circ)
{ {
return circuit_is_suitable_intro_point(circ, "ESTABLISH_INTRO"); return circuit_is_suitable_intro_point(circ, "ESTABLISH_INTRO");
} }
/* We just received an ESTABLISH_INTRO cell in <b>circ</b>. Figure out of it's /** We just received an ESTABLISH_INTRO cell in <b>circ</b>. Figure out of it's
* a legacy or a next gen cell, and pass it to the appropriate handler. */ * a legacy or a next gen cell, and pass it to the appropriate handler. */
int int
hs_intro_received_establish_intro(or_circuit_t *circ, const uint8_t *request, hs_intro_received_establish_intro(or_circuit_t *circ, const uint8_t *request,
@ -523,7 +523,7 @@ hs_intro_received_establish_intro(or_circuit_t *circ, const uint8_t *request,
return -1; return -1;
} }
/* Send an INTRODUCE_ACK cell onto the circuit <b>circ</b> with the status /** Send an INTRODUCE_ACK cell onto the circuit <b>circ</b> with the status
* value in <b>status</b>. Depending on the status, it can be ACK or a NACK. * value in <b>status</b>. Depending on the status, it can be ACK or a NACK.
* Return 0 on success else a negative value on error which will close the * Return 0 on success else a negative value on error which will close the
* circuit. */ * circuit. */
@ -567,7 +567,7 @@ send_introduce_ack_cell(or_circuit_t *circ, uint16_t status)
return ret; return ret;
} }
/* Validate a parsed INTRODUCE1 <b>cell</b>. Return 0 if valid or else a /** Validate a parsed INTRODUCE1 <b>cell</b>. Return 0 if valid or else a
* negative value for an invalid cell that should be NACKed. */ * negative value for an invalid cell that should be NACKed. */
STATIC int STATIC int
validate_introduce1_parsed_cell(const trn_cell_introduce1_t *cell) validate_introduce1_parsed_cell(const trn_cell_introduce1_t *cell)
@ -613,7 +613,7 @@ validate_introduce1_parsed_cell(const trn_cell_introduce1_t *cell)
return -1; return -1;
} }
/* We just received a non legacy INTRODUCE1 cell on <b>client_circ</b> with /** We just received a non legacy INTRODUCE1 cell on <b>client_circ</b> with
* the payload in <b>request</b> of size <b>request_len</b>. Return 0 if * the payload in <b>request</b> of size <b>request_len</b>. Return 0 if
* everything went well, or -1 if an error occurred. This function is in charge * everything went well, or -1 if an error occurred. This function is in charge
* of sending back an INTRODUCE_ACK cell and will close client_circ on error. * of sending back an INTRODUCE_ACK cell and will close client_circ on error.
@ -712,7 +712,7 @@ handle_introduce1(or_circuit_t *client_circ, const uint8_t *request,
return ret; return ret;
} }
/* Identify if the encoded cell we just received is a legacy one or not. The /** Identify if the encoded cell we just received is a legacy one or not. The
* <b>request</b> should be at least DIGEST_LEN bytes long. */ * <b>request</b> should be at least DIGEST_LEN bytes long. */
STATIC int STATIC int
introduce1_cell_is_legacy(const uint8_t *request) introduce1_cell_is_legacy(const uint8_t *request)
@ -729,7 +729,7 @@ introduce1_cell_is_legacy(const uint8_t *request)
return 0; return 0;
} }
/* Return true iff the circuit <b>circ</b> is suitable for receiving an /** Return true iff the circuit <b>circ</b> is suitable for receiving an
* INTRODUCE1 cell. */ * INTRODUCE1 cell. */
STATIC int STATIC int
circuit_is_suitable_for_introduce1(const or_circuit_t *circ) circuit_is_suitable_for_introduce1(const or_circuit_t *circ)
@ -760,7 +760,7 @@ circuit_is_suitable_for_introduce1(const or_circuit_t *circ)
return 1; return 1;
} }
/* We just received an INTRODUCE1 cell on <b>circ</b>. Figure out which type /** We just received an INTRODUCE1 cell on <b>circ</b>. Figure out which type
* it is and pass it to the appropriate handler. Return 0 on success else a * it is and pass it to the appropriate handler. Return 0 on success else a
* negative value and the circuit is closed. */ * negative value and the circuit is closed. */
int int
@ -804,8 +804,8 @@ hs_intro_received_introduce1(or_circuit_t *circ, const uint8_t *request,
return -1; return -1;
} }
/* Clear memory allocated by the given intropoint object ip (but don't free the /** Clear memory allocated by the given intropoint object ip (but don't free
* object itself). */ * the object itself). */
void void
hs_intropoint_clear(hs_intropoint_t *ip) hs_intropoint_clear(hs_intropoint_t *ip)
{ {

9
src/feature/hs/hs_intropoint.h
View File

@ -12,15 +12,15 @@
#include "lib/crypt_ops/crypto_curve25519.h" #include "lib/crypt_ops/crypto_curve25519.h"
#include "feature/nodelist/torcert.h" #include "feature/nodelist/torcert.h"
/* Object containing introduction point common data between the service and /** Object containing introduction point common data between the service and
* the client side. */ * the client side. */
typedef struct hs_intropoint_t { typedef struct hs_intropoint_t {
/* Does this intro point only supports legacy ID ?. */ /** Does this intro point only supports legacy ID ?. */
unsigned int is_only_legacy : 1; unsigned int is_only_legacy : 1;
/* Authentication key certificate from the descriptor. */ /** Authentication key certificate from the descriptor. */
tor_cert_t *auth_key_cert; tor_cert_t *auth_key_cert;
/* A list of link specifier. */ /** A list of link specifier. */
smartlist_t *link_specifiers; smartlist_t *link_specifiers;
} hs_intropoint_t; } hs_intropoint_t;
@ -64,4 +64,3 @@ STATIC bool cell_dos_extension_parameters_are_valid(
#endif /* defined(HS_INTROPOINT_PRIVATE) */ #endif /* defined(HS_INTROPOINT_PRIVATE) */
#endif /* !defined(TOR_HS_INTRO_H) */ #endif /* !defined(TOR_HS_INTRO_H) */

8
src/feature/hs/hs_service.c
View File

@ -509,7 +509,7 @@ service_intro_point_new(const node_t *node)
return NULL; return NULL;
} }
/* Add the given intro point object to the given intro point map. The intro /** Add the given intro point object to the given intro point map. The intro
* point MUST have its RSA encryption key set if this is a legacy type or the * point MUST have its RSA encryption key set if this is a legacy type or the
* authentication key set otherwise. */ * authentication key set otherwise. */
STATIC void STATIC void
@ -1076,7 +1076,7 @@ load_service_keys(hs_service_t *service)
return ret; return ret;
} }
/* Check if the client file name is valid or not. Return 1 if valid, /** Check if the client file name is valid or not. Return 1 if valid,
* otherwise return 0. */ * otherwise return 0. */
STATIC int STATIC int
client_filename_is_valid(const char *filename) client_filename_is_valid(const char *filename)
@ -1737,7 +1737,7 @@ build_service_desc_encrypted(const hs_service_t *service,
return 0; return 0;
} }
/* Populate the descriptor superencrypted section from the given service /** Populate the descriptor superencrypted section from the given service
* object. This will generate a valid list of hs_desc_authorized_client_t * object. This will generate a valid list of hs_desc_authorized_client_t
* of clients that are authorized to use the service. Return 0 on success * of clients that are authorized to use the service. Return 0 on success
* else -1 on error. */ * else -1 on error. */
@ -2637,7 +2637,7 @@ run_build_descriptor_event(time_t now)
update_all_descriptors_intro_points(now); update_all_descriptors_intro_points(now);
} }
/* For the given service, launch any intro point circuits that could be /** For the given service, launch any intro point circuits that could be
* needed. This considers every descriptor of the service. */ * needed. This considers every descriptor of the service. */
static void static void
launch_intro_point_circuits(hs_service_t *service) launch_intro_point_circuits(hs_service_t *service)

6
src/feature/hs/hs_service.h
View File

@ -29,6 +29,7 @@
/** As described in the specification, service publishes their next descriptor /** As described in the specification, service publishes their next descriptor
* at a random time between those two values (in seconds). */ * at a random time between those two values (in seconds). */
#define HS_SERVICE_NEXT_UPLOAD_TIME_MIN (60 * 60) #define HS_SERVICE_NEXT_UPLOAD_TIME_MIN (60 * 60)
/** Maximum interval for uploading next descriptor (in seconds). */
#define HS_SERVICE_NEXT_UPLOAD_TIME_MAX (120 * 60) #define HS_SERVICE_NEXT_UPLOAD_TIME_MAX (120 * 60)
/** Service side introduction point. */ /** Service side introduction point. */
@ -316,6 +317,11 @@ void hs_service_free_all(void);
/* Service new/free functions. */ /* Service new/free functions. */
hs_service_t *hs_service_new(const or_options_t *options); hs_service_t *hs_service_new(const or_options_t *options);
void hs_service_free_(hs_service_t *service); void hs_service_free_(hs_service_t *service);
/**
* @copydoc hs_service_free_
*
* Additionally, set the pointer <b>s</b> to NULL.
**/
#define hs_service_free(s) FREE_AND_NULL(hs_service_t, hs_service_free_, (s)) #define hs_service_free(s) FREE_AND_NULL(hs_service_t, hs_service_free_, (s))
MOCK_DECL(unsigned int, hs_service_get_num_services,(void)); MOCK_DECL(unsigned int, hs_service_get_num_services,(void));

7
src/feature/hs/hsdir_index_st.h
View File

@ -12,16 +12,17 @@
#ifndef HSDIR_INDEX_ST_H #ifndef HSDIR_INDEX_ST_H
#define HSDIR_INDEX_ST_H #define HSDIR_INDEX_ST_H
/* Hidden service directory index used in a node_t which is set once we set /** Hidden service directory index used in a node_t which is set once we set
* the consensus. */ * the consensus. */
struct hsdir_index_t { struct hsdir_index_t {
/* HSDir index to use when fetching a descriptor. */ /** HSDir index to use when fetching a descriptor. */
uint8_t fetch[DIGEST256_LEN]; uint8_t fetch[DIGEST256_LEN];
/* HSDir index used by services to store their first and second /** HSDir index used by services to store their first and second
* descriptor. The first descriptor is chronologically older than the second * descriptor. The first descriptor is chronologically older than the second
* one and uses older TP and SRV values. */ * one and uses older TP and SRV values. */
uint8_t store_first[DIGEST256_LEN]; uint8_t store_first[DIGEST256_LEN];
/** Newer index, for second descriptor. */
uint8_t store_second[DIGEST256_LEN]; uint8_t store_second[DIGEST256_LEN];
}; };

13
src/feature/hs_common/replaycache.h
View File

@ -14,16 +14,16 @@ typedef struct replaycache_t replaycache_t;
#ifdef REPLAYCACHE_PRIVATE #ifdef REPLAYCACHE_PRIVATE
struct replaycache_t { struct replaycache_t {
/* Scrub interval */ /** Scrub interval */
time_t scrub_interval; time_t scrub_interval;
/* Last scrubbed */ /** Last scrubbed */
time_t scrubbed; time_t scrubbed;
/* /**
* Horizon * Horizon
* (don't return true on digests in the cache but older than this) * (don't return true on digests in the cache but older than this)
*/ */
time_t horizon; time_t horizon;
/* /**
* Digest map: keys are digests, values are times the digest was last seen * Digest map: keys are digests, values are times the digest was last seen
*/ */
digest256map_t *digests_seen; digest256map_t *digests_seen;
@ -34,6 +34,11 @@ struct replaycache_t {
/* replaycache_t free/new */ /* replaycache_t free/new */
void replaycache_free_(replaycache_t *r); void replaycache_free_(replaycache_t *r);
/**
* @copydoc replaycache_free_
*
* Additionally, set the pointer <b>r</b> to NULL.
**/
#define replaycache_free(r) \ #define replaycache_free(r) \
FREE_AND_NULL(replaycache_t, replaycache_free_, (r)) FREE_AND_NULL(replaycache_t, replaycache_free_, (r))
replaycache_t * replaycache_new(time_t horizon, time_t interval); replaycache_t * replaycache_new(time_t horizon, time_t interval);

19
src/feature/hs_common/shared_random_client.c
View File

@ -18,7 +18,7 @@
#include "feature/nodelist/networkstatus_st.h" #include "feature/nodelist/networkstatus_st.h"
/* Convert a given srv object to a string for the control port. This doesn't /** Convert a given srv object to a string for the control port. This doesn't
* fail and the srv object MUST be valid. */ * fail and the srv object MUST be valid. */
static char * static char *
srv_to_control_string(const sr_srv_t *srv) srv_to_control_string(const sr_srv_t *srv)
@ -32,7 +32,7 @@ srv_to_control_string(const sr_srv_t *srv)
return srv_str; return srv_str;
} }
/* Return the voting interval of the tor vote subsystem. */ /** Return the voting interval of the tor vote subsystem. */
int int
get_voting_interval(void) get_voting_interval(void)
{ {
@ -51,7 +51,7 @@ get_voting_interval(void)
return interval; return interval;
} }
/* Given the current consensus, return the start time of the current round of /** Given the current consensus, return the start time of the current round of
* the SR protocol. For example, if it's 23:47:08, the current round thus * the SR protocol. For example, if it's 23:47:08, the current round thus
* started at 23:47:00 for a voting interval of 10 seconds. * started at 23:47:00 for a voting interval of 10 seconds.
* *
@ -78,7 +78,7 @@ get_start_time_of_current_round(void)
* Public API * Public API
*/ */
/* Encode the given shared random value and put it in dst. Destination /** Encode the given shared random value and put it in dst. Destination
* buffer must be at least SR_SRV_VALUE_BASE64_LEN plus the NULL byte. */ * buffer must be at least SR_SRV_VALUE_BASE64_LEN plus the NULL byte. */
void void
sr_srv_encode(char *dst, size_t dst_len, const sr_srv_t *srv) sr_srv_encode(char *dst, size_t dst_len, const sr_srv_t *srv)
@ -99,7 +99,7 @@ sr_srv_encode(char *dst, size_t dst_len, const sr_srv_t *srv)
strlcpy(dst, buf, dst_len); strlcpy(dst, buf, dst_len);
} }
/* Return the current SRV string representation for the control port. Return a /** Return the current SRV string representation for the control port. Return a
* newly allocated string on success containing the value else "" if not found * newly allocated string on success containing the value else "" if not found
* or if we don't have a valid consensus yet. */ * or if we don't have a valid consensus yet. */
char * char *
@ -115,7 +115,7 @@ sr_get_current_for_control(void)
return srv_str; return srv_str;
} }
/* Return the previous SRV string representation for the control port. Return /** Return the previous SRV string representation for the control port. Return
* a newly allocated string on success containing the value else "" if not * a newly allocated string on success containing the value else "" if not
* found or if we don't have a valid consensus yet. */ * found or if we don't have a valid consensus yet. */
char * char *
@ -131,7 +131,7 @@ sr_get_previous_for_control(void)
return srv_str; return srv_str;
} }
/* Return current shared random value from the latest consensus. Caller can /** Return current shared random value from the latest consensus. Caller can
* NOT keep a reference to the returned pointer. Return NULL if none. */ * NOT keep a reference to the returned pointer. Return NULL if none. */
const sr_srv_t * const sr_srv_t *
sr_get_current(const networkstatus_t *ns) sr_get_current(const networkstatus_t *ns)
@ -154,7 +154,7 @@ sr_get_current(const networkstatus_t *ns)
return NULL; return NULL;
} }
/* Return previous shared random value from the latest consensus. Caller can /** Return previous shared random value from the latest consensus. Caller can
* NOT keep a reference to the returned pointer. Return NULL if none. */ * NOT keep a reference to the returned pointer. Return NULL if none. */
const sr_srv_t * const sr_srv_t *
sr_get_previous(const networkstatus_t *ns) sr_get_previous(const networkstatus_t *ns)
@ -177,7 +177,7 @@ sr_get_previous(const networkstatus_t *ns)
return NULL; return NULL;
} }
/* Parse a list of arguments from a SRV value either from a vote, consensus /** Parse a list of arguments from a SRV value either from a vote, consensus
* or from our disk state and return a newly allocated srv object. NULL is * or from our disk state and return a newly allocated srv object. NULL is
* returned on error. * returned on error.
* *
@ -290,4 +290,3 @@ sr_state_get_protocol_run_duration(void)
int total_protocol_rounds = SHARED_RANDOM_N_ROUNDS * SHARED_RANDOM_N_PHASES; int total_protocol_rounds = SHARED_RANDOM_N_ROUNDS * SHARED_RANDOM_N_PHASES;
return total_protocol_rounds * get_voting_interval(); return total_protocol_rounds * get_voting_interval();
} }