Fix various doxygen comments in feature/hs.

#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

 * <b>circ_purpose</b> and ensure that it's properly set. Return true iff

 * circuit purpose is properly set, otherwise return false. */

static int

  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 <b>ntor_key_seed</b>.

 *

  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

 * 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

  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. */

static void

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,

  }

}

/* 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,

  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,

  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,

  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

  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)

{

  }

}

/* 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

  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)

  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)

{

  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.

/* 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)

  }

}

/* 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 *

  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.

 *

  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.

 *

  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

  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. */

  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. */

  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. */

  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

 * 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

  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

 * extend the crypt path of <b>circ</b> so that the hidden service is on the

 * other side. */

  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.

 *

  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)

  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

 * safely for the same circuit. */

void

/************************** 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)

                   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)

{

                               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

#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)

{

  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>. */

static void

hs_circuitmap_register_impl(circuit_t *circ, hs_token_t *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

 * circuitmap, this function returns object type so the specialized functions

 * using this helper can upcast it to the right type.

  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

 * 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. */

  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

 * to the <b>wanted_circ_purpose</b> parameter and if it is NOT marked for

 * close. Return NULL if no such circuit is found. */

/**** 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 *

  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

 * circuitmap. */

or_circuit_t *

                                      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. */

or_circuit_t *

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

 * <b>cookie</b>. 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)

/** 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. */

void

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 <b>digest</b> to the

/** Public function: Register v2 intro circuit with key <b>digest</b> to the

 * circuitmap. */

void

hs_circuitmap_register_intro_circ_v2_relay_side(or_circuit_t *circ,

                                 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. */

void

hs_circuitmap_register_intro_circ_v3_relay_side(or_circuit_t *circ,

/**** 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

 * found in the circuitmap. */

origin_circuit_t *

  return circ;

}

/* Public function: Return v2 introduction circuit originating from this hidden

 * service with <b>digest</b>. Return NULL if no such circuit is found in the

 * circuitmap. */

/** Public function: Return v2 introduction circuit originating from this

 * hidden service with <b>digest</b>. 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)

{

  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

 * found in the circuitmap. */

origin_circuit_t *

  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:

 * a) CIRCUIT_PURPOSE_C_REND_READY: Established rend circuit (received

  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

 *  purposes:

 *

/**** 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. */

void

hs_circuitmap_register_intro_circ_v2_service_side(origin_circuit_t *circ,

                                 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. */

void

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 <b>cookie</b> to the

/** Public function: Register rendezvous circuit with key <b>cookie</b> to the

 * circuitmap. */

void

hs_circuitmap_register_rend_circ_service_side(origin_circuit_t *circ,

                                 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. */

void

hs_circuitmap_register_rend_circ_client_side(origin_circuit_t *or_circ,

  circ->hs_token = NULL;

}

/* Public function: Initialize the global HS circuitmap. */

/** Public function: Initialize the global HS circuitmap. */

void

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)

{

  return hs_get_time_period_num(now) + 1;

}

/* Get the number of the _previous_ HS time period, given that the current time

 * is <b>now</b>. If <b>now</b> 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 <b>now</b>. If <b>now</b> is not set, we try to get the time from a

 * live consensus. */

uint64_t

hs_get_previous_time_period_num(time_t now)

{

  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)

 *

#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.

 *

  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. */

  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. */

  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

  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.

  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. */

  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

  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.

  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

  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

 * return as normal, but don't actually change the configured services. */

int

  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,

 * parse, warn and return as normal, but don't actually change the

 * configured state. */