hs_common.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297
  1. /* Copyright (c) 2016-2017, The Tor Project, Inc. */
  2. /* See LICENSE for licensing information */
  3. /**
  4. * \file hs_common.h
  5. * \brief Header file containing common data for the whole HS subsytem.
  6. **/
  7. #ifndef TOR_HS_COMMON_H
  8. #define TOR_HS_COMMON_H
  9. #include "or.h"
  10. /* Trunnel */
  11. #include "ed25519_cert.h"
  12. /* Protocol version 2. Use this instead of hardcoding "2" in the code base,
  13. * this adds a clearer semantic to the value when used. */
  14. #define HS_VERSION_TWO 2
  15. /* Version 3 of the protocol (prop224). */
  16. #define HS_VERSION_THREE 3
  17. /* Earliest and latest version we support. */
  18. #define HS_VERSION_MIN HS_VERSION_TWO
  19. #define HS_VERSION_MAX HS_VERSION_THREE
  20. /** Try to maintain this many intro points per service by default. */
  21. #define NUM_INTRO_POINTS_DEFAULT 3
  22. /** Maximum number of intro points per generic and version 2 service. */
  23. #define NUM_INTRO_POINTS_MAX 10
  24. /** Number of extra intro points we launch if our set of intro nodes is empty.
  25. * See proposal 155, section 4. */
  26. #define NUM_INTRO_POINTS_EXTRA 2
  27. /** If we can't build our intro circuits, don't retry for this long. */
  28. #define INTRO_CIRC_RETRY_PERIOD (60*5)
  29. /** Don't try to build more than this many circuits before giving up for a
  30. * while.*/
  31. #define MAX_INTRO_CIRCS_PER_PERIOD 10
  32. /** How many times will a hidden service operator attempt to connect to a
  33. * requested rendezvous point before giving up? */
  34. #define MAX_REND_FAILURES 1
  35. /** How many seconds should we spend trying to connect to a requested
  36. * rendezvous point before giving up? */
  37. #define MAX_REND_TIMEOUT 30
  38. /* String prefix for the signature of ESTABLISH_INTRO */
  39. #define ESTABLISH_INTRO_SIG_PREFIX "Tor establish-intro cell v1"
  40. /* The default HS time period length */
  41. #define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */
  42. /* The minimum time period length as seen in prop224 section [TIME-PERIODS] */
  43. #define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */
  44. /* The minimum time period length as seen in prop224 section [TIME-PERIODS] */
  45. #define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */
  46. /* Prefix of the onion address checksum. */
  47. #define HS_SERVICE_ADDR_CHECKSUM_PREFIX ".onion checksum"
  48. /* Length of the checksum prefix minus the NUL terminated byte. */
  49. #define HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN \
  50. (sizeof(HS_SERVICE_ADDR_CHECKSUM_PREFIX) - 1)
  51. /* Length of the resulting checksum of the address. The construction of this
  52. * checksum looks like:
  53. * CHECKSUM = ".onion checksum" || PUBKEY || VERSION
  54. * where VERSION is 1 byte. This is pre-hashing. */
  55. #define HS_SERVICE_ADDR_CHECKSUM_INPUT_LEN \
  56. (HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN + ED25519_PUBKEY_LEN + sizeof(uint8_t))
  57. /* The amount of bytes we use from the address checksum. */
  58. #define HS_SERVICE_ADDR_CHECKSUM_LEN_USED 2
  59. /* Length of the binary encoded service address which is of course before the
  60. * base32 encoding. Construction is:
  61. * PUBKEY || CHECKSUM || VERSION
  62. * with 1 byte VERSION and 2 bytes CHECKSUM. The following is 35 bytes. */
  63. #define HS_SERVICE_ADDR_LEN \
  64. (ED25519_PUBKEY_LEN + HS_SERVICE_ADDR_CHECKSUM_LEN_USED + sizeof(uint8_t))
  65. /* Length of 'y' portion of 'y.onion' URL. This is base32 encoded and the
  66. * length ends up to 56 bytes (not counting the terminated NUL byte.) */
  67. #define HS_SERVICE_ADDR_LEN_BASE32 \
  68. (CEIL_DIV(HS_SERVICE_ADDR_LEN * 8, 5))
  69. /* The default HS time period length */
  70. #define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */
  71. /* The minimum time period length as seen in prop224 section [TIME-PERIODS] */
  72. #define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */
  73. /* The minimum time period length as seen in prop224 section [TIME-PERIODS] */
  74. #define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */
  75. /* The time period rotation offset as seen in prop224 section [TIME-PERIODS] */
  76. #define HS_TIME_PERIOD_ROTATION_OFFSET (12 * 60) /* minutes */
  77. /* Keyblinding parameter construction is as follow:
  78. * "key-blind" || INT_8(period_num) || INT_8(start_period_sec) */
  79. #define HS_KEYBLIND_NONCE_PREFIX "key-blind"
  80. #define HS_KEYBLIND_NONCE_PREFIX_LEN (sizeof(HS_KEYBLIND_NONCE_PREFIX) - 1)
  81. #define HS_KEYBLIND_NONCE_LEN \
  82. (HS_KEYBLIND_NONCE_PREFIX_LEN + sizeof(uint64_t) + sizeof(uint64_t))
  83. /* Credential and subcredential prefix value. */
  84. #define HS_CREDENTIAL_PREFIX "credential"
  85. #define HS_CREDENTIAL_PREFIX_LEN (sizeof(HS_CREDENTIAL_PREFIX) - 1)
  86. #define HS_SUBCREDENTIAL_PREFIX "subcredential"
  87. #define HS_SUBCREDENTIAL_PREFIX_LEN (sizeof(HS_SUBCREDENTIAL_PREFIX) - 1)
  88. /* Node hidden service stored at index prefix value. */
  89. #define HS_INDEX_PREFIX "store-at-idx"
  90. #define HS_INDEX_PREFIX_LEN (sizeof(HS_INDEX_PREFIX) - 1)
  91. /* Node hidden service directory index prefix value. */
  92. #define HSDIR_INDEX_PREFIX "node-idx"
  93. #define HSDIR_INDEX_PREFIX_LEN (sizeof(HSDIR_INDEX_PREFIX) - 1)
  94. /* Prefix of the shared random value disaster mode. */
  95. #define HS_SRV_DISASTER_PREFIX "shared-random-disaster"
  96. #define HS_SRV_DISASTER_PREFIX_LEN (sizeof(HS_SRV_DISASTER_PREFIX) - 1)
  97. /* Default value of number of hsdir replicas (hsdir_n_replicas). */
  98. #define HS_DEFAULT_HSDIR_N_REPLICAS 2
  99. /* Default value of hsdir spread store (hsdir_spread_store). */
  100. #define HS_DEFAULT_HSDIR_SPREAD_STORE 4
  101. /* Default value of hsdir spread fetch (hsdir_spread_fetch). */
  102. #define HS_DEFAULT_HSDIR_SPREAD_FETCH 3
  103. /* The size of a legacy RENDEZVOUS1 cell which adds up to 168 bytes. It is
  104. * bigger than the 84 bytes needed for version 3 so we need to pad up to that
  105. * length so it is indistinguishable between versions. */
  106. #define HS_LEGACY_RENDEZVOUS_CELL_SIZE \
  107. (REND_COOKIE_LEN + DH_KEY_LEN + DIGEST_LEN)
  108. /* Type of authentication key used by an introduction point. */
  109. typedef enum {
  110. HS_AUTH_KEY_TYPE_LEGACY = 1,
  111. HS_AUTH_KEY_TYPE_ED25519 = 2,
  112. } hs_auth_key_type_t;
  113. /* Return value when adding an ephemeral service through the ADD_ONION
  114. * control port command. Both v2 and v3 share these. */
  115. typedef enum {
  116. RSAE_BADAUTH = -5, /**< Invalid auth_type/auth_clients */
  117. RSAE_BADVIRTPORT = -4, /**< Invalid VIRTPORT/TARGET(s) */
  118. RSAE_ADDREXISTS = -3, /**< Onion address collision */
  119. RSAE_BADPRIVKEY = -2, /**< Invalid public key */
  120. RSAE_INTERNAL = -1, /**< Internal error */
  121. RSAE_OKAY = 0 /**< Service added as expected */
  122. } hs_service_add_ephemeral_status_t;
  123. /* Represents the mapping from a virtual port of a rendezvous service to a
  124. * real port on some IP. */
  125. typedef struct rend_service_port_config_t {
  126. /* The incoming HS virtual port we're mapping */
  127. uint16_t virtual_port;
  128. /* Is this an AF_UNIX port? */
  129. unsigned int is_unix_addr:1;
  130. /* The outgoing TCP port to use, if !is_unix_addr */
  131. uint16_t real_port;
  132. /* The outgoing IPv4 or IPv6 address to use, if !is_unix_addr */
  133. tor_addr_t real_addr;
  134. /* The socket path to connect to, if is_unix_addr */
  135. char unix_addr[FLEXIBLE_ARRAY_MEMBER];
  136. } rend_service_port_config_t;
  137. /* Hidden service directory index used in a node_t which is set once we set
  138. * the consensus. */
  139. typedef struct hsdir_index_t {
  140. /* HSDir index to use when fetching a descriptor. */
  141. uint8_t fetch[DIGEST256_LEN];
  142. /* HSDir index used by services to store their first and second
  143. * descriptor. The first descriptor is chronologically older than the second
  144. * one and uses older TP and SRV values. */
  145. uint8_t store_first[DIGEST256_LEN];
  146. uint8_t store_second[DIGEST256_LEN];
  147. } hsdir_index_t;
  148. void hs_init(void);
  149. void hs_free_all(void);
  150. void hs_cleanup_circ(circuit_t *circ);
  151. int hs_check_service_private_dir(const char *username, const char *path,
  152. unsigned int dir_group_readable,
  153. unsigned int create);
  154. int hs_get_service_max_rend_failures(void);
  155. char *hs_path_from_filename(const char *directory, const char *filename);
  156. void hs_build_address(const ed25519_public_key_t *key, uint8_t version,
  157. char *addr_out);
  158. int hs_address_is_valid(const char *address);
  159. int hs_parse_address(const char *address, ed25519_public_key_t *key_out,
  160. uint8_t *checksum_out, uint8_t *version_out);
  161. void hs_build_blinded_pubkey(const ed25519_public_key_t *pubkey,
  162. const uint8_t *secret, size_t secret_len,
  163. uint64_t time_period_num,
  164. ed25519_public_key_t *pubkey_out);
  165. void hs_build_blinded_keypair(const ed25519_keypair_t *kp,
  166. const uint8_t *secret, size_t secret_len,
  167. uint64_t time_period_num,
  168. ed25519_keypair_t *kp_out);
  169. int hs_service_requires_uptime_circ(const smartlist_t *ports);
  170. void rend_data_free_(rend_data_t *data);
  171. #define rend_data_free(data) \
  172. FREE_AND_NULL(rend_data_t, rend_data_free_, (data))
  173. rend_data_t *rend_data_dup(const rend_data_t *data);
  174. rend_data_t *rend_data_client_create(const char *onion_address,
  175. const char *desc_id,
  176. const char *cookie,
  177. rend_auth_type_t auth_type);
  178. rend_data_t *rend_data_service_create(const char *onion_address,
  179. const char *pk_digest,
  180. const uint8_t *cookie,
  181. rend_auth_type_t auth_type);
  182. const char *rend_data_get_address(const rend_data_t *rend_data);
  183. const char *rend_data_get_desc_id(const rend_data_t *rend_data,
  184. uint8_t replica, size_t *len_out);
  185. const uint8_t *rend_data_get_pk_digest(const rend_data_t *rend_data,
  186. size_t *len_out);
  187. routerstatus_t *pick_hsdir(const char *desc_id, const char *desc_id_base32);
  188. void hs_get_subcredential(const ed25519_public_key_t *identity_pk,
  189. const ed25519_public_key_t *blinded_pk,
  190. uint8_t *subcred_out);
  191. uint64_t hs_get_previous_time_period_num(time_t now);
  192. uint64_t hs_get_time_period_num(time_t now);
  193. uint64_t hs_get_next_time_period_num(time_t now);
  194. time_t hs_get_start_time_of_next_time_period(time_t now);
  195. link_specifier_t *hs_link_specifier_dup(const link_specifier_t *lspec);
  196. MOCK_DECL(int, hs_in_period_between_tp_and_srv,
  197. (const networkstatus_t *consensus, time_t now));
  198. uint8_t *hs_get_current_srv(uint64_t time_period_num,
  199. const networkstatus_t *ns);
  200. uint8_t *hs_get_previous_srv(uint64_t time_period_num,
  201. const networkstatus_t *ns);
  202. void hs_build_hsdir_index(const ed25519_public_key_t *identity_pk,
  203. const uint8_t *srv, uint64_t period_num,
  204. uint8_t *hsdir_index_out);
  205. void hs_build_hs_index(uint64_t replica,
  206. const ed25519_public_key_t *blinded_pk,
  207. uint64_t period_num, uint8_t *hs_index_out);
  208. int32_t hs_get_hsdir_n_replicas(void);
  209. int32_t hs_get_hsdir_spread_fetch(void);
  210. int32_t hs_get_hsdir_spread_store(void);
  211. void hs_get_responsible_hsdirs(const ed25519_public_key_t *blinded_pk,
  212. uint64_t time_period_num,
  213. int use_second_hsdir_index,
  214. int for_fetching, smartlist_t *responsible_dirs);
  215. routerstatus_t *hs_pick_hsdir(smartlist_t *responsible_dirs,
  216. const char *req_key_str);
  217. time_t hs_hsdir_requery_period(const or_options_t *options);
  218. time_t hs_lookup_last_hid_serv_request(routerstatus_t *hs_dir,
  219. const char *desc_id_base32,
  220. time_t now, int set);
  221. void hs_clean_last_hid_serv_requests(time_t now);
  222. void hs_purge_hid_serv_from_last_hid_serv_requests(const char *desc_id);
  223. void hs_purge_last_hid_serv_requests(void);
  224. int hs_set_conn_addr_port(const smartlist_t *ports, edge_connection_t *conn);
  225. void hs_inc_rdv_stream_counter(origin_circuit_t *circ);
  226. void hs_dec_rdv_stream_counter(origin_circuit_t *circ);
  227. extend_info_t *hs_get_extend_info_from_lspecs(const smartlist_t *lspecs,
  228. const curve25519_public_key_t *onion_key,
  229. int direct_conn);
  230. #ifdef HS_COMMON_PRIVATE
  231. STATIC void get_disaster_srv(uint64_t time_period_num, uint8_t *srv_out);
  232. /** The period for which a hidden service directory cannot be queried for
  233. * the same descriptor ID again. */
  234. #define REND_HID_SERV_DIR_REQUERY_PERIOD (15 * 60)
  235. /** Test networks generate a new consensus every 5 or 10 seconds.
  236. * So allow them to requery HSDirs much faster. */
  237. #define REND_HID_SERV_DIR_REQUERY_PERIOD_TESTING (5)
  238. #ifdef TOR_UNIT_TESTS
  239. STATIC strmap_t *get_last_hid_serv_requests(void);
  240. STATIC uint64_t get_time_period_length(void);
  241. STATIC uint8_t *get_first_cached_disaster_srv(void);
  242. STATIC uint8_t *get_second_cached_disaster_srv(void);
  243. #endif /* defined(TOR_UNIT_TESTS) */
  244. #endif /* defined(HS_COMMON_PRIVATE) */
  245. #endif /* !defined(TOR_HS_COMMON_H) */