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