tor  0.4.0.1-alpha
hs_service.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_SERVICE_H
10 #define TOR_HS_SERVICE_H
11 
15 
16 #include "feature/hs/hs_common.h"
18 #include "feature/hs/hs_ident.h"
20 
21 /* Trunnel */
22 #include "trunnel/hs/cell_establish_intro.h"
23 
24 /* When loading and configuring a service, this is the default version it will
25  * be configured for as it is possible that no HiddenServiceVersion is
26  * present. */
27 #define HS_SERVICE_DEFAULT_VERSION HS_VERSION_THREE
28 
29 /* As described in the specification, service publishes their next descriptor
30  * at a random time between those two values (in seconds). */
31 #define HS_SERVICE_NEXT_UPLOAD_TIME_MIN (60 * 60)
32 #define HS_SERVICE_NEXT_UPLOAD_TIME_MAX (120 * 60)
33 
34 /* Service side introduction point. */
35 typedef struct hs_service_intro_point_t {
36  /* Top level intropoint "shared" data between client/service. */
37  hs_intropoint_t base;
38 
39  /* Onion key of the introduction point used to extend to it for the ntor
40  * handshake. */
41  curve25519_public_key_t onion_key;
42 
43  /* Authentication keypair used to create the authentication certificate
44  * which is published in the descriptor. */
45  ed25519_keypair_t auth_key_kp;
46 
47  /* Encryption keypair for the "ntor" type. */
48  curve25519_keypair_t enc_key_kp;
49 
50  /* Legacy key if that intro point doesn't support v3. This should be used if
51  * the base object legacy flag is set. */
52  crypto_pk_t *legacy_key;
53  /* Legacy key SHA1 public key digest. This should be used only if the base
54  * object legacy flag is set. */
55  uint8_t legacy_key_digest[DIGEST_LEN];
56 
57  /* Amount of INTRODUCE2 cell accepted from this intro point. */
58  uint64_t introduce2_count;
59 
60  /* Maximum number of INTRODUCE2 cell this intro point should accept. */
61  uint64_t introduce2_max;
62 
63  /* The time at which this intro point should expire and stop being used. */
64  time_t time_to_expire;
65 
66  /* The amount of circuit creation we've made to this intro point. This is
67  * incremented every time we do a circuit relaunch on this intro point which
68  * is triggered when the circuit dies but the node is still in the
69  * consensus. After MAX_INTRO_POINT_CIRCUIT_RETRIES, we give up on it. */
70  uint32_t circuit_retries;
71 
72  /* Set if this intro point has an established circuit. */
73  unsigned int circuit_established : 1;
74 
75  /* Replay cache recording the encrypted part of an INTRODUCE2 cell that the
76  * circuit associated with this intro point has received. This is used to
77  * prevent replay attacks. */
78  replaycache_t *replay_cache;
80 
81 /* Object handling introduction points of a service. */
82 typedef struct hs_service_intropoints_t {
83  /* The time at which we've started our retry period to build circuits. We
84  * don't want to stress circuit creation so we can only retry for a certain
85  * time and then after we stop and wait. */
86  time_t retry_period_started;
87 
88  /* Number of circuit we've launched during a single retry period. */
89  unsigned int num_circuits_launched;
90 
91  /* Contains the current hs_service_intro_point_t objects indexed by
92  * authentication public key. */
93  digest256map_t *map;
94 
95  /* Contains node's identity key digest that were introduction point for this
96  * descriptor but were retried to many times. We keep those so we avoid
97  * re-picking them over and over for a circuit retry period.
98  * XXX: Once we have #22173, change this to only use ed25519 identity. */
99  digestmap_t *failed_id;
101 
102 /* Representation of a service descriptor.
103  *
104  * Some elements of the descriptor are mutable whereas others are immutable:
105 
106  * Immutable elements are initialized once when the descriptor is built (when
107  * service descriptors gets rotated). This means that these elements are
108  * initialized once and then they don't change for the lifetime of the
109  * descriptor. See build_service_descriptor().
110  *
111  * Mutable elements are initialized when we build the descriptor but they are
112  * also altered during the lifetime of the descriptor. They could be
113  * _refreshed_ everytime we upload the descriptor (which happens multiple times
114  * over the lifetime of the descriptor), or through periodic events. We do this
115  * for elements like the descriptor revision counter and various
116  * certificates. See refresh_service_descriptor() and
117  * update_service_descriptor_intro_points().
118  */
119 typedef struct hs_service_descriptor_t {
120  /* Immutable: Client authorization ephemeral keypair. */
121  curve25519_keypair_t auth_ephemeral_kp;
122 
123  /* Immutable: Descriptor cookie used to encrypt the descriptor, when the
124  * client authorization is enabled */
125  uint8_t descriptor_cookie[HS_DESC_DESCRIPTOR_COOKIE_LEN];
126 
127  /* Immutable: Descriptor signing keypair. */
128  ed25519_keypair_t signing_kp;
129 
130  /* Immutable: Blinded keypair derived from the master identity public key. */
131  ed25519_keypair_t blinded_kp;
132 
133  /* Immutable: The time period number this descriptor has been created for. */
134  uint64_t time_period_num;
135 
139 
140  /* Mutable: Decoded descriptor. This object is used for encoding when the
141  * service publishes the descriptor. */
142  hs_descriptor_t *desc;
143 
144  /* Mutable: When is the next time when we should upload the descriptor. */
145  time_t next_upload_time;
146 
147  /* Mutable: Introduction points assign to this descriptor which contains
148  * hs_service_intropoints_t object indexed by authentication key (the RSA key
149  * if the node is legacy). */
150  hs_service_intropoints_t intro_points;
151 
152  /* Mutable: True iff we have missing intro points for this descriptor because
153  * we couldn't pick any nodes. */
154  unsigned int missing_intro_points : 1;
155 
162 
163 /* Service key material. */
164 typedef struct hs_service_keys_t {
165  /* Master identify public key. */
166  ed25519_public_key_t identity_pk;
167  /* Master identity private key. */
168  ed25519_secret_key_t identity_sk;
169  /* True iff the key is kept offline which means the identity_sk MUST not be
170  * used in that case. */
171  unsigned int is_identify_key_offline : 1;
173 
176  /* The client auth public key used to encrypt the descriptor cookie. */
177  curve25519_public_key_t client_pk;
179 
181 typedef enum {
184 
188 
189 /* Service configuration. The following are set from the torrc options either
190  * set by the configuration file or by the control port. Nothing else should
191  * change those values. */
192 typedef struct hs_service_config_t {
193  /* Protocol version of the service. Specified by HiddenServiceVersion
194  * option. */
195  uint32_t version;
196 
197  /* Have we explicitly set HiddenServiceVersion? */
198  unsigned int hs_version_explicitly_set : 1;
199 
200  /* List of rend_service_port_config_t */
201  smartlist_t *ports;
202 
203  /* Path on the filesystem where the service persistent data is stored. NULL
204  * if the service is ephemeral. Specified by HiddenServiceDir option. */
205  char *directory_path;
206 
207  /* The maximum number of simultaneous streams per rendezvous circuit that
208  * are allowed to be created. No limit if 0. Specified by
209  * HiddenServiceMaxStreams option. */
210  uint64_t max_streams_per_rdv_circuit;
211 
212  /* If true, we close circuits that exceed the max_streams_per_rdv_circuit
213  * limit. Specified by HiddenServiceMaxStreamsCloseCircuit option. */
214  unsigned int max_streams_close_circuit : 1;
215 
216  /* How many introduction points this service has. Specified by
217  * HiddenServiceNumIntroductionPoints option. */
218  unsigned int num_intro_points;
219 
220  /* True iff the client auth is enabled. */
221  unsigned int is_client_auth_enabled : 1;
222 
223  /* List of hs_service_authorized_client_t's of clients that may access this
224  * service. Specified by HiddenServiceAuthorizeClient option. */
225  smartlist_t *clients;
226 
227  /* True iff we allow request made on unknown ports. Specified by
228  * HiddenServiceAllowUnknownPorts option. */
229  unsigned int allow_unknown_ports : 1;
230 
231  /* If true, this service is a Single Onion Service. Specified by
232  * HiddenServiceSingleHopMode and HiddenServiceNonAnonymousMode options. */
233  unsigned int is_single_onion : 1;
234 
235  /* If true, allow group read permissions on the directory_path. Specified by
236  * HiddenServiceDirGroupReadable option. */
237  unsigned int dir_group_readable : 1;
238 
239  /* Is this service ephemeral? */
240  unsigned int is_ephemeral : 1;
241 
242  /* Does this service export the circuit ID of its clients? */
243  hs_circuit_id_protocol_t circuit_id_protocol;
245 
246 /* Service state. */
247 typedef struct hs_service_state_t {
248  /* The time at which we've started our retry period to build circuits. We
249  * don't want to stress circuit creation so we can only retry for a certain
250  * time and then after we stop and wait. */
251  time_t intro_circ_retry_started_time;
252 
253  /* Number of circuit we've launched during a single retry period. This
254  * should never go over MAX_INTRO_CIRCS_PER_PERIOD. */
255  unsigned int num_intro_circ_launched;
256 
257  /* Replay cache tracking the REND_COOKIE found in INTRODUCE2 cell to detect
258  * repeats. Clients may send INTRODUCE1 cells for the same rendezvous point
259  * through two or more different introduction points; when they do, this
260  * keeps us from launching multiple simultaneous attempts to connect to the
261  * same rend point. */
262  replaycache_t *replay_cache_rend_cookie;
263 
264  /* When is the next time we should rotate our descriptors. This is has to be
265  * done at the start time of the next SRV protocol run. */
266  time_t next_rotation_time;
268 
269 /* Representation of a service running on this tor instance. */
270 typedef struct hs_service_t {
271  /* Onion address base32 encoded and NUL terminated. We keep it for logging
272  * purposes so we don't have to build it everytime. */
273  char onion_address[HS_SERVICE_ADDR_LEN_BASE32 + 1];
274 
275  /* Hashtable node: use to look up the service by its master public identity
276  * key in the service global map. */
277  HT_ENTRY(hs_service_t) hs_service_node;
278 
279  /* Service state which contains various flags and counters. */
280  hs_service_state_t state;
281 
282  /* Key material of the service. */
283  hs_service_keys_t keys;
284 
285  /* Configuration of the service. */
286  hs_service_config_t config;
287 
288  /* Current descriptor. */
289  hs_service_descriptor_t *desc_current;
290  /* Next descriptor. */
291  hs_service_descriptor_t *desc_next;
292 
293  /* XXX: Credential (client auth.) #20700. */
294 
295 } hs_service_t;
296 
297 /* For the service global hash map, we define a specific type for it which
298  * will make it safe to use and specific to some controlled parameters such as
299  * the hashing function and how to compare services. */
300 typedef HT_HEAD(hs_service_ht, hs_service_t) hs_service_ht;
301 
302 /* API */
303 
304 /* Global initializer and cleanup function. */
305 void hs_service_init(void);
306 void hs_service_free_all(void);
307 
308 /* Service new/free functions. */
309 hs_service_t *hs_service_new(const or_options_t *options);
310 void hs_service_free_(hs_service_t *service);
311 #define hs_service_free(s) FREE_AND_NULL(hs_service_t, hs_service_free_, (s))
312 
313 MOCK_DECL(unsigned int, hs_service_get_num_services,(void));
314 void hs_service_stage_services(const smartlist_t *service_list);
315 int hs_service_load_all_keys(void);
316 int hs_service_get_version_from_key(const hs_service_t *service);
317 void hs_service_lists_fnames_for_sandbox(smartlist_t *file_list,
318  smartlist_t *dir_list);
319 int hs_service_set_conn_addr_port(const origin_circuit_t *circ,
320  edge_connection_t *conn);
321 
322 void hs_service_map_has_changed(void);
323 void hs_service_dir_info_changed(void);
324 void hs_service_run_scheduled_events(time_t now);
325 void hs_service_circuit_has_opened(origin_circuit_t *circ);
326 int hs_service_receive_intro_established(origin_circuit_t *circ,
327  const uint8_t *payload,
328  size_t payload_len);
329 int hs_service_receive_introduce2(origin_circuit_t *circ,
330  const uint8_t *payload,
331  size_t payload_len);
332 
333 void hs_service_intro_circ_has_closed(origin_circuit_t *circ);
334 
335 char *hs_service_lookup_current_desc(const ed25519_public_key_t *pk);
336 
338 hs_service_add_ephemeral(ed25519_secret_key_t *sk, smartlist_t *ports,
339  int max_streams_per_rdv_circuit,
340  int max_streams_close_circuit, char **address_out);
341 int hs_service_del_ephemeral(const char *address);
342 
343 /* Used outside of the HS subsystem by the control port command HSPOST. */
344 void hs_service_upload_desc_to_dir(const char *encoded_desc,
345  const uint8_t version,
346  const ed25519_public_key_t *identity_pk,
347  const ed25519_public_key_t *blinded_pk,
348  const routerstatus_t *hsdir_rs);
349 
352 
353 #ifdef HS_SERVICE_PRIVATE
354 
355 #ifdef TOR_UNIT_TESTS
356 /* Useful getters for unit tests. */
357 STATIC unsigned int get_hs_service_map_size(void);
358 STATIC int get_hs_service_staging_list_size(void);
359 STATIC hs_service_ht *get_hs_service_map(void);
360 STATIC hs_service_t *get_first_service(void);
361 STATIC hs_service_intro_point_t *service_intro_point_find_by_ident(
362  const hs_service_t *service,
363  const hs_ident_circuit_t *ident);
364 #endif
365 
366 /* Service accessors. */
367 STATIC hs_service_t *find_service(hs_service_ht *map,
368  const ed25519_public_key_t *pk);
369 STATIC void remove_service(hs_service_ht *map, hs_service_t *service);
370 STATIC int register_service(hs_service_ht *map, hs_service_t *service);
371 /* Service introduction point functions. */
372 STATIC hs_service_intro_point_t *service_intro_point_new(
373  const extend_info_t *ei,
374  unsigned int is_legacy,
375  unsigned int supports_ed25519_link_handshake_any);
376 STATIC void service_intro_point_free_(hs_service_intro_point_t *ip);
377 #define service_intro_point_free(ip) \
378  FREE_AND_NULL(hs_service_intro_point_t, \
379  service_intro_point_free_, (ip))
380 STATIC void service_intro_point_add(digest256map_t *map,
382 STATIC void service_intro_point_remove(const hs_service_t *service,
383  const hs_service_intro_point_t *ip);
384 STATIC hs_service_intro_point_t *service_intro_point_find(
385  const hs_service_t *service,
386  const ed25519_public_key_t *auth_key);
387 /* Service descriptor functions. */
388 STATIC hs_service_descriptor_t *service_descriptor_new(void);
389 STATIC hs_service_descriptor_t *service_desc_find_by_intro(
390  const hs_service_t *service,
391  const hs_service_intro_point_t *ip);
392 /* Helper functions. */
393 STATIC int client_filename_is_valid(const char *filename);
395 parse_authorized_client(const char *client_key_str);
396 STATIC void get_objects_from_ident(const hs_ident_circuit_t *ident,
397  hs_service_t **service,
399  hs_service_descriptor_t **desc);
400 STATIC const node_t *
401 get_node_from_intro_point(const hs_service_intro_point_t *ip);
402 STATIC int can_service_launch_intro_circuit(hs_service_t *service,
403  time_t now);
404 STATIC int intro_point_should_expire(const hs_service_intro_point_t *ip,
405  time_t now);
406 STATIC void run_housekeeping_event(time_t now);
407 STATIC void rotate_all_descriptors(time_t now);
408 STATIC void build_all_descriptors(time_t now);
409 STATIC void update_all_descriptors_intro_points(time_t now);
410 STATIC void run_upload_descriptor_event(time_t now);
411 
412 STATIC void service_descriptor_free_(hs_service_descriptor_t *desc);
413 #define service_descriptor_free(d) \
414  FREE_AND_NULL(hs_service_descriptor_t, \
415  service_descriptor_free_, (d))
416 
417 STATIC void
418 service_authorized_client_free_(hs_service_authorized_client_t *client);
419 #define service_authorized_client_free(c) \
420  FREE_AND_NULL(hs_service_authorized_client_t, \
421  service_authorized_client_free_, (c))
422 
423 STATIC int
424 write_address_to_file(const hs_service_t *service, const char *fname_);
425 
426 STATIC void upload_descriptor_to_all(const hs_service_t *service,
428 
430  time_t now,
431  int descriptor_changed);
432 
433 STATIC int service_desc_hsdirs_changed(const hs_service_t *service,
434  const hs_service_descriptor_t *desc);
435 
436 STATIC int service_authorized_client_config_equal(
437  const hs_service_config_t *config1,
438  const hs_service_config_t *config2);
439 
440 STATIC void service_clear_config(hs_service_config_t *config);
441 
442 #endif /* defined(HS_SERVICE_PRIVATE) */
443 
444 #endif /* !defined(TOR_HS_SERVICE_H) */
Header file containing common data for the whole HS subsytem.
Definition: node_st.h:28
STATIC int service_desc_hsdirs_changed(const hs_service_t *service, const hs_service_descriptor_t *desc)
Definition: hs_service.c:3002
Header file for replaycache.c.
struct hs_service_authorized_client_t hs_service_authorized_client_t
struct crypto_ope_t * ope_cipher
Definition: hs_service.h:138
smartlist_t * previous_hsdirs
Definition: hs_service.h:160
STATIC void upload_descriptor_to_all(const hs_service_t *service, hs_service_descriptor_t *desc)
Definition: hs_service.c:2945
#define DIGEST_LEN
Definition: digest_sizes.h:20
Header file containing circuit and connection identifier data for the whole HS subsytem.
Header for crypto_ed25519.c.
hs_circuit_id_protocol_t hs_service_exports_circuit_id(const ed25519_public_key_t *pk)
Definition: hs_service.c:3811
hs_service_add_ephemeral_status_t
Definition: hs_common.h:140
Header file for hs_descriptor.c.
Header file for hs_intropoint.c.
hs_circuit_id_protocol_t
Definition: hs_service.h:181
STATIC void service_desc_schedule_upload(hs_service_descriptor_t *desc, time_t now, int descriptor_changed)
Definition: hs_service.c:2280
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:94
Header for crypto_curve25519.c.