src/feature/control/control_events.h

   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 . */
  23 typedef enum circuit_status_minor_event_t {
  24   CIRC_MINOR_EVENT_PURPOSE_CHANGED,
  25   CIRC_MINOR_EVENT_CANNIBALIZED,
  26 } circuit_status_minor_event_t;
  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
  45 } stream_status_event_t;
  46
  47 /** Used to indicate the type of a buildtime event */
  48 typedef enum buildtimeout_set_event_t {
  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
  54 } buildtimeout_set_event_t;
  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
  98 } bootstrap_status_t;
  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
 109 void control_update_global_event_mask(void);
 110 void control_adjust_event_log_severity(void);
 111
 112 #define EVENT_NS 0x000F
 113 int control_event_is_interesting(int event);
 114
 115 void control_per_second_events(void);
 116 int control_any_per_second_event_enabled(void);
 117
 118 int control_event_circuit_status(origin_circuit_t *circ,
 119                                  circuit_status_event_t e, int reason);
 120 int control_event_circuit_purpose_changed(origin_circuit_t *circ,
 121                                           int old_purpose);
 122 int control_event_circuit_cannibalized(origin_circuit_t *circ,
 123                                        int old_purpose,
 124                                        const struct timeval *old_tv_created);
 125 int control_event_stream_status(entry_connection_t *conn,
 126                                 stream_status_event_t e,
 127                                 int reason);
 128 int control_event_or_conn_status(or_connection_t *conn,
 129                                  or_conn_status_event_t e, int reason);
 130 int control_event_bandwidth_used(uint32_t n_read, uint32_t n_written);
 131 int control_event_stream_bandwidth(edge_connection_t *edge_conn);
 132 int control_event_stream_bandwidth_used(void);
 133 int control_event_circ_bandwidth_used(void);
 134 int control_event_circ_bandwidth_used_for_circ(origin_circuit_t *ocirc);
 135 int control_event_conn_bandwidth(connection_t *conn);
 136 int control_event_conn_bandwidth_used(void);
 137 int control_event_circuit_cell_stats(void);
 138 void control_event_logmsg(int severity, log_domain_mask_t domain,
 139                           const char *msg);
 140 void control_event_logmsg_pending(void);
 141 int control_event_descriptors_changed(smartlist_t *routers);
 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);
 145 int control_event_my_descriptor_changed(void);
 146 int control_event_network_liveness_update(int liveness);
 147 int control_event_networkstatus_changed(smartlist_t *statuses);
 148
 149 int control_event_newconsensus(const networkstatus_t *consensus);
 150 int control_event_networkstatus_changed_single(const routerstatus_t *rs);
 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);
 168 int control_event_buildtimeout_set(buildtimeout_set_event_t type,
 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);
 178 void control_event_boot_first_orconn(void);
 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);
 182 void control_event_bootstrap_reset(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,
 225                                         buildtimeout_set_event_t type);
 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
 324 void sum_up_cell_stats_by_command(circuit_t *circ,
 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) */