src/or/channel.h

   1 /* * Copyright (c) 2012-2013, The Tor Project, Inc. */
   2 /* See LICENSE for licensing information */
   3
   4 /**
   5  * \file channel.h
   6  * \brief Header file for channel.c
   7  **/
   8
   9 #ifndef TOR_CHANNEL_H
  10 #define TOR_CHANNEL_H
  11
  12 #include "or.h"
  13 #include "circuitmux.h"
  14
  15 /* Channel handler function pointer typedefs */
  16 typedef void (*channel_listener_fn_ptr)(channel_listener_t *, channel_t *);
  17 typedef void (*channel_cell_handler_fn_ptr)(channel_t *, cell_t *);
  18 typedef void (*channel_var_cell_handler_fn_ptr)(channel_t *, var_cell_t *);
  19
  20 struct cell_queue_entry_s;
  21 TOR_SIMPLEQ_HEAD(chan_cell_queue, cell_queue_entry_s) incoming_queue;
  22 typedef struct chan_cell_queue chan_cell_queue_t;
  23
  24 /**
  25  * Channel struct; see the channel_t typedef in or.h.  A channel is an
  26  * abstract interface for the OR-to-OR connection, similar to connection_or_t,
  27  * but without the strong coupling to the underlying TLS implementation.  They
  28  * are constructed by calling a protocol-specific function to open a channel
  29  * to a particular node, and once constructed support the abstract operations
  30  * defined below.
  31  */
  32
  33 struct channel_s {
  34   /** Magic number for type-checking cast macros */
  35   uint32_t magic;
  36
  37   /** Current channel state */
  38   channel_state_t state;
  39
  40   /** Globally unique ID number for a channel over the lifetime of a Tor
  41    * process.
  42    */
  43   uint64_t global_identifier;
  44
  45   /** Should we expect to see this channel in the channel lists? */
  46   unsigned char registered:1;
  47
  48   /** has this channel ever been open? */
  49   unsigned int has_been_open:1;
  50
  51   /** Why did we close?
  52    */
  53   enum {
  54     CHANNEL_NOT_CLOSING = 0,
  55     CHANNEL_CLOSE_REQUESTED,
  56     CHANNEL_CLOSE_FROM_BELOW,
  57     CHANNEL_CLOSE_FOR_ERROR
  58   } reason_for_closing;
  59
  60   /** Timestamps for both cell channels and listeners */
  61   time_t timestamp_created; /* Channel created */
  62   time_t timestamp_active; /* Any activity */
  63
  64   /* Methods implemented by the lower layer */
  65
  66   /** Free a channel */
  67   void (*free)(channel_t *);
  68   /** Close an open channel */
  69   void (*close)(channel_t *);
  70   /** Describe the transport subclass for this channel */
  71   const char * (*describe_transport)(channel_t *);
  72   /** Optional method to dump transport-specific statistics on the channel */
  73   void (*dumpstats)(channel_t *, int);
  74
  75   /** Registered handlers for incoming cells */
  76   channel_cell_handler_fn_ptr cell_handler;
  77   channel_var_cell_handler_fn_ptr var_cell_handler;
  78
  79   /* Methods implemented by the lower layer */
  80
  81   /**
  82    * Ask the underlying transport what the remote endpoint address is, in
  83    * a tor_addr_t.  This is optional and subclasses may leave this NULL.
  84    * If they implement it, they should write the address out to the
  85    * provided tor_addr_t *, and return 1 if successful or 0 if no address
  86    * available.
  87    */
  88   int (*get_remote_addr)(channel_t *, tor_addr_t *);
  89   int (*get_transport_name)(channel_t *chan, char **transport_out);
  90
  91 #define GRD_FLAG_ORIGINAL 1
  92 #define GRD_FLAG_ADDR_ONLY 2
  93   /**
  94    * Get a text description of the remote endpoint; canonicalized if the flag
  95    * GRD_FLAG_ORIGINAL is not set, or the one we originally connected
  96    * to/received from if it is.  If GRD_FLAG_ADDR_ONLY is set, we return only
  97    * the original address.
  98    */
  99   const char * (*get_remote_descr)(channel_t *, int);
 100   /** Check if the lower layer has queued writes */
 101   int (*has_queued_writes)(channel_t *);
 102   /**
 103    * If the second param is zero, ask the lower layer if this is
 104    * 'canonical', for a transport-specific definition of canonical; if
 105    * it is 1, ask if the answer to the preceding query is safe to rely
 106    * on.
 107    */
 108   int (*is_canonical)(channel_t *, int);
 109   /** Check if this channel matches a specified extend_info_t */
 110   int (*matches_extend_info)(channel_t *, extend_info_t *);
 111   /** Check if this channel matches a target address when extending */
 112   int (*matches_target)(channel_t *, const tor_addr_t *);
 113   /** Write a cell to an open channel */
 114   int (*write_cell)(channel_t *, cell_t *);
 115   /** Write a packed cell to an open channel */
 116   int (*write_packed_cell)(channel_t *, packed_cell_t *);
 117   /** Write a variable-length cell to an open channel */
 118   int (*write_var_cell)(channel_t *, var_cell_t *);
 119
 120   /**
 121    * Hash of the public RSA key for the other side's identity key, or
 122    * zeroes if the other side hasn't shown us a valid identity key.
 123    */
 124   char identity_digest[DIGEST_LEN];
 125   /** Nickname of the OR on the other side, or NULL if none. */
 126   char *nickname;
 127
 128   /**
 129    * Linked list of channels with the same identity digest, for the
 130    * digest->channel map
 131    */
 132   TOR_LIST_ENTRY(channel_s) next_with_same_id;
 133
 134   /** List of incoming cells to handle */
 135   chan_cell_queue_t incoming_queue;
 136
 137   /** List of queued outgoing cells */
 138   chan_cell_queue_t outgoing_queue;
 139
 140   /** Circuit mux for circuits sending on this channel */
 141   circuitmux_t *cmux;
 142
 143   /** Circuit ID generation stuff for use by circuitbuild.c */
 144
 145   /**
 146    * When we send CREATE cells along this connection, which half of the
 147    * space should we use?
 148    */
 149   circ_id_type_bitfield_t circ_id_type:2;
 150   /** DOCDOC*/
 151   unsigned wide_circ_ids:1;
 152
 153   /** For how many circuits are we n_chan?  What about p_chan? */
 154   unsigned int num_n_circuits, num_p_circuits;
 155
 156   /**
 157    * True iff this channel shouldn't get any new circs attached to it,
 158    * because the connection is too old, or because there's a better one.
 159    * More generally, this flag is used to note an unhealthy connection;
 160    * for example, if a bad connection fails we shouldn't assume that the
 161    * router itself has a problem.
 162    */
 163   unsigned int is_bad_for_new_circs:1;
 164
 165   /** True iff we have decided that the other end of this connection
 166    * is a client.  Channels with this flag set should never be used
 167    * to satisfy an EXTEND request.  */
 168   unsigned int is_client:1;
 169
 170   /** Set if the channel was initiated remotely (came from a listener) */
 171   unsigned int is_incoming:1;
 172
 173   /** Set by lower layer if this is local; i.e., everything it communicates
 174    * with for this channel returns true for is_local_addr().  This is used
 175    * to decide whether to declare reachability when we receive something on
 176    * this channel in circuitbuild.c
 177    */
 178   unsigned int is_local:1;
 179
 180   /** Have we logged a warning about circID exhaustion on this channel?
 181    * If so, when? */
 182   ratelim_t last_warned_circ_ids_exhausted;
 183
 184   /** Channel timestamps for cell channels */
 185   time_t timestamp_client; /* Client used this, according to relay.c */
 186   time_t timestamp_drained; /* Output queue empty */
 187   time_t timestamp_recv; /* Cell received from lower layer */
 188   time_t timestamp_xmit; /* Cell sent to lower layer */
 189
 190   /** Timestamp for run_connection_housekeeping(). We update this once a
 191    * second when we run housekeeping and find a circuit on this channel, and
 192    * whenever we add a circuit to the channel. */
 193   time_t timestamp_last_had_circuits;
 194
 195   /** Unique ID for measuring direct network status requests;vtunneled ones
 196    * come over a circuit_t, which has a dirreq_id field as well, but is a
 197    * distinct namespace. */
 198   uint64_t dirreq_id;
 199
 200   /** Channel counters for cell channels */
 201   uint64_t n_cells_recved;
 202   uint64_t n_cells_xmitted;
 203 };
 204
 205 struct channel_listener_s {
 206   /* Current channel listener state */
 207   channel_listener_state_t state;
 208
 209   /* Globally unique ID number for a channel over the lifetime of a Tor
 210    * process.
 211    */
 212   uint64_t global_identifier;
 213
 214   /** Should we expect to see this channel in the channel lists? */
 215   unsigned char registered:1;
 216
 217   /** Why did we close?
 218    */
 219   enum {
 220     CHANNEL_LISTENER_NOT_CLOSING = 0,
 221     CHANNEL_LISTENER_CLOSE_REQUESTED,
 222     CHANNEL_LISTENER_CLOSE_FROM_BELOW,
 223     CHANNEL_LISTENER_CLOSE_FOR_ERROR
 224   } reason_for_closing;
 225
 226   /** Timestamps for both cell channels and listeners */
 227   time_t timestamp_created; /* Channel created */
 228   time_t timestamp_active; /* Any activity */
 229
 230   /* Methods implemented by the lower layer */
 231
 232   /** Free a channel */
 233   void (*free)(channel_listener_t *);
 234   /** Close an open channel */
 235   void (*close)(channel_listener_t *);
 236   /** Describe the transport subclass for this channel */
 237   const char * (*describe_transport)(channel_listener_t *);
 238   /** Optional method to dump transport-specific statistics on the channel */
 239   void (*dumpstats)(channel_listener_t *, int);
 240
 241   /** Registered listen handler to call on incoming connection */
 242   channel_listener_fn_ptr listener;
 243
 244   /** List of pending incoming connections */
 245   smartlist_t *incoming_list;
 246
 247   /** Timestamps for listeners */
 248   time_t timestamp_accepted;
 249
 250   /** Counters for listeners */
 251   uint64_t n_accepted;
 252 };
 253
 254 /* Channel state manipulations */
 255
 256 int channel_state_is_valid(channel_state_t state);
 257 int channel_listener_state_is_valid(channel_listener_state_t state);
 258
 259 int channel_state_can_transition(channel_state_t from, channel_state_t to);
 260 int channel_listener_state_can_transition(channel_listener_state_t from,
 261                                           channel_listener_state_t to);
 262
 263 const char * channel_state_to_string(channel_state_t state);
 264 const char *
 265 channel_listener_state_to_string(channel_listener_state_t state);
 266
 267 /* Abstract channel operations */
 268
 269 void channel_mark_for_close(channel_t *chan);
 270 void channel_write_cell(channel_t *chan, cell_t *cell);
 271 void channel_write_packed_cell(channel_t *chan, packed_cell_t *cell);
 272 void channel_write_var_cell(channel_t *chan, var_cell_t *cell);
 273
 274 void channel_listener_mark_for_close(channel_listener_t *chan_l);
 275
 276 /* Channel callback registrations */
 277
 278 /* Listener callback */
 279 channel_listener_fn_ptr
 280 channel_listener_get_listener_fn(channel_listener_t *chan);
 281
 282 void channel_listener_set_listener_fn(channel_listener_t *chan,
 283                                       channel_listener_fn_ptr listener);
 284
 285 /* Incoming cell callbacks */
 286 channel_cell_handler_fn_ptr channel_get_cell_handler(channel_t *chan);
 287
 288 channel_var_cell_handler_fn_ptr
 289 channel_get_var_cell_handler(channel_t *chan);
 290
 291 void channel_set_cell_handlers(channel_t *chan,
 292                                channel_cell_handler_fn_ptr cell_handler,
 293                                channel_var_cell_handler_fn_ptr
 294                                  var_cell_handler);
 295
 296 /* Clean up closed channels and channel listeners periodically; these are
 297  * called from run_scheduled_events() in main.c.
 298  */
 299 void channel_run_cleanup(void);
 300 void channel_listener_run_cleanup(void);
 301
 302 /* Close all channels and deallocate everything */
 303 void channel_free_all(void);
 304
 305 /* Dump some statistics in the log */
 306 void channel_dumpstats(int severity);
 307 void channel_listener_dumpstats(int severity);
 308
 309 /* Set the cmux policy on all active channels */
 310 void channel_set_cmux_policy_everywhere(circuitmux_policy_t *pol);
 311
 312 #ifdef TOR_CHANNEL_INTERNAL_
 313
 314 /* Channel operations for subclasses and internal use only */
 315
 316 /* Initialize a newly allocated channel - do this first in subclass
 317  * constructors.
 318  */
 319
 320 void channel_init(channel_t *chan);
 321 void channel_init_listener(channel_listener_t *chan);
 322
 323 /* Channel registration/unregistration */
 324 void channel_register(channel_t *chan);
 325 void channel_unregister(channel_t *chan);
 326
 327 /* Channel listener registration/unregistration */
 328 void channel_listener_register(channel_listener_t *chan_l);
 329 void channel_listener_unregister(channel_listener_t *chan_l);
 330
 331 /* Close from below */
 332 void channel_close_from_lower_layer(channel_t *chan);
 333 void channel_close_for_error(channel_t *chan);
 334 void channel_closed(channel_t *chan);
 335
 336 void channel_listener_close_from_lower_layer(channel_listener_t *chan_l);
 337 void channel_listener_close_for_error(channel_listener_t *chan_l);
 338 void channel_listener_closed(channel_listener_t *chan_l);
 339
 340 /* Free a channel */
 341 void channel_free(channel_t *chan);
 342 void channel_listener_free(channel_listener_t *chan_l);
 343
 344 /* State/metadata setters */
 345
 346 void channel_change_state(channel_t *chan, channel_state_t to_state);
 347 void channel_clear_identity_digest(channel_t *chan);
 348 void channel_clear_remote_end(channel_t *chan);
 349 void channel_mark_local(channel_t *chan);
 350 void channel_mark_incoming(channel_t *chan);
 351 void channel_mark_outgoing(channel_t *chan);
 352 void channel_mark_remote(channel_t *chan);
 353 void channel_set_identity_digest(channel_t *chan,
 354                                  const char *identity_digest);
 355 void channel_set_remote_end(channel_t *chan,
 356                             const char *identity_digest,
 357                             const char *nickname);
 358
 359 void channel_listener_change_state(channel_listener_t *chan_l,
 360                                    channel_listener_state_t to_state);
 361
 362 /* Timestamp updates */
 363 void channel_timestamp_created(channel_t *chan);
 364 void channel_timestamp_active(channel_t *chan);
 365 void channel_timestamp_drained(channel_t *chan);
 366 void channel_timestamp_recv(channel_t *chan);
 367 void channel_timestamp_xmit(channel_t *chan);
 368
 369 void channel_listener_timestamp_created(channel_listener_t *chan_l);
 370 void channel_listener_timestamp_active(channel_listener_t *chan_l);
 371 void channel_listener_timestamp_accepted(channel_listener_t *chan_l);
 372
 373 /* Incoming channel handling */
 374 void channel_listener_process_incoming(channel_listener_t *listener);
 375 void channel_listener_queue_incoming(channel_listener_t *listener,
 376                                      channel_t *incoming);
 377
 378 /* Incoming cell handling */
 379 void channel_process_cells(channel_t *chan);
 380 void channel_queue_cell(channel_t *chan, cell_t *cell);
 381 void channel_queue_var_cell(channel_t *chan, var_cell_t *var_cell);
 382
 383 /* Outgoing cell handling */
 384 void channel_flush_cells(channel_t *chan);
 385
 386 /* Request from lower layer for more cells if available */
 387 ssize_t channel_flush_some_cells(channel_t *chan, ssize_t num_cells);
 388
 389 /* Query if data available on this channel */
 390 int channel_more_to_flush(channel_t *chan);
 391
 392 /* Notify flushed outgoing for dirreq handling */
 393 void channel_notify_flushed(channel_t *chan);
 394
 395 /* Handle stuff we need to do on open like notifying circuits */
 396 void channel_do_open_actions(channel_t *chan);
 397
 398 #endif
 399
 400 /* Helper functions to perform operations on channels */
 401
 402 int channel_send_destroy(circid_t circ_id, channel_t *chan,
 403                          int reason);
 404
 405 /*
 406  * Outside abstract interfaces that should eventually get turned into
 407  * something transport/address format independent.
 408  */
 409
 410 channel_t * channel_connect(const tor_addr_t *addr, uint16_t port,
 411                             const char *id_digest);
 412
 413 channel_t * channel_get_for_extend(const char *digest,
 414                                    const tor_addr_t *target_addr,
 415                                    const char **msg_out,
 416                                    int *launch_out);
 417
 418 /* Ask which of two channels is better for circuit-extension purposes */
 419 int channel_is_better(time_t now,
 420                       channel_t *a, channel_t *b,
 421                       int forgive_new_connections);
 422
 423 /** Channel lookups
 424  */
 425
 426 channel_t * channel_find_by_global_id(uint64_t global_identifier);
 427 channel_t * channel_find_by_remote_digest(const char *identity_digest);
 428
 429 /** For things returned by channel_find_by_remote_digest(), walk the list.
 430  */
 431 channel_t * channel_next_with_digest(channel_t *chan);
 432
 433 /*
 434  * Metadata queries/updates
 435  */
 436
 437 const char * channel_describe_transport(channel_t *chan);
 438 void channel_dump_statistics(channel_t *chan, int severity);
 439 void channel_dump_transport_statistics(channel_t *chan, int severity);
 440 const char * channel_get_actual_remote_descr(channel_t *chan);
 441 const char * channel_get_actual_remote_address(channel_t *chan);
 442 int channel_get_addr_if_possible(channel_t *chan, tor_addr_t *addr_out);
 443 const char * channel_get_canonical_remote_descr(channel_t *chan);
 444 int channel_has_queued_writes(channel_t *chan);
 445 int channel_is_bad_for_new_circs(channel_t *chan);
 446 void channel_mark_bad_for_new_circs(channel_t *chan);
 447 int channel_is_canonical(channel_t *chan);
 448 int channel_is_canonical_is_reliable(channel_t *chan);
 449 int channel_is_client(channel_t *chan);
 450 int channel_is_local(channel_t *chan);
 451 int channel_is_incoming(channel_t *chan);
 452 int channel_is_outgoing(channel_t *chan);
 453 void channel_mark_client(channel_t *chan);
 454 int channel_matches_extend_info(channel_t *chan, extend_info_t *extend_info);
 455 int channel_matches_target_addr_for_extend(channel_t *chan,
 456                                            const tor_addr_t *target);
 457 unsigned int channel_num_circuits(channel_t *chan);
 458 void channel_set_circid_type(channel_t *chan, crypto_pk_t *identity_rcvd,
 459                              int consider_identity);
 460 void channel_timestamp_client(channel_t *chan);
 461
 462 const char * channel_listener_describe_transport(channel_listener_t *chan_l);
 463 void channel_listener_dump_statistics(channel_listener_t *chan_l,
 464                                       int severity);
 465 void channel_listener_dump_transport_statistics(channel_listener_t *chan_l,
 466                                                 int severity);
 467
 468 /* Timestamp queries */
 469 time_t channel_when_created(channel_t *chan);
 470 time_t channel_when_last_active(channel_t *chan);
 471 time_t channel_when_last_client(channel_t *chan);
 472 time_t channel_when_last_drained(channel_t *chan);
 473 time_t channel_when_last_recv(channel_t *chan);
 474 time_t channel_when_last_xmit(channel_t *chan);
 475
 476 time_t channel_listener_when_created(channel_listener_t *chan_l);
 477 time_t channel_listener_when_last_active(channel_listener_t *chan_l);
 478 time_t channel_listener_when_last_accepted(channel_listener_t *chan_l);
 479
 480 /* Counter queries */
 481 uint64_t channel_count_recved(channel_t *chan);
 482 uint64_t channel_count_xmitted(channel_t *chan);
 483
 484 uint64_t channel_listener_count_accepted(channel_listener_t *chan_l);
 485
 486 int packed_cell_is_destroy(channel_t *chan,
 487                            const packed_cell_t *packed_cell,
 488                            circid_t *circid_out);
 489
 490 #endif
 491