Tor  0.4.8.0-alpha-dev
control_events.h
Go to the documentation of this file.
1 /* Copyright (c) 2001 Matej Pfajfar.
2  * Copyright (c) 2001-2004, Roger Dingledine.
3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4  * Copyright (c) 2007-2021, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
6 
7 /**
8  * \file control_events.h
9  * \brief Header file for control_events.c.
10  **/
11 
12 #ifndef TOR_CONTROL_EVENTS_H
13 #define TOR_CONTROL_EVENTS_H
14 
15 #include "lib/cc/ctassert.h"
16 #include "core/or/ocirc_event.h"
17 #include "core/or/orconn_event.h"
18 
19 struct config_line_t;
20 
21 /** Used to indicate the type of a CIRC_MINOR event passed to the controller.
22  * The various types are defined in control-spec.txt . */
24  CIRC_MINOR_EVENT_PURPOSE_CHANGED,
25  CIRC_MINOR_EVENT_CANNIBALIZED,
27 
28 /** Used to indicate the type of a stream event passed to the controller.
29  * The various types are defined in control-spec.txt */
30 typedef enum stream_status_event_t {
31  STREAM_EVENT_SENT_CONNECT = 0,
32  STREAM_EVENT_SENT_RESOLVE = 1,
33  STREAM_EVENT_SUCCEEDED = 2,
34  STREAM_EVENT_FAILED = 3,
35  STREAM_EVENT_CLOSED = 4,
36  STREAM_EVENT_NEW = 5,
37  STREAM_EVENT_NEW_RESOLVE = 6,
38  STREAM_EVENT_FAILED_RETRIABLE = 7,
39  STREAM_EVENT_REMAP = 8,
40  STREAM_EVENT_CONTROLLER_WAIT = 9,
41  STREAM_EVENT_XOFF_SENT = 10,
42  STREAM_EVENT_XOFF_RECV = 11,
43  STREAM_EVENT_XON_SENT = 12,
44  STREAM_EVENT_XON_RECV = 13
46 
47 /** Used to indicate the type of a buildtime event */
49  BUILDTIMEOUT_SET_EVENT_COMPUTED = 0,
50  BUILDTIMEOUT_SET_EVENT_RESET = 1,
51  BUILDTIMEOUT_SET_EVENT_SUSPENDED = 2,
52  BUILDTIMEOUT_SET_EVENT_DISCARD = 3,
53  BUILDTIMEOUT_SET_EVENT_RESUME = 4
55 
56 /** Enum describing various stages of bootstrapping, for use with controller
57  * bootstrap status events. The values range from 0 to 100. */
58 typedef enum {
59  BOOTSTRAP_STATUS_UNDEF=-1,
60  BOOTSTRAP_STATUS_STARTING=0,
61 
62  /* Initial connection to any relay */
63 
64  BOOTSTRAP_STATUS_CONN_PT=1,
65  BOOTSTRAP_STATUS_CONN_DONE_PT=2,
66  BOOTSTRAP_STATUS_CONN_PROXY=3,
67  BOOTSTRAP_STATUS_CONN_DONE_PROXY=4,
68  BOOTSTRAP_STATUS_CONN=5,
69  BOOTSTRAP_STATUS_CONN_DONE=10,
70  BOOTSTRAP_STATUS_HANDSHAKE=14,
71  BOOTSTRAP_STATUS_HANDSHAKE_DONE=15,
72 
73  /* Loading directory info */
74 
75  BOOTSTRAP_STATUS_ONEHOP_CREATE=20,
76  BOOTSTRAP_STATUS_REQUESTING_STATUS=25,
77  BOOTSTRAP_STATUS_LOADING_STATUS=30,
78  BOOTSTRAP_STATUS_LOADING_KEYS=40,
79  BOOTSTRAP_STATUS_REQUESTING_DESCRIPTORS=45,
80  BOOTSTRAP_STATUS_LOADING_DESCRIPTORS=50,
81  BOOTSTRAP_STATUS_ENOUGH_DIRINFO=75,
82 
83  /* Connecting to a relay for AP circuits */
84 
85  BOOTSTRAP_STATUS_AP_CONN_PT=76,
86  BOOTSTRAP_STATUS_AP_CONN_DONE_PT=77,
87  BOOTSTRAP_STATUS_AP_CONN_PROXY=78,
88  BOOTSTRAP_STATUS_AP_CONN_DONE_PROXY=79,
89  BOOTSTRAP_STATUS_AP_CONN=80,
90  BOOTSTRAP_STATUS_AP_CONN_DONE=85,
91  BOOTSTRAP_STATUS_AP_HANDSHAKE=89,
92  BOOTSTRAP_STATUS_AP_HANDSHAKE_DONE=90,
93 
94  /* Creating AP circuits */
95 
96  BOOTSTRAP_STATUS_CIRCUIT_CREATE=95,
97  BOOTSTRAP_STATUS_DONE=100
99 
100 /** Reason for remapping an AP connection's address: we have a cached
101  * answer. */
102 #define REMAP_STREAM_SOURCE_CACHE 1
103 /** Reason for remapping an AP connection's address: the exit node told us an
104  * answer. */
105 #define REMAP_STREAM_SOURCE_EXIT 2
106 
107 void control_initialize_event_queue(void);
108 
111 
112 #define EVENT_NS 0x000F
113 int control_event_is_interesting(int event);
114 
115 void control_per_second_events(void);
117 
119  circuit_status_event_t e, int reason);
121  int old_purpose);
123  int old_purpose,
124  const struct timeval *old_tv_created);
127  int reason);
129  or_conn_status_event_t e, int reason);
130 int control_event_bandwidth_used(uint32_t n_read, uint32_t n_written);
138 void control_event_logmsg(int severity, log_domain_mask_t domain,
139  const char *msg);
142 int control_event_address_mapped(const char *from, const char *to,
143  time_t expires, const char *error,
144  const int cached, uint64_t stream_id);
146 int control_event_network_liveness_update(int liveness);
148 
149 int control_event_newconsensus(const networkstatus_t *consensus);
151 int control_event_general_status(int severity, const char *format, ...)
152  CHECK_PRINTF(2,3);
153 int control_event_client_status(int severity, const char *format, ...)
154  CHECK_PRINTF(2,3);
155 int control_event_server_status(int severity, const char *format, ...)
156  CHECK_PRINTF(2,3);
157 
158 int control_event_general_error(const char *format, ...)
159  CHECK_PRINTF(1,2);
160 int control_event_client_error(const char *format, ...)
161  CHECK_PRINTF(1,2);
162 int control_event_server_error(const char *format, ...)
163  CHECK_PRINTF(1,2);
164 
165 int control_event_guard(const char *nickname, const char *digest,
166  const char *status);
167 void control_event_conf_changed(const struct config_line_t *changes);
169  const char *args);
170 int control_event_signal(uintptr_t signal);
171 
172 void control_event_bootstrap(bootstrap_status_t status, int progress);
173 int control_get_bootstrap_percent(void);
174 MOCK_DECL(void, control_event_bootstrap_prob_or,(const char *warn,
175  int reason,
176  or_connection_t *or_conn));
177 void control_event_boot_dir(bootstrap_status_t status, int progress);
179 void control_event_bootstrap_problem(const char *warn, const char *reason,
180  const connection_t *conn, int dowarn);
181 char *control_event_boot_last_msg(void);
183 
184 void control_event_clients_seen(const char *controller_str);
185 void control_event_transport_launched(const char *mode,
186  const char *transport_name,
187  tor_addr_t *addr, uint16_t port);
188 void control_event_pt_log(const char *log);
189 void control_event_pt_status(const char *status);
190 
191 void control_event_hs_descriptor_requested(const char *onion_address,
192  rend_auth_type_t auth_type,
193  const char *id_digest,
194  const char *desc_id,
195  const char *hsdir_index);
196 void control_event_hs_descriptor_created(const char *onion_address,
197  const char *desc_id,
198  int replica);
199 void control_event_hs_descriptor_upload(const char *onion_address,
200  const char *desc_id,
201  const char *hs_dir,
202  const char *hsdir_index);
203 void control_event_hs_descriptor_upload_end(const char *action,
204  const char *onion_address,
205  const char *hs_dir,
206  const char *reason);
207 void control_event_hs_descriptor_uploaded(const char *hs_dir,
208  const char *onion_address);
209 /* Hidden service v3 HS_DESC specific. */
210 void control_event_hsv3_descriptor_failed(const char *onion_address,
211  const char *desc_id,
212  const char *hsdir_id_digest,
213  const char *reason);
214 void control_event_hsv3_descriptor_received(const char *onion_address,
215  const char *desc_id,
216  const char *hsdir_id_digest);
217 void control_event_hs_descriptor_upload_failed(const char *hs_dir,
218  const char *onion_address,
219  const char *reason);
220 void control_event_hs_descriptor_content(const char *onion_address,
221  const char *desc_id,
222  const char *hsdir_fp,
223  const char *content);
224 void cbt_control_event_buildtimeout_set(const circuit_build_times_t *cbt,
226 
227 int control_event_enter_controller_wait(void);
228 
229 void control_events_free_all(void);
230 
231 #ifdef CONTROL_MODULE_PRIVATE
232 char *get_bw_samples(void);
233 #endif /* defined(CONTROL_MODULE_PRIVATE) */
234 
235 #ifdef CONTROL_EVENTS_PRIVATE
236 /** Bitfield: The bit 1&lt;&lt;e is set if <b>any</b> open control
237  * connection is interested in events of type <b>e</b>. We use this
238  * so that we can decide to skip generating event messages that nobody
239  * has interest in without having to walk over the global connection
240  * list to find out.
241  **/
242 typedef uint64_t event_mask_t;
243 
244 /* Recognized asynchronous event types. It's okay to expand this list
245  * because it is used both as a list of v0 event types, and as indices
246  * into the bitfield to determine which controllers want which events.
247  */
248 /* This bitfield has no event zero 0x0000 */
249 #define EVENT_MIN_ 0x0001
250 #define EVENT_CIRCUIT_STATUS 0x0001
251 #define EVENT_STREAM_STATUS 0x0002
252 #define EVENT_OR_CONN_STATUS 0x0003
253 #define EVENT_BANDWIDTH_USED 0x0004
254 #define EVENT_CIRCUIT_STATUS_MINOR 0x0005
255 #define EVENT_NEW_DESC 0x0006
256 #define EVENT_DEBUG_MSG 0x0007
257 #define EVENT_INFO_MSG 0x0008
258 #define EVENT_NOTICE_MSG 0x0009
259 #define EVENT_WARN_MSG 0x000A
260 #define EVENT_ERR_MSG 0x000B
261 #define EVENT_ADDRMAP 0x000C
262 /* There was an AUTHDIR_NEWDESCS event, but it no longer exists. We
263  can reclaim 0x000D. */
264 #define EVENT_DESCCHANGED 0x000E
265 /* Exposed above */
266 // #define EVENT_NS 0x000F
267 #define EVENT_STATUS_CLIENT 0x0010
268 #define EVENT_STATUS_SERVER 0x0011
269 #define EVENT_STATUS_GENERAL 0x0012
270 #define EVENT_GUARD 0x0013
271 #define EVENT_STREAM_BANDWIDTH_USED 0x0014
272 #define EVENT_CLIENTS_SEEN 0x0015
273 #define EVENT_NEWCONSENSUS 0x0016
274 #define EVENT_BUILDTIMEOUT_SET 0x0017
275 #define EVENT_GOT_SIGNAL 0x0018
276 #define EVENT_CONF_CHANGED 0x0019
277 #define EVENT_CONN_BW 0x001A
278 #define EVENT_CELL_STATS 0x001B
279 /* UNUSED : 0x001C */
280 #define EVENT_CIRC_BANDWIDTH_USED 0x001D
281 #define EVENT_TRANSPORT_LAUNCHED 0x0020
282 #define EVENT_HS_DESC 0x0021
283 #define EVENT_HS_DESC_CONTENT 0x0022
284 #define EVENT_NETWORK_LIVENESS 0x0023
285 #define EVENT_PT_LOG 0x0024
286 #define EVENT_PT_STATUS 0x0025
287 #define EVENT_MAX_ 0x0025
288 
289 /* sizeof(control_connection_t.event_mask) in bits, currently a uint64_t */
290 #define EVENT_CAPACITY_ 0x0040
291 
292 /* If EVENT_MAX_ ever hits 0x0040, we need to make the mask into a
293  * different structure, as it can only handle a maximum left shift of 1<<63. */
294 CTASSERT(EVENT_MAX_ < EVENT_CAPACITY_);
295 
296 #define EVENT_MASK_(e) (((uint64_t)1)<<(e))
297 
298 #define EVENT_MASK_NONE_ ((uint64_t)0x0)
299 
300 #define EVENT_MASK_ABOVE_MIN_ ((~((uint64_t)0x0)) << EVENT_MIN_)
301 #define EVENT_MASK_BELOW_MAX_ ((~((uint64_t)0x0)) \
302  >> (EVENT_CAPACITY_ - EVENT_MAX_ \
303  - EVENT_MIN_))
304 
305 #define EVENT_MASK_ALL_ (EVENT_MASK_ABOVE_MIN_ \
306  & EVENT_MASK_BELOW_MAX_)
307 
308 /** Helper structure: temporarily stores cell statistics for a circuit. */
309 typedef struct cell_stats_t {
310  /** Number of cells added in app-ward direction by command. */
311  uint64_t added_cells_appward[CELL_COMMAND_MAX_ + 1];
312  /** Number of cells added in exit-ward direction by command. */
313  uint64_t added_cells_exitward[CELL_COMMAND_MAX_ + 1];
314  /** Number of cells removed in app-ward direction by command. */
315  uint64_t removed_cells_appward[CELL_COMMAND_MAX_ + 1];
316  /** Number of cells removed in exit-ward direction by command. */
317  uint64_t removed_cells_exitward[CELL_COMMAND_MAX_ + 1];
318  /** Total waiting time of cells in app-ward direction by command. */
319  uint64_t total_time_appward[CELL_COMMAND_MAX_ + 1];
320  /** Total waiting time of cells in exit-ward direction by command. */
321  uint64_t total_time_exitward[CELL_COMMAND_MAX_ + 1];
322 } cell_stats_t;
323 
325  cell_stats_t *cell_stats);
326 void append_cell_stats_by_command(smartlist_t *event_parts,
327  const char *key,
328  const uint64_t *include_if_non_zero,
329  const uint64_t *number_to_include);
330 void format_cell_stats(char **event_string, circuit_t *circ,
331  cell_stats_t *cell_stats);
332 
333 /** Helper structure: maps event values to their names. */
334 struct control_event_t {
335  uint16_t event_code;
336  const char *event_name;
337 };
338 
339 extern const struct control_event_t control_event_table[];
340 
341 void control_logmsg_strip_newlines(char *msg);
342 
343 #ifdef TOR_UNIT_TESTS
344 MOCK_DECL(STATIC void,
345  send_control_event_string,(uint16_t event, const char *msg));
346 
347 MOCK_DECL(STATIC void,
348  queue_control_event_string,(uint16_t event, char *msg));
349 
350 void control_testing_set_global_event_mask(uint64_t mask);
351 
352 #endif /* defined(TOR_UNIT_TESTS) */
353 
354 #endif /* defined(CONTROL_EVENTS_PRIVATE) */
355 
356 #endif /* !defined(TOR_CONTROL_EVENTS_H) */
const struct control_event_t control_event_table[]
void format_cell_stats(char **event_string, circuit_t *circ, cell_stats_t *cell_stats)
STATIC void send_control_event_string(uint16_t event, const char *msg)
void sum_up_cell_stats_by_command(circuit_t *circ, cell_stats_t *cell_stats)
STATIC void queue_control_event_string(uint16_t event, char *msg)
void append_cell_stats_by_command(smartlist_t *event_parts, const char *key, const uint64_t *include_if_non_zero, const uint64_t *number_to_include)
void control_logmsg_strip_newlines(char *msg)
void control_event_conf_changed(const config_line_t *changes)
void control_event_pt_status(const char *status)
int control_event_my_descriptor_changed(void)
int control_event_server_error(const char *format,...)
int control_event_stream_bandwidth(edge_connection_t *edge_conn)
void control_event_pt_log(const char *log)
void control_event_bootstrap_reset(void)
void control_event_hs_descriptor_upload(const char *onion_address, const char *desc_id, const char *hs_dir, const char *hsdir_index)
int control_event_general_status(int severity, const char *format,...)
void control_event_clients_seen(const char *controller_str)
int control_event_bandwidth_used(uint32_t n_read, uint32_t n_written)
int control_event_circuit_purpose_changed(origin_circuit_t *circ, int old_purpose)
int control_event_conn_bandwidth(connection_t *conn)
int control_event_circuit_cell_stats(void)
char * control_event_boot_last_msg(void)
int control_event_or_conn_status(or_connection_t *conn, or_conn_status_event_t e, int reason)
int control_event_buildtimeout_set(buildtimeout_set_event_t type, const char *args)
void control_event_hs_descriptor_requested(const char *onion_address, rend_auth_type_t auth_type, const char *id_digest, const char *desc_id, const char *hsdir_index)
int control_event_stream_bandwidth_used(void)
int control_event_guard(const char *nickname, const char *digest, const char *status)
stream_status_event_t
int control_event_general_error(const char *format,...)
int control_event_networkstatus_changed(smartlist_t *statuses)
int control_event_server_status(int severity, const char *format,...)
void control_event_hs_descriptor_upload_end(const char *action, const char *onion_address, const char *hs_dir, const char *reason)
int control_event_circ_bandwidth_used_for_circ(origin_circuit_t *ocirc)
int control_event_is_interesting(int event)
int control_event_client_error(const char *format,...)
int control_event_circ_bandwidth_used(void)
circuit_status_minor_event_t
int control_event_circuit_status(origin_circuit_t *circ, circuit_status_event_t e, int reason)
void control_event_hsv3_descriptor_failed(const char *onion_address, const char *desc_id, const char *hsdir_id_digest, const char *reason)
int control_event_network_liveness_update(int liveness)
void control_event_transport_launched(const char *mode, const char *transport_name, tor_addr_t *addr, uint16_t port)
void control_event_bootstrap_problem(const char *warn, const char *reason, const connection_t *conn, int dowarn)
int control_event_conn_bandwidth_used(void)
void control_adjust_event_log_severity(void)
int control_event_client_status(int severity, const char *format,...)
void control_event_hs_descriptor_content(const char *onion_address, const char *desc_id, const char *hsdir_fp, const char *content)
void control_event_hs_descriptor_uploaded(const char *hs_dir, const char *onion_address)
int control_event_networkstatus_changed_single(const routerstatus_t *rs)
int control_event_stream_status(entry_connection_t *conn, stream_status_event_t e, int reason)
int control_event_circuit_cannibalized(origin_circuit_t *circ, int old_purpose, const struct timeval *old_tv_created)
void control_event_boot_dir(bootstrap_status_t status, int progress)
void control_event_hs_descriptor_upload_failed(const char *hs_dir, const char *onion_address, const char *reason)
int control_event_descriptors_changed(smartlist_t *routers)
int control_event_newconsensus(const networkstatus_t *consensus)
void control_event_bootstrap(bootstrap_status_t status, int progress)
bootstrap_status_t
void control_event_boot_first_orconn(void)
int control_event_address_mapped(const char *from, const char *to, time_t expires, const char *error, const int cached, uint64_t stream_id)
int control_event_signal(uintptr_t signal)
void control_event_hs_descriptor_created(const char *onion_address, const char *desc_id, int replica)
void control_event_logmsg_pending(void)
void control_update_global_event_mask(void)
void control_per_second_events(void)
void control_event_logmsg(int severity, log_domain_mask_t domain, const char *msg)
buildtimeout_set_event_t
void control_event_bootstrap_prob_or(const char *warn, int reason, or_connection_t *or_conn)
int control_any_per_second_event_enabled(void)
Compile-time assertions: CTASSERT(expression).
CTASSERT(NUMBER_SECOND_GUARDS< 20)
uint64_t log_domain_mask_t
Definition: logging_types.h:21
Header file for ocirc_event.c.
circuit_status_event_t
Definition: ocirc_event.h:19
rend_auth_type_t
Definition: or.h:347
Header file for orconn_event.c.
or_conn_status_event_t
Definition: orconn_event.h:59
#define STATIC
Definition: testsupport.h:32
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127