[tor-commits] [tor/master] hs_client.[ch]: fix doxygen comments by using /**.

commit 1b66668e26764c98d4e5348947a35c1d8ae9f92b Author: Nick Mathewson nickm@torproject.org Date: Wed Oct 16 11:51:47 2019 -0400

hs_client.[ch]: fix doxygen comments by using /**. --- src/feature/hs/hs_client.c | 92 +++++++++++++++++++++++----------------------- src/feature/hs/hs_client.h | 21 +++++------ 2 files changed, 56 insertions(+), 57 deletions(-)

diff --git a/src/feature/hs/hs_client.c b/src/feature/hs/hs_client.c index f8d47f011..4ed34aa9a 100644 --- a/src/feature/hs/hs_client.c +++ b/src/feature/hs/hs_client.c @@ -43,13 +43,13 @@ #include "core/or/extend_info_st.h" #include "core/or/origin_circuit_st.h"

-/* Client-side authorizations for hidden services; map of service identity +/** Client-side authorizations for hidden services; map of service identity * public key to hs_client_service_authorization_t *. */ static digest256map_t *client_auths = NULL;

#include "trunnel/hs/cell_introduce1.h"

-/* Return a human-readable string for the client fetch status code. */ +/** Return a human-readable string for the client fetch status code. */ static const char * fetch_status_to_string(hs_client_fetch_status_t status) { @@ -73,7 +73,7 @@ fetch_status_to_string(hs_client_fetch_status_t status) } }

-/* Return true iff tor should close the SOCKS request(s) for the descriptor +/** Return true iff tor should close the SOCKS request(s) for the descriptor * fetch that ended up with this given status code. */ static int fetch_status_should_close_socks(hs_client_fetch_status_t status) @@ -100,7 +100,7 @@ fetch_status_should_close_socks(hs_client_fetch_status_t status) return 1; }

-/* Cancel all descriptor fetches currently in progress. */ +/** Cancel all descriptor fetches currently in progress. */ static void cancel_descriptor_fetches(void) { @@ -124,7 +124,7 @@ cancel_descriptor_fetches(void) log_info(LD_REND, "Hidden service client descriptor fetches cancelled."); }

-/* Get all connections that are waiting on a circuit and flag them back to +/** Get all connections that are waiting on a circuit and flag them back to * waiting for a hidden service descriptor for the given service key * service_identity_pk. */ static void @@ -151,7 +151,7 @@ flag_all_conn_wait_desc(const ed25519_public_key_t *service_identity_pk) smartlist_free(conns); }

-/* Remove tracked HSDir requests from our history for this hidden service +/** Remove tracked HSDir requests from our history for this hidden service * identity public key. */ static void purge_hid_serv_request(const ed25519_public_key_t *identity_pk) @@ -172,7 +172,7 @@ purge_hid_serv_request(const ed25519_public_key_t *identity_pk) hs_purge_hid_serv_from_last_hid_serv_requests(base64_blinded_pk); }

-/* Return true iff there is at least one pending directory descriptor request +/** Return true iff there is at least one pending directory descriptor request * for the service identity_pk. */ static int directory_request_is_pending(const ed25519_public_key_t *identity_pk) @@ -200,7 +200,7 @@ directory_request_is_pending(const ed25519_public_key_t *identity_pk) return ret; }

-/* Helper function that changes the state of an entry connection to waiting +/** Helper function that changes the state of an entry connection to waiting * for a circuit. For this to work properly, the connection timestamps are set * to now and the connection is then marked as pending for a circuit. */ static void @@ -220,7 +220,7 @@ mark_conn_as_waiting_for_circuit(connection_t *conn, time_t now) connection_ap_mark_as_pending_circuit(TO_ENTRY_CONN(conn)); }

-/* We failed to fetch a descriptor for the service with <b>identity_pk</b> +/** We failed to fetch a descriptor for the service with <b>identity_pk</b> * because of <b>status</b>. Find all pending SOCKS connections for this * service that are waiting on the descriptor and close them with * <b>reason</b>. */ @@ -265,7 +265,7 @@ close_all_socks_conns_waiting_for_desc(const ed25519_public_key_t *identity_pk, smartlist_free(conns); }

-/* Find all pending SOCKS connection waiting for a descriptor and retry them +/** Find all pending SOCKS connection waiting for a descriptor and retry them * all. This is called when the directory information changed. */ STATIC void retry_all_socks_conn_waiting_for_desc(void) @@ -321,7 +321,7 @@ retry_all_socks_conn_waiting_for_desc(void) smartlist_free(conns); }

-/* A v3 HS circuit successfully connected to the hidden service. Update the +/** A v3 HS circuit successfully connected to the hidden service. Update the * stream state at <b>hs_conn_ident</b> appropriately. */ static void note_connection_attempt_succeeded(const hs_ident_edge_conn_t *hs_conn_ident) @@ -343,7 +343,7 @@ note_connection_attempt_succeeded(const hs_ident_edge_conn_t *hs_conn_ident) * will be reset and thus possible to be retried. */ }

-/* Given the pubkey of a hidden service in <b>onion_identity_pk</b>, fetch its +/** Given the pubkey of a hidden service in <b>onion_identity_pk</b>, fetch its * descriptor by launching a dir connection to <b>hsdir</b>. Return a * hs_client_fetch_status_t status code depending on how it went. */ static hs_client_fetch_status_t @@ -451,7 +451,7 @@ fetch_v3_desc, (const ed25519_public_key_t *onion_identity_pk)) return directory_launch_v3_desc_fetch(onion_identity_pk, hsdir_rs); }

-/* With a given <b>onion_identity_pk</b>, fetch its descriptor. If +/** With a given <b>onion_identity_pk</b>, fetch its descriptor. If * <b>hsdirs</b> is specified, use the directory servers specified in the list. * Else, use a random server. */ void @@ -469,7 +469,7 @@ hs_client_launch_v3_desc_fetch(const ed25519_public_key_t *onion_identity_pk, } }

-/* Make sure that the given v3 origin circuit circ is a valid correct +/** Make sure that the given v3 origin circuit circ is a valid correct * introduction circuit. This will BUG() on any problems and hard assert if * the anonymity of the circuit is not ok. Return 0 on success else -1 where * the circuit should be mark for closed immediately. */ @@ -498,7 +498,7 @@ intro_circ_is_ok(const origin_circuit_t *circ) return ret; }

-/* Find a descriptor intro point object that matches the given ident in the +/** Find a descriptor intro point object that matches the given ident in the * given descriptor desc. Return NULL if not found. */ static const hs_desc_intro_point_t * find_desc_intro_point_by_ident(const hs_ident_circuit_t *ident, @@ -521,7 +521,7 @@ find_desc_intro_point_by_ident(const hs_ident_circuit_t *ident, return intro_point; }

-/* Find a descriptor intro point object from the descriptor object desc that +/** Find a descriptor intro point object from the descriptor object desc that * matches the given legacy identity digest in legacy_id. Return NULL if not * found. */ static hs_desc_intro_point_t * @@ -559,7 +559,7 @@ find_desc_intro_point_by_legacy_id(const char *legacy_id, return ret_ip; }

-/* Send an INTRODUCE1 cell along the intro circuit and populate the rend +/** Send an INTRODUCE1 cell along the intro circuit and populate the rend * circuit identifier with the needed key material for the e2e encryption. * Return 0 on success, -1 if there is a transient error such that an action * has been taken to recover and -2 if there is a permanent error indicating @@ -671,7 +671,7 @@ send_introduce1(origin_circuit_t *intro_circ, return status; }

-/* Using the introduction circuit circ, setup the authentication key of the +/** Using the introduction circuit circ, setup the authentication key of the * intro point this circuit has extended to. */ static void setup_intro_circ_auth_key(origin_circuit_t *circ) @@ -706,7 +706,7 @@ setup_intro_circ_auth_key(origin_circuit_t *circ) return; }

-/* Called when an introduction circuit has opened. */ +/** Called when an introduction circuit has opened. */ static void client_intro_circ_has_opened(origin_circuit_t *circ) { @@ -723,7 +723,7 @@ client_intro_circ_has_opened(origin_circuit_t *circ) connection_ap_attach_pending(1); }

-/* Called when a rendezvous circuit has opened. */ +/** Called when a rendezvous circuit has opened. */ static void client_rendezvous_circ_has_opened(origin_circuit_t *circ) { @@ -757,7 +757,7 @@ client_rendezvous_circ_has_opened(origin_circuit_t *circ) } }

-/* This is an helper function that convert a descriptor intro point object ip +/** This is an helper function that convert a descriptor intro point object ip * to a newly allocated extend_info_t object fully initialized. Return NULL if * we can't convert it for which chances are that we are missing or malformed * link specifiers. */ @@ -775,7 +775,7 @@ desc_intro_point_to_extend_info(const hs_desc_intro_point_t *ip) return ei; }

-/* Return true iff the intro point ip for the service service_pk is usable. +/** Return true iff the intro point ip for the service service_pk is usable. * This function checks if the intro point is in the client intro state cache * and checks at the failures. It is considered usable if: * - No error happened (INTRO_POINT_FAILURE_GENERIC) @@ -820,7 +820,7 @@ intro_point_is_usable(const ed25519_public_key_t *service_pk, return 0; }

-/* Using a descriptor desc, return a newly allocated extend_info_t object of a +/** Using a descriptor desc, return a newly allocated extend_info_t object of a * randomly picked introduction point from its list. Return NULL if none are * usable. */ STATIC extend_info_t * @@ -925,7 +925,7 @@ client_get_random_intro(const ed25519_public_key_t *service_pk) return ei; }

-/* For this introduction circuit, we'll look at if we have any usable +/** For this introduction circuit, we'll look at if we have any usable * introduction point left for this service. If so, we'll use the circuit to * re-extend to a new intro point. Else, we'll close the circuit and its * corresponding rendezvous circuit. Return 0 if we are re-extending else -1 @@ -982,7 +982,7 @@ close_or_reextend_intro_circ(origin_circuit_t *intro_circ) return ret; }

-/* Called when we get an INTRODUCE_ACK success status code. Do the appropriate +/** Called when we get an INTRODUCE_ACK success status code. Do the appropriate * actions for the rendezvous point and finally close intro_circ. */ static void handle_introduce_ack_success(origin_circuit_t *intro_circ) @@ -1028,7 +1028,7 @@ handle_introduce_ack_success(origin_circuit_t *intro_circ) return; }

-/* Called when we get an INTRODUCE_ACK failure status code. Depending on our +/** Called when we get an INTRODUCE_ACK failure status code. Depending on our * failure cache status, either close the circuit or re-extend to a new * introduction point. */ static void @@ -1050,7 +1050,7 @@ handle_introduce_ack_bad(origin_circuit_t *circ, int status) INTRO_POINT_FAILURE_GENERIC); }

-/* Called when we get an INTRODUCE_ACK on the intro circuit circ. The encoded +/** Called when we get an INTRODUCE_ACK on the intro circuit circ. The encoded * cell is in payload of length payload_len. Return 0 on success else a * negative value. The circuit is either close or reuse to re-extend to a new * introduction point. */ @@ -1089,7 +1089,7 @@ handle_introduce_ack(origin_circuit_t *circ, const uint8_t *payload, return ret; }

-/* Called when we get a RENDEZVOUS2 cell on the rendezvous circuit circ. The +/** Called when we get a RENDEZVOUS2 cell on the rendezvous circuit circ. The * encoded cell is in payload of length payload_len. Return 0 on success or a * negative value on error. On error, the circuit is marked for close. */ STATIC int @@ -1151,7 +1151,7 @@ handle_rendezvous2(origin_circuit_t *circ, const uint8_t *payload, return ret; }

-/* Return true iff the client can fetch a descriptor for this service public +/** Return true iff the client can fetch a descriptor for this service public * identity key and status_out if not NULL is untouched. If the client can * _not_ fetch the descriptor and if status_out is not NULL, it is set with * the fetch status code. */ @@ -1218,7 +1218,7 @@ can_client_refetch_desc(const ed25519_public_key_t *identity_pk, return 0; }

-/* Return the client auth in the map using the service identity public key. +/** Return the client auth in the map using the service identity public key. * Return NULL if it does not exist in the map. */ static hs_client_service_authorization_t * find_client_auth(const ed25519_public_key_t *service_identity_pk) @@ -1256,7 +1256,7 @@ hs_client_note_connection_attempt_succeeded(const edge_connection_t *conn) } }

-/* With the given encoded descriptor in desc_str and the service key in +/** With the given encoded descriptor in desc_str and the service key in * service_identity_pk, decode the descriptor and set the desc pointer with a * newly allocated descriptor object. * @@ -1315,7 +1315,7 @@ hs_client_decode_descriptor(const char *desc_str, return -1; }

-/* Return true iff there are at least one usable intro point in the service +/** Return true iff there are at least one usable intro point in the service * descriptor desc. */ int hs_client_any_intro_points_usable(const ed25519_public_key_t *service_pk, @@ -1364,7 +1364,7 @@ hs_client_refetch_hsdesc(const ed25519_public_key_t *identity_pk) return status; }

-/* This is called when we are trying to attach an AP connection to these +/** This is called when we are trying to attach an AP connection to these * hidden service circuits from connection_ap_handshake_attach_circuit(). * Return 0 on success, -1 for a transient error that is actions were * triggered to recover or -2 for a permenent error where both circuits will @@ -1380,7 +1380,7 @@ hs_client_send_introduce1(origin_circuit_t *intro_circ, rend_circ); }

-/* Called when the client circuit circ has been established. It can be either +/** Called when the client circuit circ has been established. It can be either * an introduction or rendezvous circuit. This function handles all hidden * service versions. */ void @@ -1410,7 +1410,7 @@ hs_client_circuit_has_opened(origin_circuit_t *circ) } }

-/* Called when we receive a RENDEZVOUS_ESTABLISHED cell. Change the state of +/** Called when we receive a RENDEZVOUS_ESTABLISHED cell. Change the state of * the circuit to CIRCUIT_PURPOSE_C_REND_READY. Return 0 on success else a * negative value and the circuit marked for close. */ int @@ -1481,7 +1481,7 @@ client_service_authorization_free_all(void) digest256map_free(client_auths, client_service_authorization_free_void); }

-/* Check if the auth key file name is valid or not. Return 1 if valid, +/** Check if the auth key file name is valid or not. Return 1 if valid, * otherwise return 0. */ STATIC int auth_key_filename_is_valid(const char *filename) @@ -1566,7 +1566,7 @@ parse_auth_file_content(const char *client_key_str) return auth; }

-/* From a set of <b>options</b>, setup every client authorization detail +/** From a set of <b>options</b>, setup every client authorization detail * found. 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 configuration. */ @@ -1681,7 +1681,7 @@ hs_config_client_authorization(const or_options_t *options, return ret; }

-/* This is called when a descriptor has arrived following a fetch request and +/** This is called when a descriptor has arrived following a fetch request and * has been stored in the client cache. Every entry connection that matches * the service identity key in the ident will get attached to the hidden * service circuit. */ @@ -1739,7 +1739,7 @@ hs_client_desc_has_arrived(const hs_ident_dir_conn_t *ident) smartlist_free(conns); }

-/* Return a newly allocated extend_info_t for a randomly chosen introduction +/** Return a newly allocated extend_info_t for a randomly chosen introduction * point for the given edge connection identifier ident. Return NULL if we * can't pick any usable introduction points. */ extend_info_t * @@ -1752,7 +1752,7 @@ hs_client_get_random_intro_from_edge(const edge_connection_t *edge_conn) rend_client_get_random_intro(edge_conn->rend_data); }

-/* Called when get an INTRODUCE_ACK cell on the introduction circuit circ. +/** Called when get an INTRODUCE_ACK cell on the introduction circuit circ. * Return 0 on success else a negative value is returned. The circuit will be * closed or reuse to extend again to another intro point. */ int @@ -1781,7 +1781,7 @@ hs_client_receive_introduce_ack(origin_circuit_t *circ, return ret; }

-/* Called when get a RENDEZVOUS2 cell on the rendezvous circuit circ. Return +/** Called when get a RENDEZVOUS2 cell on the rendezvous circuit circ. Return * 0 on success else a negative value is returned. The circuit will be closed * on error. */ int @@ -1814,7 +1814,7 @@ hs_client_receive_rendezvous2(origin_circuit_t *circ, return ret; }

-/* Extend the introduction circuit circ to another valid introduction point +/** Extend the introduction circuit circ to another valid introduction point * for the hidden service it is trying to connect to, or mark it and launch a * new circuit if we can't extend it. Return 0 on success or possible * success. Return -1 and mark the introduction circuit for close on permanent @@ -1864,7 +1864,7 @@ hs_client_reextend_intro_circuit(origin_circuit_t *circ) return ret; }

-/* Close all client introduction circuits related to the given descriptor. +/** Close all client introduction circuits related to the given descriptor. * This is called with a descriptor that is about to get replaced in the * client cache. * @@ -1896,7 +1896,7 @@ hs_client_close_intro_circuits_from_desc(const hs_descriptor_t *desc) } }

-/* Release all the storage held by the client subsystem. */ +/** Release all the storage held by the client subsystem. */ void hs_client_free_all(void) { @@ -1905,7 +1905,7 @@ hs_client_free_all(void) client_service_authorization_free_all(); }

-/* Purge all potentially remotely-detectable state held in the hidden +/** Purge all potentially remotely-detectable state held in the hidden * service client code. Called on SIGNAL NEWNYM. */ void hs_client_purge_state(void) @@ -1926,7 +1926,7 @@ hs_client_purge_state(void) log_info(LD_REND, "Hidden service client state has been purged."); }

-/* Called when our directory information has changed. */ +/** Called when our directory information has changed. */ void hs_client_dir_info_changed(void) { diff --git a/src/feature/hs/hs_client.h b/src/feature/hs/hs_client.h index 96a96755f..69e48ca31 100644 --- a/src/feature/hs/hs_client.h +++ b/src/feature/hs/hs_client.h @@ -13,31 +13,31 @@ #include "feature/hs/hs_descriptor.h" #include "feature/hs/hs_ident.h"

-/* Status code of a descriptor fetch request. */ +/** Status code of a descriptor fetch request. */ typedef enum { - /* Something internally went wrong. */ + /** Something internally went wrong. */ HS_CLIENT_FETCH_ERROR = -1, - /* The fetch request has been launched successfully. */ + /** The fetch request has been launched successfully. */ HS_CLIENT_FETCH_LAUNCHED = 0, - /* We already have a usable descriptor. No fetch. */ + /** We already have a usable descriptor. No fetch. */ HS_CLIENT_FETCH_HAVE_DESC = 1, - /* No more HSDir available to query. */ + /** No more HSDir available to query. */ HS_CLIENT_FETCH_NO_HSDIRS = 2, - /* The fetch request is not allowed. */ + /** The fetch request is not allowed. */ HS_CLIENT_FETCH_NOT_ALLOWED = 3, - /* We are missing information to be able to launch a request. */ + /** We are missing information to be able to launch a request. */ HS_CLIENT_FETCH_MISSING_INFO = 4, - /* There is a pending fetch for the requested service. */ + /** There is a pending fetch for the requested service. */ HS_CLIENT_FETCH_PENDING = 5, } hs_client_fetch_status_t;

/** Client-side configuration of authorization for a service. */ typedef struct hs_client_service_authorization_t { - /* An curve25519 secret key used to compute decryption keys that + /** An curve25519 secret key used to compute decryption keys that * allow the client to decrypt the hidden service descriptor. */ curve25519_secret_key_t enc_seckey;

- /* An onion address that is used to connect to the onion service. */ + /** An onion address that is used to connect to the onion service. */ char onion_address[HS_SERVICE_ADDR_LEN_BASE32+1]; } hs_client_service_authorization_t;

@@ -120,4 +120,3 @@ STATIC digest256map_t *get_hs_client_auths_map(void); #endif /* defined(HS_CLIENT_PRIVATE) */

#endif /* !defined(TOR_HS_CLIENT_H) */ -