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

hs_common.[ch]: repair doxygen comments by replacing /* with /**

Browse Source
This commit is contained in:
Nick Mathewson 2019-10-16 11:39:10 -04:00
parent 2127d797e9
commit 123fe6bdc5
2 changed files with 85 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -44,7 +44,7 @@
/* Trunnel */ /* Trunnel */
#include "trunnel/ed25519_cert.h" #include "trunnel/ed25519_cert.h"
/* Ed25519 Basepoint value. Taken from section 5 of /** Ed25519 Basepoint value. Taken from section 5 of
* https://tools.ietf.org/html/draft-josefsson-eddsa-ed25519-03 */ * https://tools.ietf.org/html/draft-josefsson-eddsa-ed25519-03 */
static const char *str_ed25519_basepoint = static const char *str_ed25519_basepoint =
"(15112221349535400772501151409588531511" "(15112221349535400772501151409588531511"
@ -106,7 +106,7 @@ add_unix_port(smartlist_t *ports, rend_service_port_config_t *p)
#endif /* defined(HAVE_SYS_UN_H) */ #endif /* defined(HAVE_SYS_UN_H) */
/* Helper function: The key is a digest that we compare to a node_t object /** Helper function: The key is a digest that we compare to a node_t object
* current hsdir_index. */ * current hsdir_index. */
static int static int
compare_digest_to_fetch_hsdir_index(const void *_key, const void **_member) compare_digest_to_fetch_hsdir_index(const void *_key, const void **_member)
@ -116,7 +116,7 @@ compare_digest_to_fetch_hsdir_index(const void *_key, const void **_member)
return tor_memcmp(key, node->hsdir_index.fetch, DIGEST256_LEN); return tor_memcmp(key, node->hsdir_index.fetch, DIGEST256_LEN);
} }
/* Helper function: The key is a digest that we compare to a node_t object /** Helper function: The key is a digest that we compare to a node_t object
* next hsdir_index. */ * next hsdir_index. */
static int static int
compare_digest_to_store_first_hsdir_index(const void *_key, compare_digest_to_store_first_hsdir_index(const void *_key,
@ -127,7 +127,7 @@ compare_digest_to_store_first_hsdir_index(const void *_key,
return tor_memcmp(key, node->hsdir_index.store_first, DIGEST256_LEN); return tor_memcmp(key, node->hsdir_index.store_first, DIGEST256_LEN);
} }
/* Helper function: The key is a digest that we compare to a node_t object /** Helper function: The key is a digest that we compare to a node_t object
* next hsdir_index. */ * next hsdir_index. */
static int static int
compare_digest_to_store_second_hsdir_index(const void *_key, compare_digest_to_store_second_hsdir_index(const void *_key,
@ -138,7 +138,7 @@ compare_digest_to_store_second_hsdir_index(const void *_key,
return tor_memcmp(key, node->hsdir_index.store_second, DIGEST256_LEN); return tor_memcmp(key, node->hsdir_index.store_second, DIGEST256_LEN);
} }
/* Helper function: Compare two node_t objects current hsdir_index. */ /** Helper function: Compare two node_t objects current hsdir_index. */
static int static int
compare_node_fetch_hsdir_index(const void **a, const void **b) compare_node_fetch_hsdir_index(const void **a, const void **b)
{ {
@ -149,7 +149,7 @@ compare_node_fetch_hsdir_index(const void **a, const void **b)
DIGEST256_LEN); DIGEST256_LEN);
} }
/* Helper function: Compare two node_t objects next hsdir_index. */ /** Helper function: Compare two node_t objects next hsdir_index. */
static int static int
compare_node_store_first_hsdir_index(const void **a, const void **b) compare_node_store_first_hsdir_index(const void **a, const void **b)
{ {
@ -160,7 +160,7 @@ compare_node_store_first_hsdir_index(const void **a, const void **b)
DIGEST256_LEN); DIGEST256_LEN);
} }
/* Helper function: Compare two node_t objects next hsdir_index. */ /** Helper function: Compare two node_t objects next hsdir_index. */
static int static int
compare_node_store_second_hsdir_index(const void **a, const void **b) compare_node_store_second_hsdir_index(const void **a, const void **b)
{ {
@ -171,7 +171,7 @@ compare_node_store_second_hsdir_index(const void **a, const void **b)
DIGEST256_LEN); DIGEST256_LEN);
} }
/* Allocate and return a string containing the path to filename in directory. /** Allocate and return a string containing the path to filename in directory.
* This function will never return NULL. The caller must free this path. */ * This function will never return NULL. The caller must free this path. */
char * char *
hs_path_from_filename(const char *directory, const char *filename) hs_path_from_filename(const char *directory, const char *filename)
@ -185,8 +185,9 @@ hs_path_from_filename(const char *directory, const char *filename)
return file_path; return file_path;
} }
/* Make sure that the directory for <b>service</b> is private, using the config /** Make sure that the directory for <b>service</b> is private, using the
* <b>username</b>. * config <b>username</b>.
*
* If <b>create</b> is true: * If <b>create</b> is true:
* - if the directory exists, change permissions if needed, * - if the directory exists, change permissions if needed,
* - if the directory does not exist, create it with the correct permissions. * - if the directory does not exist, create it with the correct permissions.
@ -313,9 +314,9 @@ hs_get_previous_time_period_num(time_t now)
return hs_get_time_period_num(now) - 1; return hs_get_time_period_num(now) - 1;
} }
/* Return the start time of the upcoming time period based on <b>now</b>. If /** Return the start time of the upcoming time period based on <b>now</b>. If
<b>now</b> is not set, we try to get the time ourselves from a live * <b>now</b> is not set, we try to get the time ourselves from a live
consensus. */ * consensus. */
time_t time_t
hs_get_start_time_of_next_time_period(time_t now) hs_get_start_time_of_next_time_period(time_t now)
{ {
@ -330,7 +331,7 @@ hs_get_start_time_of_next_time_period(time_t now)
return (time_t)(start_of_next_tp_in_mins * 60 + time_period_rotation_offset); return (time_t)(start_of_next_tp_in_mins * 60 + time_period_rotation_offset);
} }
/* Create a new rend_data_t for a specific given <b>version</b>. /** Create a new rend_data_t for a specific given <b>version</b>.
* Return a pointer to the newly allocated data structure. */ * Return a pointer to the newly allocated data structure. */
static rend_data_t * static rend_data_t *
rend_data_alloc(uint32_t version) rend_data_alloc(uint32_t version)
@ -379,7 +380,7 @@ rend_data_free_(rend_data_t *data)
} }
} }
/* Allocate and return a deep copy of <b>data</b>. */ /** Allocate and return a deep copy of <b>data</b>. */
rend_data_t * rend_data_t *
rend_data_dup(const rend_data_t *data) rend_data_dup(const rend_data_t *data)
{ {
@ -409,7 +410,7 @@ rend_data_dup(const rend_data_t *data)
return data_dup; return data_dup;
} }
/* Compute the descriptor ID for each HS descriptor replica and save them. A /** Compute the descriptor ID for each HS descriptor replica and save them. A
* valid onion address must be present in the <b>rend_data</b>. * valid onion address must be present in the <b>rend_data</b>.
* *
* Return 0 on success else -1. */ * Return 0 on success else -1. */
@ -447,7 +448,7 @@ compute_desc_id(rend_data_t *rend_data)
return ret; return ret;
} }
/* Allocate and initialize a rend_data_t object for a service using the /** Allocate and initialize a rend_data_t object for a service using the
* provided arguments. All arguments are optional (can be NULL), except from * provided arguments. All arguments are optional (can be NULL), except from
* <b>onion_address</b> which MUST be set. The <b>pk_digest</b> is the hash of * <b>onion_address</b> which MUST be set. The <b>pk_digest</b> is the hash of
* the service private key. The <b>cookie</b> is the rendezvous cookie and * the service private key. The <b>cookie</b> is the rendezvous cookie and
@ -479,7 +480,7 @@ rend_data_service_create(const char *onion_address, const char *pk_digest,
return rend_data; return rend_data;
} }
/* Allocate and initialize a rend_data_t object for a client request using the /** Allocate and initialize a rend_data_t object for a client request using the
* given arguments. Either an onion address or a descriptor ID is needed. Both * given arguments. Either an onion address or a descriptor ID is needed. Both
* can be given but in this case only the onion address will be used to make * can be given but in this case only the onion address will be used to make
* the descriptor fetch. The <b>cookie</b> is the rendezvous cookie and * the descriptor fetch. The <b>cookie</b> is the rendezvous cookie and
@ -520,7 +521,7 @@ rend_data_client_create(const char *onion_address, const char *desc_id,
return NULL; return NULL;
} }
/* Return the onion address from the rend data. Depending on the version, /** Return the onion address from the rend data. Depending on the version,
* the size of the address can vary but it's always NUL terminated. */ * the size of the address can vary but it's always NUL terminated. */
const char * const char *
rend_data_get_address(const rend_data_t *rend_data) rend_data_get_address(const rend_data_t *rend_data)
@ -536,7 +537,7 @@ rend_data_get_address(const rend_data_t *rend_data)
} }
} }
/* Return the descriptor ID for a specific replica number from the rend /** Return the descriptor ID for a specific replica number from the rend
* data. The returned data is a binary digest and depending on the version its * data. The returned data is a binary digest and depending on the version its
* size can vary. The size of the descriptor ID is put in <b>len_out</b> if * size can vary. The size of the descriptor ID is put in <b>len_out</b> if
* non NULL. */ * non NULL. */
@ -559,7 +560,7 @@ rend_data_get_desc_id(const rend_data_t *rend_data, uint8_t replica,
} }
} }
/* Return the public key digest using the given <b>rend_data</b>. The size of /** Return the public key digest using the given <b>rend_data</b>. The size of
* the digest is put in <b>len_out</b> (if set) which can differ depending on * the digest is put in <b>len_out</b> (if set) which can differ depending on
* the version. */ * the version. */
const uint8_t * const uint8_t *
@ -582,7 +583,7 @@ rend_data_get_pk_digest(const rend_data_t *rend_data, size_t *len_out)
} }
} }
/* Using the given time period number, compute the disaster shared random /** Using the given time period number, compute the disaster shared random
* value and put it in srv_out. It MUST be at least DIGEST256_LEN bytes. */ * value and put it in srv_out. It MUST be at least DIGEST256_LEN bytes. */
static void static void
compute_disaster_srv(uint64_t time_period_num, uint8_t *srv_out) compute_disaster_srv(uint64_t time_period_num, uint8_t *srv_out)
@ -670,7 +671,7 @@ get_second_cached_disaster_srv(void)
#endif /* defined(TOR_UNIT_TESTS) */ #endif /* defined(TOR_UNIT_TESTS) */
/* When creating a blinded key, we need a parameter which construction is as /** When creating a blinded key, we need a parameter which construction is as
* follow: H(pubkey | [secret] | ed25519-basepoint | nonce). * follow: H(pubkey | [secret] | ed25519-basepoint | nonce).
* *
* The nonce has a pre-defined format which uses the time period number * The nonce has a pre-defined format which uses the time period number
@ -751,7 +752,7 @@ build_hs_checksum(const ed25519_public_key_t *key, uint8_t version,
DIGEST_SHA3_256); DIGEST_SHA3_256);
} }
/* Using an ed25519 public key, checksum and version to build the binary /** Using an ed25519 public key, checksum and version to build the binary
* representation of a service address. Put in addr_out. Format is: * representation of a service address. Put in addr_out. Format is:
* addr_out = PUBKEY || CHECKSUM || VERSION * addr_out = PUBKEY || CHECKSUM || VERSION
* *
@ -774,7 +775,7 @@ build_hs_address(const ed25519_public_key_t *key, const uint8_t *checksum,
tor_assert(offset == HS_SERVICE_ADDR_LEN); tor_assert(offset == HS_SERVICE_ADDR_LEN);
} }
/* Helper for hs_parse_address(): Using a binary representation of a service /** Helper for hs_parse_address(): Using a binary representation of a service
* address, parse its content into the key_out, checksum_out and version_out. * address, parse its content into the key_out, checksum_out and version_out.
* Any out variable can be NULL in case the caller would want only one field. * Any out variable can be NULL in case the caller would want only one field.
* checksum_out MUST at least be 2 bytes long. address must be at least * checksum_out MUST at least be 2 bytes long. address must be at least
@ -806,7 +807,7 @@ hs_parse_address_impl(const char *address, ed25519_public_key_t *key_out,
tor_assert(offset == HS_SERVICE_ADDR_LEN); tor_assert(offset == HS_SERVICE_ADDR_LEN);
} }
/* Using the given identity public key and a blinded public key, compute the /** Using the given identity public key and a blinded public key, compute the
* subcredential and put it in subcred_out (must be of size DIGEST256_LEN). * subcredential and put it in subcred_out (must be of size DIGEST256_LEN).
* This can't fail. */ * This can't fail. */
void void
@ -846,7 +847,7 @@ hs_get_subcredential(const ed25519_public_key_t *identity_pk,
memwipe(credential, 0, sizeof(credential)); memwipe(credential, 0, sizeof(credential));
} }
/* From the given list of hidden service ports, find the ones that match the /** From the given list of hidden service ports, find the ones that match the
* given edge connection conn, pick one at random and use it to set the * given edge connection conn, pick one at random and use it to set the
* connection address. Return 0 on success or -1 if none. */ * connection address. Return 0 on success or -1 if none. */
int int
@ -903,7 +904,7 @@ hs_set_conn_addr_port(const smartlist_t *ports, edge_connection_t *conn)
return (chosen_port) ? 0 : -1; return (chosen_port) ? 0 : -1;
} }
/* Using a base32 representation of a service address, parse its content into /** Using a base32 representation of a service address, parse its content into
* the key_out, checksum_out and version_out. Any out variable can be NULL in * the key_out, checksum_out and version_out. Any out variable can be NULL in
* case the caller would want only one field. checksum_out MUST at least be 2 * case the caller would want only one field. checksum_out MUST at least be 2
* bytes long. * bytes long.
@ -943,7 +944,7 @@ hs_parse_address(const char *address, ed25519_public_key_t *key_out,
return -1; return -1;
} }
/* Validate a given onion address. The length, the base32 decoding, and /** Validate a given onion address. The length, the base32 decoding, and
* checksum are validated. Return 1 if valid else 0. */ * checksum are validated. Return 1 if valid else 0. */
int int
hs_address_is_valid(const char *address) hs_address_is_valid(const char *address)
@ -982,7 +983,7 @@ hs_address_is_valid(const char *address)
return 0; return 0;
} }
/* Build a service address using an ed25519 public key and a given version. /** Build a service address using an ed25519 public key and a given version.
* The returned address is base32 encoded and put in addr_out. The caller MUST * The returned address is base32 encoded and put in addr_out. The caller MUST
* make sure the addr_out is at least HS_SERVICE_ADDR_LEN_BASE32 + 1 long. * make sure the addr_out is at least HS_SERVICE_ADDR_LEN_BASE32 + 1 long.
* *
@ -1012,7 +1013,7 @@ hs_build_address(const ed25519_public_key_t *key, uint8_t version,
tor_assert(hs_address_is_valid(addr_out)); tor_assert(hs_address_is_valid(addr_out));
} }
/* From a given ed25519 public key pk and an optional secret, compute a /** From a given ed25519 public key pk and an optional secret, compute a
* blinded public key and put it in blinded_pk_out. This is only useful to * blinded public key and put it in blinded_pk_out. This is only useful to
* the client side because the client only has access to the identity public * the client side because the client only has access to the identity public
* key of the service. */ * key of the service. */
@ -1036,7 +1037,7 @@ hs_build_blinded_pubkey(const ed25519_public_key_t *pk,
memwipe(param, 0, sizeof(param)); memwipe(param, 0, sizeof(param));
} }
/* From a given ed25519 keypair kp and an optional secret, compute a blinded /** From a given ed25519 keypair kp and an optional secret, compute a blinded
* keypair for the current time period and put it in blinded_kp_out. This is * keypair for the current time period and put it in blinded_kp_out. This is
* only useful by the service side because the client doesn't have access to * only useful by the service side because the client doesn't have access to
* the identity secret key. */ * the identity secret key. */
@ -1062,7 +1063,7 @@ hs_build_blinded_keypair(const ed25519_keypair_t *kp,
memwipe(param, 0, sizeof(param)); memwipe(param, 0, sizeof(param));
} }
/* Return true if we are currently in the time segment between a new time /** Return true if we are currently in the time segment between a new time
* period and a new SRV (in the real network that happens between 12:00 and * period and a new SRV (in the real network that happens between 12:00 and
* 00:00 UTC). Here is a diagram showing exactly when this returns true: * 00:00 UTC). Here is a diagram showing exactly when this returns true:
* *
@ -1102,7 +1103,7 @@ hs_in_period_between_tp_and_srv,(const networkstatus_t *consensus, time_t now))
return 1; return 1;
} }
/* Return 1 if any virtual port in ports needs a circuit with good uptime. /** Return 1 if any virtual port in ports needs a circuit with good uptime.
* Else return 0. */ * Else return 0. */
int int
hs_service_requires_uptime_circ(const smartlist_t *ports) hs_service_requires_uptime_circ(const smartlist_t *ports)
@ -1118,7 +1119,7 @@ hs_service_requires_uptime_circ(const smartlist_t *ports)
return 0; return 0;
} }
/* Build hs_index which is used to find the responsible hsdirs. This index /** Build hs_index which is used to find the responsible hsdirs. This index
* value is used to select the responsible HSDir where their hsdir_index is * value is used to select the responsible HSDir where their hsdir_index is
* closest to this value. * closest to this value.
* SHA3-256("store-at-idx" | blinded_public_key | * SHA3-256("store-at-idx" | blinded_public_key |
@ -1160,7 +1161,7 @@ hs_build_hs_index(uint64_t replica, const ed25519_public_key_t *blinded_pk,
crypto_digest_free(digest); crypto_digest_free(digest);
} }
/* Build hsdir_index which is used to find the responsible hsdirs. This is the /** Build hsdir_index which is used to find the responsible hsdirs. This is the
* index value that is compare to the hs_index when selecting an HSDir. * index value that is compare to the hs_index when selecting an HSDir.
* SHA3-256("node-idx" | node_identity | * SHA3-256("node-idx" | node_identity |
* shared_random_value | INT_8(period_length) | INT_8(period_num) ) * shared_random_value | INT_8(period_length) | INT_8(period_num) )
@ -1201,7 +1202,7 @@ hs_build_hsdir_index(const ed25519_public_key_t *identity_pk,
crypto_digest_free(digest); crypto_digest_free(digest);
} }
/* Return a newly allocated buffer containing the current shared random value /** Return a newly allocated buffer containing the current shared random value
* or if not present, a disaster value is computed using the given time period * or if not present, a disaster value is computed using the given time period
* number. If a consensus is provided in <b>ns</b>, use it to get the SRV * number. If a consensus is provided in <b>ns</b>, use it to get the SRV
* value. This function can't fail. */ * value. This function can't fail. */
@ -1220,7 +1221,7 @@ hs_get_current_srv(uint64_t time_period_num, const networkstatus_t *ns)
return sr_value; return sr_value;
} }
/* Return a newly allocated buffer containing the previous shared random /** Return a newly allocated buffer containing the previous shared random
* value or if not present, a disaster value is computed using the given time * value or if not present, a disaster value is computed using the given time
* period number. This function can't fail. */ * period number. This function can't fail. */
uint8_t * uint8_t *
@ -1238,7 +1239,7 @@ hs_get_previous_srv(uint64_t time_period_num, const networkstatus_t *ns)
return sr_value; return sr_value;
} }
/* Return the number of replicas defined by a consensus parameter or the /** Return the number of replicas defined by a consensus parameter or the
* default value. */ * default value. */
int32_t int32_t
hs_get_hsdir_n_replicas(void) hs_get_hsdir_n_replicas(void)
@ -1248,7 +1249,7 @@ hs_get_hsdir_n_replicas(void)
HS_DEFAULT_HSDIR_N_REPLICAS, 1, 16); HS_DEFAULT_HSDIR_N_REPLICAS, 1, 16);
} }
/* Return the spread fetch value defined by a consensus parameter or the /** Return the spread fetch value defined by a consensus parameter or the
* default value. */ * default value. */
int32_t int32_t
hs_get_hsdir_spread_fetch(void) hs_get_hsdir_spread_fetch(void)
@ -1258,7 +1259,7 @@ hs_get_hsdir_spread_fetch(void)
HS_DEFAULT_HSDIR_SPREAD_FETCH, 1, 128); HS_DEFAULT_HSDIR_SPREAD_FETCH, 1, 128);
} }
/* Return the spread store value defined by a consensus parameter or the /** Return the spread store value defined by a consensus parameter or the
* default value. */ * default value. */
int32_t int32_t
hs_get_hsdir_spread_store(void) hs_get_hsdir_spread_store(void)
@ -1301,7 +1302,7 @@ node_has_hsdir_index(const node_t *node)
return 1; return 1;
} }
/* For a given blinded key and time period number, get the responsible HSDir /** For a given blinded key and time period number, get the responsible HSDir
* and put their routerstatus_t object in the responsible_dirs list. If * and put their routerstatus_t object in the responsible_dirs list. If
* 'use_second_hsdir_index' is true, use the second hsdir_index of the node_t * 'use_second_hsdir_index' is true, use the second hsdir_index of the node_t
* is used. If 'for_fetching' is true, the spread fetch consensus parameter is * is used. If 'for_fetching' is true, the spread fetch consensus parameter is
@ -1674,7 +1675,7 @@ hs_pick_hsdir(smartlist_t *responsible_dirs, const char *req_key_str,
return hs_dir; return hs_dir;
} }
/* Given a list of link specifiers lspecs, a curve 25519 onion_key, and /** Given a list of link specifiers lspecs, a curve 25519 onion_key, and
* a direct connection boolean direct_conn (true for single onion services), * a direct connection boolean direct_conn (true for single onion services),
* return a newly allocated extend_info_t object. * return a newly allocated extend_info_t object.
* *
@ -1787,7 +1788,7 @@ hs_get_extend_info_from_lspecs(const smartlist_t *lspecs,
/***********************************************************************/ /***********************************************************************/
/* Initialize the entire HS subsytem. This is called in tor_init() before any /** Initialize the entire HS subsytem. This is called in tor_init() before any
* torrc options are loaded. Only for >= v3. */ * torrc options are loaded. Only for >= v3. */
void void
hs_init(void) hs_init(void)
@ -1797,7 +1798,7 @@ hs_init(void)
hs_cache_init(); hs_cache_init();
} }
/* Release and cleanup all memory of the HS subsystem (all version). This is /** Release and cleanup all memory of the HS subsystem (all version). This is
* called by tor_free_all(). */ * called by tor_free_all(). */
void void
hs_free_all(void) hs_free_all(void)
@ -1808,7 +1809,7 @@ hs_free_all(void)
hs_client_free_all(); hs_client_free_all();
} }
/* For the given origin circuit circ, decrement the number of rendezvous /** For the given origin circuit circ, decrement the number of rendezvous
* stream counter. This handles every hidden service version. */ * stream counter. This handles every hidden service version. */
void void
hs_dec_rdv_stream_counter(origin_circuit_t *circ) hs_dec_rdv_stream_counter(origin_circuit_t *circ)
@ -1825,7 +1826,7 @@ hs_dec_rdv_stream_counter(origin_circuit_t *circ)
} }
} }
/* For the given origin circuit circ, increment the number of rendezvous /** For the given origin circuit circ, increment the number of rendezvous
* stream counter. This handles every hidden service version. */ * stream counter. This handles every hidden service version. */
void void
hs_inc_rdv_stream_counter(origin_circuit_t *circ) hs_inc_rdv_stream_counter(origin_circuit_t *circ)
@ -1842,7 +1843,7 @@ hs_inc_rdv_stream_counter(origin_circuit_t *circ)
} }
} }
/* Return a newly allocated link specifier object that is a copy of dst. */ /** Return a newly allocated link specifier object that is a copy of dst. */
link_specifier_t * link_specifier_t *
link_specifier_dup(const link_specifier_t *src) link_specifier_dup(const link_specifier_t *src)
{ {

70
src/feature/hs/hs_common.h
View File

@ -19,13 +19,14 @@ struct ed25519_keypair_t;
/* Trunnel */ /* Trunnel */
#include "trunnel/ed25519_cert.h" #include "trunnel/ed25519_cert.h"
/* Protocol version 2. Use this instead of hardcoding "2" in the code base, /** Protocol version 2. Use this instead of hardcoding "2" in the code base,
* this adds a clearer semantic to the value when used. */ * this adds a clearer semantic to the value when used. */
#define HS_VERSION_TWO 2 #define HS_VERSION_TWO 2
/* Version 3 of the protocol (prop224). */ /** Version 3 of the protocol (prop224). */
#define HS_VERSION_THREE 3 #define HS_VERSION_THREE 3
/* Earliest and latest version we support. */ /** Earliest version we support. */
#define HS_VERSION_MIN HS_VERSION_TWO #define HS_VERSION_MIN HS_VERSION_TWO
/** Latest version we support. */
#define HS_VERSION_MAX HS_VERSION_THREE #define HS_VERSION_MAX HS_VERSION_THREE
/** Try to maintain this many intro points per service by default. */ /** Try to maintain this many intro points per service by default. */
@ -48,94 +49,95 @@ struct ed25519_keypair_t;
* rendezvous point before giving up? */ * rendezvous point before giving up? */
#define MAX_REND_TIMEOUT 30 #define MAX_REND_TIMEOUT 30
/* String prefix for the signature of ESTABLISH_INTRO */ /** String prefix for the signature of ESTABLISH_INTRO */
#define ESTABLISH_INTRO_SIG_PREFIX "Tor establish-intro cell v1" #define ESTABLISH_INTRO_SIG_PREFIX "Tor establish-intro cell v1"
/* The default HS time period length */ /** The default HS time period length */
#define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */ #define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */
/* The minimum time period length as seen in prop224 section [TIME-PERIODS] */ /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */
#define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */ #define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */
/* The minimum time period length as seen in prop224 section [TIME-PERIODS] */ /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */
#define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */ #define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */
/* Prefix of the onion address checksum. */ /** Prefix of the onion address checksum. */
#define HS_SERVICE_ADDR_CHECKSUM_PREFIX ".onion checksum" #define HS_SERVICE_ADDR_CHECKSUM_PREFIX ".onion checksum"
/* Length of the checksum prefix minus the NUL terminated byte. */ /** Length of the checksum prefix minus the NUL terminated byte. */
#define HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN \ #define HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN \
(sizeof(HS_SERVICE_ADDR_CHECKSUM_PREFIX) - 1) (sizeof(HS_SERVICE_ADDR_CHECKSUM_PREFIX) - 1)
/* Length of the resulting checksum of the address. The construction of this /** Length of the resulting checksum of the address. The construction of this
* checksum looks like: * checksum looks like:
* CHECKSUM = ".onion checksum" || PUBKEY || VERSION * CHECKSUM = ".onion checksum" || PUBKEY || VERSION
* where VERSION is 1 byte. This is pre-hashing. */ * where VERSION is 1 byte. This is pre-hashing. */
#define HS_SERVICE_ADDR_CHECKSUM_INPUT_LEN \ #define HS_SERVICE_ADDR_CHECKSUM_INPUT_LEN \
(HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN + ED25519_PUBKEY_LEN + sizeof(uint8_t)) (HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN + ED25519_PUBKEY_LEN + sizeof(uint8_t))
/* The amount of bytes we use from the address checksum. */ /** The amount of bytes we use from the address checksum. */
#define HS_SERVICE_ADDR_CHECKSUM_LEN_USED 2 #define HS_SERVICE_ADDR_CHECKSUM_LEN_USED 2
/* Length of the binary encoded service address which is of course before the /** Length of the binary encoded service address which is of course before the
* base32 encoding. Construction is: * base32 encoding. Construction is:
* PUBKEY || CHECKSUM || VERSION * PUBKEY || CHECKSUM || VERSION
* with 1 byte VERSION and 2 bytes CHECKSUM. The following is 35 bytes. */ * with 1 byte VERSION and 2 bytes CHECKSUM. The following is 35 bytes. */
#define HS_SERVICE_ADDR_LEN \ #define HS_SERVICE_ADDR_LEN \
(ED25519_PUBKEY_LEN + HS_SERVICE_ADDR_CHECKSUM_LEN_USED + sizeof(uint8_t)) (ED25519_PUBKEY_LEN + HS_SERVICE_ADDR_CHECKSUM_LEN_USED + sizeof(uint8_t))
/* Length of 'y' portion of 'y.onion' URL. This is base32 encoded and the /** Length of 'y' portion of 'y.onion' URL. This is base32 encoded and the
* length ends up to 56 bytes (not counting the terminated NUL byte.) */ * length ends up to 56 bytes (not counting the terminated NUL byte.) */
#define HS_SERVICE_ADDR_LEN_BASE32 \ #define HS_SERVICE_ADDR_LEN_BASE32 \
(CEIL_DIV(HS_SERVICE_ADDR_LEN * 8, 5)) (CEIL_DIV(HS_SERVICE_ADDR_LEN * 8, 5))
/* The default HS time period length */ /** The default HS time period length */
#define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */ #define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */
/* The minimum time period length as seen in prop224 section [TIME-PERIODS] */ /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */
#define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */ #define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */
/* The minimum time period length as seen in prop224 section [TIME-PERIODS] */ /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */
#define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */ #define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */
/* The time period rotation offset as seen in prop224 section [TIME-PERIODS] */ /** The time period rotation offset as seen in prop224 section
* [TIME-PERIODS] */
#define HS_TIME_PERIOD_ROTATION_OFFSET (12 * 60) /* minutes */ #define HS_TIME_PERIOD_ROTATION_OFFSET (12 * 60) /* minutes */
/* Keyblinding parameter construction is as follow: /** Keyblinding parameter construction is as follow:
* "key-blind" || INT_8(period_num) || INT_8(start_period_sec) */ * "key-blind" || INT_8(period_num) || INT_8(start_period_sec) */
#define HS_KEYBLIND_NONCE_PREFIX "key-blind" #define HS_KEYBLIND_NONCE_PREFIX "key-blind"
#define HS_KEYBLIND_NONCE_PREFIX_LEN (sizeof(HS_KEYBLIND_NONCE_PREFIX) - 1) #define HS_KEYBLIND_NONCE_PREFIX_LEN (sizeof(HS_KEYBLIND_NONCE_PREFIX) - 1)
#define HS_KEYBLIND_NONCE_LEN \ #define HS_KEYBLIND_NONCE_LEN \
(HS_KEYBLIND_NONCE_PREFIX_LEN + sizeof(uint64_t) + sizeof(uint64_t)) (HS_KEYBLIND_NONCE_PREFIX_LEN + sizeof(uint64_t) + sizeof(uint64_t))
/* Credential and subcredential prefix value. */ /** Credential and subcredential prefix value. */
#define HS_CREDENTIAL_PREFIX "credential" #define HS_CREDENTIAL_PREFIX "credential"
#define HS_CREDENTIAL_PREFIX_LEN (sizeof(HS_CREDENTIAL_PREFIX) - 1) #define HS_CREDENTIAL_PREFIX_LEN (sizeof(HS_CREDENTIAL_PREFIX) - 1)
#define HS_SUBCREDENTIAL_PREFIX "subcredential" #define HS_SUBCREDENTIAL_PREFIX "subcredential"
#define HS_SUBCREDENTIAL_PREFIX_LEN (sizeof(HS_SUBCREDENTIAL_PREFIX) - 1) #define HS_SUBCREDENTIAL_PREFIX_LEN (sizeof(HS_SUBCREDENTIAL_PREFIX) - 1)
/* Node hidden service stored at index prefix value. */ /** Node hidden service stored at index prefix value. */
#define HS_INDEX_PREFIX "store-at-idx" #define HS_INDEX_PREFIX "store-at-idx"
#define HS_INDEX_PREFIX_LEN (sizeof(HS_INDEX_PREFIX) - 1) #define HS_INDEX_PREFIX_LEN (sizeof(HS_INDEX_PREFIX) - 1)
/* Node hidden service directory index prefix value. */ /** Node hidden service directory index prefix value. */
#define HSDIR_INDEX_PREFIX "node-idx" #define HSDIR_INDEX_PREFIX "node-idx"
#define HSDIR_INDEX_PREFIX_LEN (sizeof(HSDIR_INDEX_PREFIX) - 1) #define HSDIR_INDEX_PREFIX_LEN (sizeof(HSDIR_INDEX_PREFIX) - 1)
/* Prefix of the shared random value disaster mode. */ /** Prefix of the shared random value disaster mode. */
#define HS_SRV_DISASTER_PREFIX "shared-random-disaster" #define HS_SRV_DISASTER_PREFIX "shared-random-disaster"
#define HS_SRV_DISASTER_PREFIX_LEN (sizeof(HS_SRV_DISASTER_PREFIX) - 1) #define HS_SRV_DISASTER_PREFIX_LEN (sizeof(HS_SRV_DISASTER_PREFIX) - 1)
/* Default value of number of hsdir replicas (hsdir_n_replicas). */ /** Default value of number of hsdir replicas (hsdir_n_replicas). */
#define HS_DEFAULT_HSDIR_N_REPLICAS 2 #define HS_DEFAULT_HSDIR_N_REPLICAS 2
/* Default value of hsdir spread store (hsdir_spread_store). */ /** Default value of hsdir spread store (hsdir_spread_store). */
#define HS_DEFAULT_HSDIR_SPREAD_STORE 4 #define HS_DEFAULT_HSDIR_SPREAD_STORE 4
/* Default value of hsdir spread fetch (hsdir_spread_fetch). */ /** Default value of hsdir spread fetch (hsdir_spread_fetch). */
#define HS_DEFAULT_HSDIR_SPREAD_FETCH 3 #define HS_DEFAULT_HSDIR_SPREAD_FETCH 3
/* The size of a legacy RENDEZVOUS1 cell which adds up to 168 bytes. It is /** The size of a legacy RENDEZVOUS1 cell which adds up to 168 bytes. It is
* bigger than the 84 bytes needed for version 3 so we need to pad up to that * bigger than the 84 bytes needed for version 3 so we need to pad up to that
* length so it is indistinguishable between versions. */ * length so it is indistinguishable between versions. */
#define HS_LEGACY_RENDEZVOUS_CELL_SIZE \ #define HS_LEGACY_RENDEZVOUS_CELL_SIZE \
(REND_COOKIE_LEN + DH1024_KEY_LEN + DIGEST_LEN) (REND_COOKIE_LEN + DH1024_KEY_LEN + DIGEST_LEN)
/* Type of authentication key used by an introduction point. */ /** Type of authentication key used by an introduction point. */
typedef enum { typedef enum {
HS_AUTH_KEY_TYPE_LEGACY = 1, HS_AUTH_KEY_TYPE_LEGACY = 1,
HS_AUTH_KEY_TYPE_ED25519 = 2, HS_AUTH_KEY_TYPE_ED25519 = 2,
} hs_auth_key_type_t; } hs_auth_key_type_t;
/* Return value when adding an ephemeral service through the ADD_ONION /** Return value when adding an ephemeral service through the ADD_ONION
* control port command. Both v2 and v3 share these. */ * control port command. Both v2 and v3 share these. */
typedef enum { typedef enum {
RSAE_BADAUTH = -5, /**< Invalid auth_type/auth_clients */ RSAE_BADAUTH = -5, /**< Invalid auth_type/auth_clients */
@ -146,18 +148,18 @@ typedef enum {
RSAE_OKAY = 0 /**< Service added as expected */ RSAE_OKAY = 0 /**< Service added as expected */
} hs_service_add_ephemeral_status_t; } hs_service_add_ephemeral_status_t;
/* Represents the mapping from a virtual port of a rendezvous service to a /** Represents the mapping from a virtual port of a rendezvous service to a
* real port on some IP. */ * real port on some IP. */
typedef struct rend_service_port_config_t { typedef struct rend_service_port_config_t {
/* The incoming HS virtual port we're mapping */ /** The incoming HS virtual port we're mapping */
uint16_t virtual_port; uint16_t virtual_port;
/* Is this an AF_UNIX port? */ /** Is this an AF_UNIX port? */
unsigned int is_unix_addr:1; unsigned int is_unix_addr:1;
/* The outgoing TCP port to use, if !is_unix_addr */ /** The outgoing TCP port to use, if !is_unix_addr */
uint16_t real_port; uint16_t real_port;
/* The outgoing IPv4 or IPv6 address to use, if !is_unix_addr */ /** The outgoing IPv4 or IPv6 address to use, if !is_unix_addr */
tor_addr_t real_addr; tor_addr_t real_addr;
/* The socket path to connect to, if is_unix_addr */ /** The socket path to connect to, if is_unix_addr */
char unix_addr[FLEXIBLE_ARRAY_MEMBER]; char unix_addr[FLEXIBLE_ARRAY_MEMBER];
} rend_service_port_config_t; } rend_service_port_config_t;