diff --git a/src/feature/hs/hs_circuit.c b/src/feature/hs/hs_circuit.c index e1e9c7c790..9d21acf42f 100644 --- a/src/feature/hs/hs_circuit.c +++ b/src/feature/hs/hs_circuit.c @@ -40,7 +40,7 @@ #include "feature/nodelist/node_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 * circ_purpose and ensure that it's properly set. Return true iff * circuit purpose is properly set, otherwise return false. */ static int @@ -67,7 +67,7 @@ circuit_purpose_is_correct_for_rend(unsigned int circ_purpose, 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 * ntor key exchange at ntor_key_seed. * @@ -101,7 +101,7 @@ create_rend_cpath(const uint8_t *ntor_key_seed, size_t seed_len, 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 circ. Initialize * the crypt path crypto using the body of the RENDEZVOUS1 cell at * rend_cell_body (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; } -/* Append the final hop to the cpath of the rend circ, and mark +/** Append the final hop to the cpath of the rend circ, and mark * circ ready for use to transfer HS relay cells. */ static void 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. */ static void 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. */ static unsigned int 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; } -/* 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. */ STATIC hs_ident_circuit_t * create_rp_circuit_identifier(const hs_service_t *service, @@ -282,7 +282,7 @@ create_rp_circuit_identifier(const hs_service_t *service, 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. */ static hs_ident_circuit_t * create_intro_circuit_identifier(const hs_service_t *service, @@ -299,7 +299,7 @@ create_intro_circuit_identifier(const hs_service_t *service, 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 * 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 @@ -349,7 +349,7 @@ send_establish_intro(const hs_service_t *service, 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 * 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 * 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 @@ -469,7 +469,7 @@ launch_rendezvous_point_circuit(const hs_service_t *service, 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. */ static int 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; } -/* 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 retry_service_rendezvous_point(const origin_circuit_t *circ) { @@ -565,7 +565,7 @@ retry_service_rendezvous_point(const origin_circuit_t *circ) 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 * already allocated intro1_data object with the needed key material and link * specifiers. @@ -622,7 +622,7 @@ setup_introduce1_data(const hs_desc_intro_point_t *ip, /* 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. */ origin_circuit_t * 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 * is returned is no such circuit can be found. */ 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; } -/* 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 * supports legacy service. * @@ -698,7 +698,7 @@ hs_circ_retry_service_rendezvous_point(origin_circuit_t *circ) 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, * a one-hop circuit will be requested. * @@ -759,7 +759,7 @@ hs_circ_launch_intro_point(hs_service_t *service, 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 * 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 @@ -828,7 +828,7 @@ hs_circ_service_intro_has_opened(hs_service_t *service, 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 * circuit using the information in the circuit identifier. If the cell can't * 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)); } -/* 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 * given introduction circuit circ. The service is only used for logging * 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; } -/* 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 * circuit and service. This cell is associated with the intro point object ip * 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; } -/* Circuit circ just finished the rend ntor key exchange. Use the key +/** Circuit circ just finished the rend ntor key exchange. Use the key * exchange output material at ntor_key_seed and setup circ to * serve as a rendezvous end-to-end circuit between the client and the * service. If is_service_side is set, then we are the hidden service @@ -1036,7 +1036,7 @@ hs_circuit_setup_e2e_rend_circ(origin_circuit_t *circ, 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 * rend_cell_body on circ. Finish up the DH key exchange and then * extend the crypt path of circ so that the hidden service is on the * other side. */ @@ -1061,7 +1061,7 @@ hs_circuit_setup_e2e_rend_circ_legacy_client(origin_circuit_t *circ, 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 * subcredential, send an INTRODUCE1 cell on intro_circ. * @@ -1146,7 +1146,7 @@ hs_circ_send_introduce1(origin_circuit_t *intro_circ, 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. */ int hs_circ_send_establish_rendezvous(origin_circuit_t *circ) @@ -1197,7 +1197,7 @@ hs_circ_send_establish_rendezvous(origin_circuit_t *circ) return -1; } -/* We are about to close or free this circ. Clean it up from any +/** We are about to close or free this circ. Clean it up from any * related HS data structures. This function can be called multiple times * safely for the same circuit. */ void diff --git a/src/feature/hs/hs_circuitmap.c b/src/feature/hs/hs_circuitmap.c index e34f564fb4..0df4519488 100644 --- a/src/feature/hs/hs_circuitmap.c +++ b/src/feature/hs/hs_circuitmap.c @@ -23,13 +23,13 @@ /************************** 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 token it's easy to find the corresponding circuit. */ 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 - * two circuits have the same HS token. */ +/** This is a helper function used by the hash table code (HT_). It returns 1 + * if two circuits have the same HS token. */ static int hs_circuits_have_same_token(const circuit_t *first_circuit, const circuit_t *second_circuit) @@ -60,8 +60,9 @@ hs_circuits_have_same_token(const circuit_t *first_circuit, first_token->token_len); } -/* This is a helper function for the hash table code (HT_). It hashes a circuit - * HS token into an unsigned int for use as a key by the hash table routines.*/ +/** This is a helper function for the hash table code (HT_). It hashes a + * circuit HS token into an unsigned int for use as a key by the hash table + * routines.*/ static inline unsigned int 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); } -/* Register the circuitmap hash table */ +/** Register the circuitmap hash table */ HT_PROTOTYPE(hs_circuitmap_ht, // The name of the hashtable struct circuit_t, // The name of the element struct, 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 -/* Return the global HS circuitmap. Used by unittests. */ +/** Return the global HS circuitmap. Used by unittests. */ hs_circuitmap_ht * 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); } -/* Helper function that registers circ with token on the HS +/** Helper function that registers circ with token on the HS circuitmap. This function steals reference of token. */ static void 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); } -/* 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 * circuitmap, this function returns object type so the specialized functions * 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; } -/* Helper function: Query circuitmap for origin circuit with token of +/** Helper function: Query circuitmap for origin circuit with token of * size token_len and type. Only returns a circuit with purpose * equal to the wanted_circ_purpose parameter and if it is NOT marked * 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); } -/* Helper function: Query circuitmap for OR circuit with token of size +/** Helper function: Query circuitmap for OR circuit with token of size * token_len and type. Only returns a circuit with purpose equal * to the wanted_circ_purpose parameter and if it is NOT marked for * 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 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 * responsability to free it. */ smartlist_t * @@ -299,7 +300,7 @@ hs_circuitmap_get_all_intro_circ_relay_side(void) 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 * auth_key. Return NULL if no such circuit is found in the * circuitmap. */ or_circuit_t * @@ -311,7 +312,7 @@ hs_circuitmap_get_intro_circ_v3_relay_side( CIRCUIT_PURPOSE_INTRO_POINT); } -/* Public function: Return v2 introduction circuit to this relay with +/** Public function: Return v2 introduction circuit to this relay with * digest. Return NULL if no such circuit is found in the circuitmap. */ or_circuit_t * 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); } -/* Public function: Return rendezvous circuit to this relay with rendezvous +/** Public function: Return rendezvous circuit to this relay with rendezvous * cookie. Return NULL if no such circuit is found in the circuitmap. */ or_circuit_t * 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 function: Register rendezvous circuit with key cookie to the +/** Public function: Register rendezvous circuit with key cookie to the * circuitmap. */ void 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, REND_TOKEN_LEN, cookie); } -/* Public function: Register v2 intro circuit with key digest to the +/** Public function: Register v2 intro circuit with key digest to the * circuitmap. */ void 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); } -/* Public function: Register v3 intro circuit with key auth_key to the +/** Public function: Register v3 intro circuit with key auth_key to the * circuitmap. */ void 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 function: Return v3 introduction circuit with auth_key +/** Public function: Return v3 introduction circuit with auth_key * originating from this hidden service. Return NULL if no such circuit is * found in the circuitmap. */ origin_circuit_t * @@ -392,9 +393,9 @@ hs_circuitmap_get_intro_circ_v3_service_side(const return circ; } -/* Public function: Return v2 introduction circuit originating from this hidden - * service with digest. Return NULL if no such circuit is found in the - * circuitmap. */ +/** Public function: Return v2 introduction circuit originating from this + * hidden service with digest. Return NULL if no such circuit is found + * in the circuitmap. */ origin_circuit_t * 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; } -/* Public function: Return rendezvous circuit originating from this hidden +/** Public function: Return rendezvous circuit originating from this hidden * service with rendezvous cookie. Return NULL if no such circuit is * found in the circuitmap. */ origin_circuit_t * @@ -439,7 +440,7 @@ hs_circuitmap_get_rend_circ_service_side(const uint8_t *cookie) return circ; } -/* Public function: Return client-side rendezvous circuit with rendezvous +/** Public function: Return client-side rendezvous circuit with rendezvous * cookie. It will look for circuits with the following purposes: * 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; } -/* Public function: Return client-side established rendezvous circuit with +/** Public function: Return client-side established rendezvous circuit with * rendezvous cookie. It will look for circuits with the following * purposes: * @@ -514,7 +515,7 @@ hs_circuitmap_get_established_rend_circ_client_side(const uint8_t *cookie) /**** Public servide-side setters: */ -/* Public function: Register v2 intro circuit with key digest to the +/** Public function: Register v2 intro circuit with key digest to the * circuitmap. */ void 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); } -/* Public function: Register v3 intro circuit with key auth_key to the +/** Public function: Register v3 intro circuit with key auth_key to the * circuitmap. */ void 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); } -/* Public function: Register rendezvous circuit with key cookie to the +/** Public function: Register rendezvous circuit with key cookie to the * circuitmap. */ void 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); } -/* Public function: Register rendezvous circuit with key cookie to the +/** Public function: Register rendezvous circuit with key cookie to the * client-side circuitmap. */ void 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; } -/* Public function: Initialize the global HS circuitmap. */ +/** Public function: Initialize the global HS circuitmap. */ void hs_circuitmap_init(void) { @@ -601,7 +602,7 @@ hs_circuitmap_init(void) 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 hs_circuitmap_free_all(void) { diff --git a/src/feature/hs/hs_common.c b/src/feature/hs/hs_common.c index cf98bea320..75f4385eea 100644 --- a/src/feature/hs/hs_common.c +++ b/src/feature/hs/hs_common.c @@ -305,9 +305,9 @@ hs_get_next_time_period_num(time_t now) return hs_get_time_period_num(now) + 1; } -/* Get the number of the _previous_ HS time period, given that the current time - * is now. If now is not set, we try to get the time from a live - * consensus. */ +/** Get the number of the _previous_ HS time period, given that the current + * time is now. If now is not set, we try to get the time from a + * live consensus. */ uint64_t 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)); } -/* 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: * SHA3-256(".onion checksum" || PUBKEY || VERSION) * diff --git a/src/feature/hs/hs_config.c b/src/feature/hs/hs_config.c index 3b6caaec6a..ed577daf7d 100644 --- a/src/feature/hs/hs_config.c +++ b/src/feature/hs/hs_config.c @@ -34,7 +34,7 @@ #include "lib/encoding/confline.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_list. * @@ -70,7 +70,7 @@ stage_services(smartlist_t *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 * directory path aren't allowed and will return an error. If a duplicate is * 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; } -/* 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 * 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. */ @@ -173,7 +173,7 @@ helper_parse_circuit_id_protocol(const char *key, const char *value, int *ok) 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 * returned. */ static int @@ -191,7 +191,7 @@ config_learn_service_version(hs_service_t *service) 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 * apply to all versions so this function can find out. The line_ MUST start * right after the HiddenServiceDir line of this service. @@ -273,7 +273,7 @@ config_has_invalid_options(const config_line_t *line_, 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 * function for further validation. This does not validate service key * material. Return 0 if valid else -1 if invalid. */ @@ -304,7 +304,7 @@ config_validate_service(const hs_service_config_t *config) 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 * 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 @@ -423,7 +423,7 @@ config_service_v3(const config_line_t *line_, 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 * directives in this function are generic to any service version. This * 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; } -/* 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 * 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 @@ -663,7 +663,7 @@ config_service(const config_line_t *line, const or_options_t *options, return -1; } -/* From a set of options, setup every hidden service found. Return 0 on +/** From a set of options, setup every hidden service found. Return 0 on * success or -1 on failure. If validate_only is set, parse, warn and * return as normal, but don't actually change the configured services. */ int @@ -731,7 +731,7 @@ hs_config_service_all(const or_options_t *options, int validate_only) return ret; } -/* From a set of options, setup every client authorization found. +/** From a set of options, setup every client authorization found. * Return 0 on success or -1 on failure. If validate_only is set, * parse, warn and return as normal, but don't actually change the * configured state. */ diff --git a/src/feature/hs/hs_control.c b/src/feature/hs/hs_control.c index abb421345c..461be3e1e4 100644 --- a/src/feature/hs/hs_control.c +++ b/src/feature/hs/hs_control.c @@ -20,7 +20,7 @@ #include "feature/nodelist/node_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 * 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)); } -/* 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 * 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); } -/* 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. * None can be NULL. */ @@ -103,7 +103,7 @@ hs_control_desc_event_received(const hs_ident_dir_conn_t *ident, 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 * 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); } -/* 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 * 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)); } -/* 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. * 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); } -/* 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 * 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); } -/* 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 * in hsdirs_rs. If NULL, the responsible directories for the current time * period will be selected. @@ -248,7 +248,7 @@ hs_control_hspost_command(const char *body, const char *onion_address, return ret; } -/* With a given onion_identity_pk, fetch its descriptor, optionally +/** With a given onion_identity_pk, fetch its descriptor, optionally * using the list of directory servers given in hsdirs, or a random * server if it is NULL. This function calls hs_client_launch_v3_desc_fetch(). */ diff --git a/src/feature/hs/hs_dos.c b/src/feature/hs/hs_dos.c index d36ee97e6b..529955b0e7 100644 --- a/src/feature/hs/hs_dos.c +++ b/src/feature/hs/hs_dos.c @@ -31,21 +31,21 @@ #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. */ #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 * of INTRODUCE2 cell per second but the bucket is refilled by the rate value * but never goes above that burst value. */ #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. */ #define HS_DOS_INTRODUCE_ENABLED_DEFAULT 0 -/* INTRODUCE2 rejected request counter. */ +/** INTRODUCE2 rejected request counter. */ static uint64_t intro2_rejected_count = 0; /* 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); } -/* Return the parameter for the introduction rate per sec. */ +/** Return the parameter for the introduction rate per sec. */ STATIC uint32_t 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); } -/* Return the parameter for the introduction burst per sec. */ +/** Return the parameter for the introduction burst per sec. */ STATIC uint32_t 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); } -/* 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 * consensus parameters might have changed. */ static void @@ -105,7 +105,7 @@ update_intro_circuits(void) smartlist_free(intro_circs); } -/* Set consensus parameters. */ +/** Set consensus parameters. */ static void set_consensus_parameters(const networkstatus_t *ns) { @@ -125,7 +125,7 @@ set_consensus_parameters(const networkstatus_t *ns) * 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 * later but if we don't, the default or consensus parameters are used. */ void @@ -141,7 +141,7 @@ hs_dos_setup_default_intro2_defenses(or_circuit_t *circ) (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. */ void 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); } -/* 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. */ bool 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 rolling count of rejected INTRO2. */ +/** Return rolling count of rejected INTRO2. */ uint64_t hs_dos_get_intro2_rejected_count(void) { return intro2_rejected_count; } -/* Initialize the onion service Denial of Service subsystem. */ +/** Initialize the onion service Denial of Service subsystem. */ void hs_dos_init(void) { diff --git a/src/feature/hs/hs_intropoint.c b/src/feature/hs/hs_intropoint.c index fe8486b1a6..c3889004f2 100644 --- a/src/feature/hs/hs_intropoint.c +++ b/src/feature/hs/hs_intropoint.c @@ -147,7 +147,7 @@ verify_establish_intro_cell(const trn_cell_establish_intro_t *cell, return 0; } -/* Send an INTRO_ESTABLISHED cell to circ. */ +/** Send an INTRO_ESTABLISHED cell to circ. */ MOCK_IMPL(int, 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; } -/* 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 * details and reasons about this validation. */ STATIC bool @@ -244,7 +244,7 @@ cell_dos_extension_parameters_are_valid(uint64_t intro2_rate_per_sec, 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 * values, the DoS defenses is disabled on the circuit. */ static void @@ -321,7 +321,7 @@ handle_establish_intro_cell_dos_extension( return; } -/* Parse every cell extension in the given ESTABLISH_INTRO cell. */ +/** Parse every cell extension in the given ESTABLISH_INTRO cell. */ static void handle_establish_intro_cell_extensions( 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 True if circuit is suitable for being an intro circuit. */ +/** Return True if circuit is suitable for being an intro circuit. */ static int circuit_is_suitable_intro_point(const or_circuit_t *circ, const char *log_cell_type_str) @@ -482,14 +482,14 @@ circuit_is_suitable_intro_point(const or_circuit_t *circ, 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 hs_intro_circuit_is_suitable_for_establish_intro(const or_circuit_t *circ) { return circuit_is_suitable_intro_point(circ, "ESTABLISH_INTRO"); } -/* We just received an ESTABLISH_INTRO cell in circ. Figure out of it's +/** We just received an ESTABLISH_INTRO cell in circ. Figure out of it's * a legacy or a next gen cell, and pass it to the appropriate handler. */ int 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; } -/* Send an INTRODUCE_ACK cell onto the circuit circ with the status +/** Send an INTRODUCE_ACK cell onto the circuit circ with the status * value in status. 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 * circuit. */ @@ -567,7 +567,7 @@ send_introduce_ack_cell(or_circuit_t *circ, uint16_t status) return ret; } -/* Validate a parsed INTRODUCE1 cell. Return 0 if valid or else a +/** Validate a parsed INTRODUCE1 cell. Return 0 if valid or else a * negative value for an invalid cell that should be NACKed. */ STATIC int 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; } -/* We just received a non legacy INTRODUCE1 cell on client_circ with +/** We just received a non legacy INTRODUCE1 cell on client_circ with * the payload in request of size request_len. Return 0 if * 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. @@ -712,7 +712,7 @@ handle_introduce1(or_circuit_t *client_circ, const uint8_t *request, 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 * request should be at least DIGEST_LEN bytes long. */ STATIC int introduce1_cell_is_legacy(const uint8_t *request) @@ -729,7 +729,7 @@ introduce1_cell_is_legacy(const uint8_t *request) return 0; } -/* Return true iff the circuit circ is suitable for receiving an +/** Return true iff the circuit circ is suitable for receiving an * INTRODUCE1 cell. */ STATIC int 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; } -/* We just received an INTRODUCE1 cell on circ. Figure out which type +/** We just received an INTRODUCE1 cell on circ. Figure out which type * it is and pass it to the appropriate handler. Return 0 on success else a * negative value and the circuit is closed. */ int @@ -804,8 +804,8 @@ hs_intro_received_introduce1(or_circuit_t *circ, const uint8_t *request, return -1; } -/* Clear memory allocated by the given intropoint object ip (but don't free the - * object itself). */ +/** Clear memory allocated by the given intropoint object ip (but don't free + * the object itself). */ void hs_intropoint_clear(hs_intropoint_t *ip) { diff --git a/src/feature/hs/hs_intropoint.h b/src/feature/hs/hs_intropoint.h index 94ebf021e4..f4d7ad2637 100644 --- a/src/feature/hs/hs_intropoint.h +++ b/src/feature/hs/hs_intropoint.h @@ -12,15 +12,15 @@ #include "lib/crypt_ops/crypto_curve25519.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. */ 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; - /* Authentication key certificate from the descriptor. */ + /** Authentication key certificate from the descriptor. */ tor_cert_t *auth_key_cert; - /* A list of link specifier. */ + /** A list of link specifier. */ smartlist_t *link_specifiers; } hs_intropoint_t; @@ -64,4 +64,3 @@ STATIC bool cell_dos_extension_parameters_are_valid( #endif /* defined(HS_INTROPOINT_PRIVATE) */ #endif /* !defined(TOR_HS_INTRO_H) */ - diff --git a/src/feature/hs/hs_service.c b/src/feature/hs/hs_service.c index d0fb77fdaa..5693cdb0f1 100644 --- a/src/feature/hs/hs_service.c +++ b/src/feature/hs/hs_service.c @@ -509,7 +509,7 @@ service_intro_point_new(const node_t *node) 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 * authentication key set otherwise. */ STATIC void @@ -1076,7 +1076,7 @@ load_service_keys(hs_service_t *service) 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. */ STATIC int client_filename_is_valid(const char *filename) @@ -1737,7 +1737,7 @@ build_service_desc_encrypted(const hs_service_t *service, 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 * of clients that are authorized to use the service. Return 0 on success * else -1 on error. */ @@ -2637,7 +2637,7 @@ run_build_descriptor_event(time_t 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. */ static void launch_intro_point_circuits(hs_service_t *service) diff --git a/src/feature/hs/hs_service.h b/src/feature/hs/hs_service.h index 193e08546f..6c929c7ff1 100644 --- a/src/feature/hs/hs_service.h +++ b/src/feature/hs/hs_service.h @@ -29,6 +29,7 @@ /** As described in the specification, service publishes their next descriptor * at a random time between those two values (in seconds). */ #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) /** Service side introduction point. */ @@ -316,6 +317,11 @@ void hs_service_free_all(void); /* Service new/free functions. */ hs_service_t *hs_service_new(const or_options_t *options); void hs_service_free_(hs_service_t *service); +/** + * @copydoc hs_service_free_ + * + * Additionally, set the pointer s to NULL. + **/ #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)); diff --git a/src/feature/hs/hsdir_index_st.h b/src/feature/hs/hsdir_index_st.h index 34ff84f91f..0a0ac8ae6a 100644 --- a/src/feature/hs/hsdir_index_st.h +++ b/src/feature/hs/hsdir_index_st.h @@ -12,16 +12,17 @@ #ifndef 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. */ 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]; - /* 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 * one and uses older TP and SRV values. */ uint8_t store_first[DIGEST256_LEN]; + /** Newer index, for second descriptor. */ uint8_t store_second[DIGEST256_LEN]; }; diff --git a/src/feature/hs_common/replaycache.h b/src/feature/hs_common/replaycache.h index 01f5e600c2..812a05d260 100644 --- a/src/feature/hs_common/replaycache.h +++ b/src/feature/hs_common/replaycache.h @@ -14,16 +14,16 @@ typedef struct replaycache_t replaycache_t; #ifdef REPLAYCACHE_PRIVATE struct replaycache_t { - /* Scrub interval */ + /** Scrub interval */ time_t scrub_interval; - /* Last scrubbed */ + /** Last scrubbed */ time_t scrubbed; - /* + /** * Horizon * (don't return true on digests in the cache but older than this) */ time_t horizon; - /* + /** * Digest map: keys are digests, values are times the digest was last seen */ digest256map_t *digests_seen; @@ -34,6 +34,11 @@ struct replaycache_t { /* replaycache_t free/new */ void replaycache_free_(replaycache_t *r); +/** + * @copydoc replaycache_free_ + * + * Additionally, set the pointer r to NULL. + **/ #define replaycache_free(r) \ FREE_AND_NULL(replaycache_t, replaycache_free_, (r)) replaycache_t * replaycache_new(time_t horizon, time_t interval); diff --git a/src/feature/hs_common/shared_random_client.c b/src/feature/hs_common/shared_random_client.c index 5772034c6d..f5328e6e10 100644 --- a/src/feature/hs_common/shared_random_client.c +++ b/src/feature/hs_common/shared_random_client.c @@ -18,7 +18,7 @@ #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. */ static char * 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 the voting interval of the tor vote subsystem. */ +/** Return the voting interval of the tor vote subsystem. */ int get_voting_interval(void) { @@ -51,7 +51,7 @@ get_voting_interval(void) 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 * 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 */ -/* 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. */ void 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); } -/* 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 * or if we don't have a valid consensus yet. */ char * @@ -115,7 +115,7 @@ sr_get_current_for_control(void) 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 * found or if we don't have a valid consensus yet. */ char * @@ -131,7 +131,7 @@ sr_get_previous_for_control(void) 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. */ const sr_srv_t * sr_get_current(const networkstatus_t *ns) @@ -154,7 +154,7 @@ sr_get_current(const networkstatus_t *ns) 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. */ const sr_srv_t * sr_get_previous(const networkstatus_t *ns) @@ -177,7 +177,7 @@ sr_get_previous(const networkstatus_t *ns) 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 * 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; return total_protocol_rounds * get_voting_interval(); } -