tor  0.4.2.1-alpha-dev
hs_common.h
Go to the documentation of this file.
1 /* Copyright (c) 2016-2019, The Tor Project, Inc. */
2 /* See LICENSE for licensing information */
3 
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 and latest version we support. */
28 #define HS_VERSION_MIN HS_VERSION_TWO
29 #define HS_VERSION_MAX HS_VERSION_THREE
30 
32 #define NUM_INTRO_POINTS_DEFAULT 3
33 
34 #define NUM_INTRO_POINTS_MAX 10
35 
37 #define NUM_INTRO_POINTS_EXTRA 2
38 
40 #define INTRO_CIRC_RETRY_PERIOD (60*5)
41 
43 #define MAX_INTRO_CIRCS_PER_PERIOD 10
44 
46 #define MAX_REND_FAILURES 1
47 
49 #define MAX_REND_TIMEOUT 30
50 
51 /* String prefix for the signature of ESTABLISH_INTRO */
52 #define ESTABLISH_INTRO_SIG_PREFIX "Tor establish-intro cell v1"
53 
54 /* The default HS time period length */
55 #define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */
56 /* The minimum time period length as seen in prop224 section [TIME-PERIODS] */
57 #define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */
58 /* The minimum time period length as seen in prop224 section [TIME-PERIODS] */
59 #define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */
60 
61 /* Prefix of the onion address checksum. */
62 #define HS_SERVICE_ADDR_CHECKSUM_PREFIX ".onion checksum"
63 /* Length of the checksum prefix minus the NUL terminated byte. */
64 #define HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN \
65  (sizeof(HS_SERVICE_ADDR_CHECKSUM_PREFIX) - 1)
66 /* Length of the resulting checksum of the address. The construction of this
67  * checksum looks like:
68  * CHECKSUM = ".onion checksum" || PUBKEY || VERSION
69  * where VERSION is 1 byte. This is pre-hashing. */
70 #define HS_SERVICE_ADDR_CHECKSUM_INPUT_LEN \
71  (HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN + ED25519_PUBKEY_LEN + sizeof(uint8_t))
72 /* The amount of bytes we use from the address checksum. */
73 #define HS_SERVICE_ADDR_CHECKSUM_LEN_USED 2
74 /* Length of the binary encoded service address which is of course before the
75  * base32 encoding. Construction is:
76  * PUBKEY || CHECKSUM || VERSION
77  * with 1 byte VERSION and 2 bytes CHECKSUM. The following is 35 bytes. */
78 #define HS_SERVICE_ADDR_LEN \
79  (ED25519_PUBKEY_LEN + HS_SERVICE_ADDR_CHECKSUM_LEN_USED + sizeof(uint8_t))
80 /* Length of 'y' portion of 'y.onion' URL. This is base32 encoded and the
81  * length ends up to 56 bytes (not counting the terminated NUL byte.) */
82 #define HS_SERVICE_ADDR_LEN_BASE32 \
83  (CEIL_DIV(HS_SERVICE_ADDR_LEN * 8, 5))
84 
85 /* The default HS time period length */
86 #define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */
87 /* The minimum time period length as seen in prop224 section [TIME-PERIODS] */
88 #define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */
89 /* The minimum time period length as seen in prop224 section [TIME-PERIODS] */
90 #define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */
91 /* The time period rotation offset as seen in prop224 section [TIME-PERIODS] */
92 #define HS_TIME_PERIOD_ROTATION_OFFSET (12 * 60) /* minutes */
93 
94 /* Keyblinding parameter construction is as follow:
95  * "key-blind" || INT_8(period_num) || INT_8(start_period_sec) */
96 #define HS_KEYBLIND_NONCE_PREFIX "key-blind"
97 #define HS_KEYBLIND_NONCE_PREFIX_LEN (sizeof(HS_KEYBLIND_NONCE_PREFIX) - 1)
98 #define HS_KEYBLIND_NONCE_LEN \
99  (HS_KEYBLIND_NONCE_PREFIX_LEN + sizeof(uint64_t) + sizeof(uint64_t))
100 
101 /* Credential and subcredential prefix value. */
102 #define HS_CREDENTIAL_PREFIX "credential"
103 #define HS_CREDENTIAL_PREFIX_LEN (sizeof(HS_CREDENTIAL_PREFIX) - 1)
104 #define HS_SUBCREDENTIAL_PREFIX "subcredential"
105 #define HS_SUBCREDENTIAL_PREFIX_LEN (sizeof(HS_SUBCREDENTIAL_PREFIX) - 1)
106 
107 /* Node hidden service stored at index prefix value. */
108 #define HS_INDEX_PREFIX "store-at-idx"
109 #define HS_INDEX_PREFIX_LEN (sizeof(HS_INDEX_PREFIX) - 1)
110 
111 /* Node hidden service directory index prefix value. */
112 #define HSDIR_INDEX_PREFIX "node-idx"
113 #define HSDIR_INDEX_PREFIX_LEN (sizeof(HSDIR_INDEX_PREFIX) - 1)
114 
115 /* Prefix of the shared random value disaster mode. */
116 #define HS_SRV_DISASTER_PREFIX "shared-random-disaster"
117 #define HS_SRV_DISASTER_PREFIX_LEN (sizeof(HS_SRV_DISASTER_PREFIX) - 1)
118 
119 /* Default value of number of hsdir replicas (hsdir_n_replicas). */
120 #define HS_DEFAULT_HSDIR_N_REPLICAS 2
121 /* Default value of hsdir spread store (hsdir_spread_store). */
122 #define HS_DEFAULT_HSDIR_SPREAD_STORE 4
123 /* Default value of hsdir spread fetch (hsdir_spread_fetch). */
124 #define HS_DEFAULT_HSDIR_SPREAD_FETCH 3
125 
126 /* The size of a legacy RENDEZVOUS1 cell which adds up to 168 bytes. It is
127  * bigger than the 84 bytes needed for version 3 so we need to pad up to that
128  * length so it is indistinguishable between versions. */
129 #define HS_LEGACY_RENDEZVOUS_CELL_SIZE \
130  (REND_COOKIE_LEN + DH1024_KEY_LEN + DIGEST_LEN)
131 
132 /* Type of authentication key used by an introduction point. */
133 typedef enum {
134  HS_AUTH_KEY_TYPE_LEGACY = 1,
135  HS_AUTH_KEY_TYPE_ED25519 = 2,
136 } hs_auth_key_type_t;
137 
138 /* Return value when adding an ephemeral service through the ADD_ONION
139  * control port command. Both v2 and v3 share these. */
140 typedef enum {
148 
149 /* Represents the mapping from a virtual port of a rendezvous service to a
150  * real port on some IP. */
152  /* The incoming HS virtual port we're mapping */
153  uint16_t virtual_port;
154  /* Is this an AF_UNIX port? */
155  unsigned int is_unix_addr:1;
156  /* The outgoing TCP port to use, if !is_unix_addr */
157  uint16_t real_port;
158  /* The outgoing IPv4 or IPv6 address to use, if !is_unix_addr */
159  tor_addr_t real_addr;
160  /* The socket path to connect to, if is_unix_addr */
161  char unix_addr[FLEXIBLE_ARRAY_MEMBER];
163 
164 void hs_init(void);
165 void hs_free_all(void);
166 
167 void hs_cleanup_circ(circuit_t *circ);
168 
169 int hs_check_service_private_dir(const char *username, const char *path,
170  unsigned int dir_group_readable,
171  unsigned int create);
173 
174 char *hs_path_from_filename(const char *directory, const char *filename);
175 void hs_build_address(const struct ed25519_public_key_t *key, uint8_t version,
176  char *addr_out);
177 int hs_address_is_valid(const char *address);
178 int hs_parse_address(const char *address, struct ed25519_public_key_t *key_out,
179  uint8_t *checksum_out, uint8_t *version_out);
180 
181 void hs_build_blinded_pubkey(const struct ed25519_public_key_t *pubkey,
182  const uint8_t *secret, size_t secret_len,
183  uint64_t time_period_num,
184  struct ed25519_public_key_t *pubkey_out);
185 void hs_build_blinded_keypair(const struct ed25519_keypair_t *kp,
186  const uint8_t *secret, size_t secret_len,
187  uint64_t time_period_num,
188  struct ed25519_keypair_t *kp_out);
189 int hs_service_requires_uptime_circ(const smartlist_t *ports);
190 
191 void rend_data_free_(rend_data_t *data);
192 #define rend_data_free(data) \
193  FREE_AND_NULL(rend_data_t, rend_data_free_, (data))
194 rend_data_t *rend_data_dup(const rend_data_t *data);
195 rend_data_t *rend_data_client_create(const char *onion_address,
196  const char *desc_id,
197  const char *cookie,
198  rend_auth_type_t auth_type);
199 rend_data_t *rend_data_service_create(const char *onion_address,
200  const char *pk_digest,
201  const uint8_t *cookie,
202  rend_auth_type_t auth_type);
203 const char *rend_data_get_address(const rend_data_t *rend_data);
204 const char *rend_data_get_desc_id(const rend_data_t *rend_data,
205  uint8_t replica, size_t *len_out);
206 const uint8_t *rend_data_get_pk_digest(const rend_data_t *rend_data,
207  size_t *len_out);
208 
209 routerstatus_t *pick_hsdir(const char *desc_id, const char *desc_id_base32);
210 
211 void hs_get_subcredential(const struct ed25519_public_key_t *identity_pk,
212  const struct ed25519_public_key_t *blinded_pk,
213  uint8_t *subcred_out);
214 
215 uint64_t hs_get_previous_time_period_num(time_t now);
216 uint64_t hs_get_time_period_num(time_t now);
217 uint64_t hs_get_next_time_period_num(time_t now);
218 time_t hs_get_start_time_of_next_time_period(time_t now);
219 
220 MOCK_DECL(int, hs_in_period_between_tp_and_srv,
221  (const networkstatus_t *consensus, time_t now));
222 
223 uint8_t *hs_get_current_srv(uint64_t time_period_num,
224  const networkstatus_t *ns);
225 uint8_t *hs_get_previous_srv(uint64_t time_period_num,
226  const networkstatus_t *ns);
227 
228 void hs_build_hsdir_index(const struct ed25519_public_key_t *identity_pk,
229  const uint8_t *srv, uint64_t period_num,
230  uint8_t *hsdir_index_out);
231 void hs_build_hs_index(uint64_t replica,
232  const struct ed25519_public_key_t *blinded_pk,
233  uint64_t period_num, uint8_t *hs_index_out);
234 
235 int32_t hs_get_hsdir_n_replicas(void);
236 int32_t hs_get_hsdir_spread_fetch(void);
237 int32_t hs_get_hsdir_spread_store(void);
238 
239 void hs_get_responsible_hsdirs(const struct ed25519_public_key_t *blinded_pk,
240  uint64_t time_period_num,
241  int use_second_hsdir_index,
242  int for_fetching, smartlist_t *responsible_dirs);
243 routerstatus_t *hs_pick_hsdir(smartlist_t *responsible_dirs,
244  const char *req_key_str,
245  bool *is_rate_limited_out);
246 
247 time_t hs_hsdir_requery_period(const or_options_t *options);
249  const char *desc_id_base32,
250  time_t now, int set);
251 void hs_clean_last_hid_serv_requests(time_t now);
252 void hs_purge_hid_serv_from_last_hid_serv_requests(const char *desc_id);
254 
255 int hs_set_conn_addr_port(const smartlist_t *ports, edge_connection_t *conn);
256 
257 void hs_inc_rdv_stream_counter(origin_circuit_t *circ);
258 void hs_dec_rdv_stream_counter(origin_circuit_t *circ);
259 
260 extend_info_t *hs_get_extend_info_from_lspecs(const smartlist_t *lspecs,
261  const struct curve25519_public_key_t *onion_key,
262  int direct_conn);
263 
264 link_specifier_t *link_specifier_dup(const link_specifier_t *src);
265 
266 #ifdef HS_COMMON_PRIVATE
267 
268 STATIC void get_disaster_srv(uint64_t time_period_num, uint8_t *srv_out);
269 
272 #define REND_HID_SERV_DIR_REQUERY_PERIOD (15 * 60)
273 
275 #define REND_HID_SERV_DIR_REQUERY_PERIOD_TESTING (5)
276 
277 #ifdef TOR_UNIT_TESTS
278 
279 STATIC strmap_t *get_last_hid_serv_requests(void);
280 STATIC uint64_t get_time_period_length(void);
281 
282 STATIC uint8_t *get_first_cached_disaster_srv(void);
283 STATIC uint8_t *get_second_cached_disaster_srv(void);
284 
285 #endif /* defined(TOR_UNIT_TESTS) */
286 
287 #endif /* defined(HS_COMMON_PRIVATE) */
288 
289 #endif /* !defined(TOR_HS_COMMON_H) */
uint64_t hs_get_time_period_num(time_t now)
Definition: hs_common.c:267
STATIC strmap_t * get_last_hid_serv_requests(void)
Definition: hs_common.c:1457
void rend_data_free_(rend_data_t *data)
Definition: hs_common.c:359
rend_auth_type_t
Definition: or.h:402
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:1602
Master header file for Tor-specific functionality.
STATIC uint64_t get_time_period_length(void)
Definition: hs_common.c:241
time_t hs_hsdir_requery_period(const or_options_t *options)
Definition: hs_common.c:1427
hs_service_add_ephemeral_status_t
Definition: hs_common.h:140
int hs_get_service_max_rend_failures(void)
Definition: hs_common.c:231
uint64_t hs_get_next_time_period_num(time_t now)
Definition: hs_common.c:302
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:1470
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:94
STATIC void get_disaster_srv(uint64_t time_period_num, uint8_t *srv_out)
Definition: hs_common.c:632
void hs_purge_last_hid_serv_requests(void)
Definition: hs_common.c:1574
void hs_purge_hid_serv_from_last_hid_serv_requests(const char *desc_id)
Definition: hs_common.c:1533
void hs_clean_last_hid_serv_requests(time_t now)
Definition: hs_common.c:1504