src/core/or/channel.h

   1 /* * Copyright (c) 2012-2019, 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 "core/or/or.h"
  13 #include "core/or/circuitmux.h"
  14 #include "lib/container/handles.h"
  15 #include "lib/crypt_ops/crypto_ed25519.h"
  16
  17 #include "tor_queue.h"
  18
  19 #define tor_timer_t timeout
  20 struct tor_timer_t;
  21
  22 /* Channel handler function pointer typedefs */
  23 typedef void (*channel_listener_fn_ptr)(channel_listener_t *, channel_t *);
  24 typedef void (*channel_cell_handler_fn_ptr)(channel_t *, cell_t *);
  25 typedef void (*channel_var_cell_handler_fn_ptr)(channel_t *, var_cell_t *);
  26
  27 /**
  28  * This enum is used by channelpadding to decide when to pad channels.
  29  * Don't add values to it without updating the checks in
  30  * channelpadding_decide_to_pad_channel().
  31  */
  32 typedef enum {
  33     CHANNEL_USED_NOT_USED_FOR_FULL_CIRCS = 0,
  34     CHANNEL_USED_FOR_FULL_CIRCS,
  35     CHANNEL_USED_FOR_USER_TRAFFIC,
  36 } channel_usage_info_t;
  37
  38 /** Possible rules for generating circuit IDs on an OR connection. */
  39 typedef enum {
  40   CIRC_ID_TYPE_LOWER=0, /**< Pick from 0..1<<15-1. */
  41   CIRC_ID_TYPE_HIGHER=1, /**< Pick from 1<<15..1<<16-1. */
  42   /** The other side of a connection is an OP: never create circuits to it,
  43    * and let it use any circuit ID it wants. */
  44   CIRC_ID_TYPE_NEITHER=2
  45 } circ_id_type_t;
  46 #define circ_id_type_bitfield_t ENUM_BF(circ_id_type_t)
  47
  48 /* channel states for channel_t */
  49
  50 typedef enum {
  51   /*
  52    * Closed state - channel is inactive
  53    *
  54    * Permitted transitions from:
  55    *   - CHANNEL_STATE_CLOSING
  56    * Permitted transitions to:
  57    *   - CHANNEL_STATE_OPENING
  58    */
  59   CHANNEL_STATE_CLOSED = 0,
  60   /*
  61    * Opening state - channel is trying to connect
  62    *
  63    * Permitted transitions from:
  64    *   - CHANNEL_STATE_CLOSED
  65    * Permitted transitions to:
  66    *   - CHANNEL_STATE_CLOSING
  67    *   - CHANNEL_STATE_ERROR
  68    *   - CHANNEL_STATE_OPEN
  69    */
  70   CHANNEL_STATE_OPENING,
  71   /*
  72    * Open state - channel is active and ready for use
  73    *
  74    * Permitted transitions from:
  75    *   - CHANNEL_STATE_MAINT
  76    *   - CHANNEL_STATE_OPENING
  77    * Permitted transitions to:
  78    *   - CHANNEL_STATE_CLOSING
  79    *   - CHANNEL_STATE_ERROR
  80    *   - CHANNEL_STATE_MAINT
  81    */
  82   CHANNEL_STATE_OPEN,
  83   /*
  84    * Maintenance state - channel is temporarily offline for subclass specific
  85    *   maintenance activities such as TLS renegotiation.
  86    *
  87    * Permitted transitions from:
  88    *   - CHANNEL_STATE_OPEN
  89    * Permitted transitions to:
  90    *   - CHANNEL_STATE_CLOSING
  91    *   - CHANNEL_STATE_ERROR
  92    *   - CHANNEL_STATE_OPEN
  93    */
  94   CHANNEL_STATE_MAINT,
  95   /*
  96    * Closing state - channel is shutting down
  97    *
  98    * Permitted transitions from:
  99    *   - CHANNEL_STATE_MAINT
 100    *   - CHANNEL_STATE_OPEN
 101    * Permitted transitions to:
 102    *   - CHANNEL_STATE_CLOSED,
 103    *   - CHANNEL_STATE_ERROR
 104    */
 105   CHANNEL_STATE_CLOSING,
 106   /*
 107    * Error state - channel has experienced a permanent error
 108    *
 109    * Permitted transitions from:
 110    *   - CHANNEL_STATE_CLOSING
 111    *   - CHANNEL_STATE_MAINT
 112    *   - CHANNEL_STATE_OPENING
 113    *   - CHANNEL_STATE_OPEN
 114    * Permitted transitions to:
 115    *   - None
 116    */
 117   CHANNEL_STATE_ERROR,
 118   /*
 119    * Placeholder for maximum state value
 120    */
 121   CHANNEL_STATE_LAST
 122 } channel_state_t;
 123
 124 /* channel listener states for channel_listener_t */
 125
 126 typedef enum {
 127   /*
 128    * Closed state - channel listener is inactive
 129    *
 130    * Permitted transitions from:
 131    *   - CHANNEL_LISTENER_STATE_CLOSING
 132    * Permitted transitions to:
 133    *   - CHANNEL_LISTENER_STATE_LISTENING
 134    */
 135   CHANNEL_LISTENER_STATE_CLOSED = 0,
 136   /*
 137    * Listening state - channel listener is listening for incoming
 138    * connections
 139    *
 140    * Permitted transitions from:
 141    *   - CHANNEL_LISTENER_STATE_CLOSED
 142    * Permitted transitions to:
 143    *   - CHANNEL_LISTENER_STATE_CLOSING
 144    *   - CHANNEL_LISTENER_STATE_ERROR
 145    */
 146   CHANNEL_LISTENER_STATE_LISTENING,
 147   /*
 148    * Closing state - channel listener is shutting down
 149    *
 150    * Permitted transitions from:
 151    *   - CHANNEL_LISTENER_STATE_LISTENING
 152    * Permitted transitions to:
 153    *   - CHANNEL_LISTENER_STATE_CLOSED,
 154    *   - CHANNEL_LISTENER_STATE_ERROR
 155    */
 156   CHANNEL_LISTENER_STATE_CLOSING,
 157   /*
 158    * Error state - channel listener has experienced a permanent error
 159    *
 160    * Permitted transitions from:
 161    *   - CHANNEL_STATE_CLOSING
 162    *   - CHANNEL_STATE_LISTENING
 163    * Permitted transitions to:
 164    *   - None
 165    */
 166   CHANNEL_LISTENER_STATE_ERROR,
 167   /*
 168    * Placeholder for maximum state value
 169    */
 170   CHANNEL_LISTENER_STATE_LAST
 171 } channel_listener_state_t;
 172
 173 /**
 174  * Channel struct; see the channel_t typedef in or.h.  A channel is an
 175  * abstract interface for the OR-to-OR connection, similar to connection_or_t,
 176  * but without the strong coupling to the underlying TLS implementation.  They
 177  * are constructed by calling a protocol-specific function to open a channel
 178  * to a particular node, and once constructed support the abstract operations
 179  * defined below.
 180  */
 181 struct channel_s {
 182   /** Magic number for type-checking cast macros */
 183   uint32_t magic;
 184
 185   /** List entry for hashtable for global-identifier lookup. */
 186   HT_ENTRY(channel_s) gidmap_node;
 187
 188   /** Handle entry for handle-based lookup */
 189   HANDLE_ENTRY(channel, channel_s);
 190
 191   /** Current channel state */
 192   channel_state_t state;
 193
 194   /** Globally unique ID number for a channel over the lifetime of a Tor
 195    * process.  This may not be 0.
 196    */
 197   uint64_t global_identifier;
 198
 199   /** Should we expect to see this channel in the channel lists? */
 200   unsigned char registered:1;
 201
 202   /** has this channel ever been open? */
 203   unsigned int has_been_open:1;
 204
 205   /**
 206    * This field indicates if the other side has enabled or disabled
 207    * padding via either the link protocol version or
 208    * channelpadding_negotiate cells.
 209    *
 210    * Clients can override this with ConnectionPadding in torrc to
 211    * disable or force padding to relays, but relays cannot override the
 212    * client's request.
 213    */
 214   unsigned int padding_enabled:1;
 215
 216   /** Cached value of our decision to pad (to avoid expensive
 217    * checks during critical path statistics counting). */
 218   unsigned int currently_padding:1;
 219
 220   /** Is there a pending netflow padding callback? */
 221   unsigned int pending_padding_callback:1;
 222
 223   /** Is our peer likely to consider this channel canonical? */
 224   unsigned int is_canonical_to_peer:1;
 225
 226   /** Has this channel ever been used for non-directory traffic?
 227    * Used to decide what channels to pad, and when. */
 228   channel_usage_info_t channel_usage;
 229
 230   /** When should we send a cell for netflow padding? 0 means no padding is
 231    *  scheduled. */
 232   monotime_coarse_t next_padding_time;
 233
 234   /** The callback pointer for the padding callbacks */
 235   struct tor_timer_t *padding_timer;
 236   /** The handle to this channel (to free on canceled timers) */
 237   struct channel_handle_t *timer_handle;
 238
 239   /**
 240    * These two fields specify the minimum and maximum negotiated timeout
 241    * values for inactivity (send or receive) before we decide to pad a
 242    * channel. These fields can be set either via a PADDING_NEGOTIATE cell,
 243    * or the torrc option ReducedConnectionPadding. The consensus parameters
 244    * nf_ito_low and nf_ito_high are used to ensure that padding can only be
 245    * negotiated to be less frequent than what is specified in the consensus.
 246    * (This is done to prevent wingnut clients from requesting excessive
 247    * padding).
 248    *
 249    * The actual timeout value is randomly chosen between these two values
 250    * as per the table in channelpadding_get_netflow_inactive_timeout_ms(),
 251    * after ensuring that these values do not specify lower timeouts than
 252    * the consensus parameters.
 253    *
 254    * If these are 0, we have not negotiated or specified custom padding
 255    * times, and instead use consensus defaults. */
 256   uint16_t padding_timeout_low_ms;
 257   uint16_t padding_timeout_high_ms;
 258
 259   /** Why did we close?
 260    */
 261   enum {
 262     CHANNEL_NOT_CLOSING = 0,
 263     CHANNEL_CLOSE_REQUESTED,
 264     CHANNEL_CLOSE_FROM_BELOW,
 265     CHANNEL_CLOSE_FOR_ERROR
 266   } reason_for_closing;
 267
 268   /** State variable for use by the scheduler */
 269   enum {
 270     /*
 271      * The channel is not open, or it has a full output buffer but no queued
 272      * cells.
 273      */
 274     SCHED_CHAN_IDLE = 0,
 275     /*
 276      * The channel has space on its output buffer to write, but no queued
 277      * cells.
 278      */
 279     SCHED_CHAN_WAITING_FOR_CELLS,
 280     /*
 281      * The scheduler has queued cells but no output buffer space to write.
 282      */
 283     SCHED_CHAN_WAITING_TO_WRITE,
 284     /*
 285      * The scheduler has both queued cells and output buffer space, and is
 286      * eligible for the scheduler loop.
 287      */
 288     SCHED_CHAN_PENDING
 289   } scheduler_state;
 290
 291   /** Heap index for use by the scheduler */
 292   int sched_heap_idx;
 293
 294   /** Timestamps for both cell channels and listeners */
 295   time_t timestamp_created; /* Channel created */
 296   time_t timestamp_active; /* Any activity */
 297
 298   /**
 299    * This is a monotonic timestamp that marks when we
 300    * believe the channel has actually sent or received data to/from
 301    * the wire. Right now, it is used to determine when we should send
 302    * a padding cell for channelpadding.
 303    *
 304    * XXX: Are we setting timestamp_xfer_ms in the right places to
 305    * accurately reflect actual network data transfer? Or might this be
 306    * very wrong wrt when bytes actually go on the wire?
 307    */
 308   monotime_coarse_t timestamp_xfer;
 309
 310   /* Methods implemented by the lower layer */
 311
 312   /** Free a channel */
 313   void (*free_fn)(channel_t *);
 314   /** Close an open channel */
 315   void (*close)(channel_t *);
 316   /** Describe the transport subclass for this channel */
 317   const char * (*describe_transport)(channel_t *);
 318   /** Optional method to dump transport-specific statistics on the channel */
 319   void (*dumpstats)(channel_t *, int);
 320
 321   /** Registered handlers for incoming cells */
 322   channel_cell_handler_fn_ptr cell_handler;
 323   channel_var_cell_handler_fn_ptr var_cell_handler;
 324
 325   /* Methods implemented by the lower layer */
 326
 327   /**
 328    * Ask the lower layer for an estimate of the average overhead for
 329    * transmissions on this channel.
 330    */
 331   double (*get_overhead_estimate)(channel_t *);
 332   /*
 333    * Ask the underlying transport what the remote endpoint address is, in
 334    * a tor_addr_t.  This is optional and subclasses may leave this NULL.
 335    * If they implement it, they should write the address out to the
 336    * provided tor_addr_t *, and return 1 if successful or 0 if no address
 337    * available.
 338    */
 339   int (*get_remote_addr)(channel_t *, tor_addr_t *);
 340   int (*get_transport_name)(channel_t *chan, char **transport_out);
 341
 342 #define GRD_FLAG_ORIGINAL 1
 343 #define GRD_FLAG_ADDR_ONLY 2
 344   /**
 345    * Get a text description of the remote endpoint; canonicalized if the flag
 346    * GRD_FLAG_ORIGINAL is not set, or the one we originally connected
 347    * to/received from if it is.  If GRD_FLAG_ADDR_ONLY is set, we return only
 348    * the original address.
 349    */
 350   const char * (*get_remote_descr)(channel_t *, int);
 351   /** Check if the lower layer has queued writes */
 352   int (*has_queued_writes)(channel_t *);
 353   /**
 354    * If the second param is zero, ask the lower layer if this is
 355    * 'canonical', for a transport-specific definition of canonical; if
 356    * it is 1, ask if the answer to the preceding query is safe to rely
 357    * on.
 358    */
 359   int (*is_canonical)(channel_t *, int);
 360   /** Check if this channel matches a specified extend_info_t */
 361   int (*matches_extend_info)(channel_t *, extend_info_t *);
 362   /** Check if this channel matches a target address when extending */
 363   int (*matches_target)(channel_t *, const tor_addr_t *);
 364   /* Ask the lower layer how many bytes it has queued but not yet sent */
 365   size_t (*num_bytes_queued)(channel_t *);
 366   /* Ask the lower layer how many cells can be written */
 367   int (*num_cells_writeable)(channel_t *);
 368   /* Write a cell to an open channel */
 369   int (*write_cell)(channel_t *, cell_t *);
 370   /** Write a packed cell to an open channel */
 371   int (*write_packed_cell)(channel_t *, packed_cell_t *);
 372   /** Write a variable-length cell to an open channel */
 373   int (*write_var_cell)(channel_t *, var_cell_t *);
 374
 375   /**
 376    * Hash of the public RSA key for the other side's RSA identity key -- or
 377    * zeroes if we don't have an RSA identity in mind for the other side, and
 378    * it hasn't shown us one.
 379    *
 380    * Note that this is the RSA identity that we hope the other side has -- not
 381    * necessarily its true identity.  Don't believe this identity unless
 382    * authentication has happened.
 383    */
 384   char identity_digest[DIGEST_LEN];
 385   /**
 386    * Ed25519 key for the other side of this channel -- or zeroes if we don't
 387    * have an Ed25519 identity in mind for the other side, and it hasn't shown
 388    * us one.
 389    *
 390    * Note that this is the identity that we hope the other side has -- not
 391    * necessarily its true identity.  Don't believe this identity unless
 392    * authentication has happened.
 393    */
 394   struct ed25519_public_key_t ed25519_identity;
 395
 396   /**
 397    * Linked list of channels with the same RSA identity digest, for use with
 398    * the digest->channel map
 399    */
 400   TOR_LIST_ENTRY(channel_s) next_with_same_id;
 401
 402   /** Circuit mux for circuits sending on this channel */
 403   circuitmux_t *cmux;
 404
 405   /** Circuit ID generation stuff for use by circuitbuild.c */
 406
 407   /**
 408    * When we send CREATE cells along this connection, which half of the
 409    * space should we use?
 410    */
 411   circ_id_type_bitfield_t circ_id_type:2;
 412   /* DOCDOC */
 413   unsigned wide_circ_ids:1;
 414
 415   /** For how many circuits are we n_chan?  What about p_chan? */
 416   unsigned int num_n_circuits, num_p_circuits;
 417
 418   /**
 419    * True iff this channel shouldn't get any new circs attached to it,
 420    * because the connection is too old, or because there's a better one.
 421    * More generally, this flag is used to note an unhealthy connection;
 422    * for example, if a bad connection fails we shouldn't assume that the
 423    * router itself has a problem.
 424    */
 425   unsigned int is_bad_for_new_circs:1;
 426
 427   /** True iff we have decided that the other end of this connection
 428    * is a client or bridge relay.  Connections with this flag set should never
 429    * be used to satisfy an EXTEND request. */
 430   unsigned int is_client:1;
 431
 432   /** Set if the channel was initiated remotely (came from a listener) */
 433   unsigned int is_incoming:1;
 434
 435   /** Set by lower layer if this is local; i.e., everything it communicates
 436    * with for this channel returns true for is_local_addr().  This is used
 437    * to decide whether to declare reachability when we receive something on
 438    * this channel in circuitbuild.c
 439    */
 440   unsigned int is_local:1;
 441
 442   /** Have we logged a warning about circID exhaustion on this channel?
 443    * If so, when? */
 444   ratelim_t last_warned_circ_ids_exhausted;
 445
 446   /** Channel timestamps for cell channels */
 447   time_t timestamp_client; /* Client used this, according to relay.c */
 448   time_t timestamp_recv; /* Cell received from lower layer */
 449   time_t timestamp_xmit; /* Cell sent to lower layer */
 450
 451   /** Timestamp for run_connection_housekeeping(). We update this once a
 452    * second when we run housekeeping and find a circuit on this channel, and
 453    * whenever we add a circuit to the channel. */
 454   time_t timestamp_last_had_circuits;
 455
 456   /** Unique ID for measuring direct network status requests;vtunneled ones
 457    * come over a circuit_t, which has a dirreq_id field as well, but is a
 458    * distinct namespace. */
 459   uint64_t dirreq_id;
 460
 461   /** Channel counters for cell channels */
 462   uint64_t n_cells_recved, n_bytes_recved;
 463   uint64_t n_cells_xmitted, n_bytes_xmitted;
 464 };
 465
 466 struct channel_listener_s {
 467   /* Current channel listener state */
 468   channel_listener_state_t state;
 469
 470   /* Globally unique ID number for a channel over the lifetime of a Tor
 471    * process.
 472    */
 473   uint64_t global_identifier;
 474
 475   /** Should we expect to see this channel in the channel lists? */
 476   unsigned char registered:1;
 477
 478   /** Why did we close?
 479    */
 480   enum {
 481     CHANNEL_LISTENER_NOT_CLOSING = 0,
 482     CHANNEL_LISTENER_CLOSE_REQUESTED,
 483     CHANNEL_LISTENER_CLOSE_FROM_BELOW,
 484     CHANNEL_LISTENER_CLOSE_FOR_ERROR
 485   } reason_for_closing;
 486
 487   /** Timestamps for both cell channels and listeners */
 488   time_t timestamp_created; /* Channel created */
 489   time_t timestamp_active; /* Any activity */
 490
 491   /* Methods implemented by the lower layer */
 492
 493   /** Free a channel */
 494   void (*free_fn)(channel_listener_t *);
 495   /** Close an open channel */
 496   void (*close)(channel_listener_t *);
 497   /** Describe the transport subclass for this channel */
 498   const char * (*describe_transport)(channel_listener_t *);
 499   /** Optional method to dump transport-specific statistics on the channel */
 500   void (*dumpstats)(channel_listener_t *, int);
 501
 502   /** Registered listen handler to call on incoming connection */
 503   channel_listener_fn_ptr listener;
 504
 505   /** List of pending incoming connections */
 506   smartlist_t *incoming_list;
 507
 508   /** Timestamps for listeners */
 509   time_t timestamp_accepted;
 510
 511   /** Counters for listeners */
 512   uint64_t n_accepted;
 513 };
 514
 515 /* Channel state manipulations */
 516
 517 int channel_state_is_valid(channel_state_t state);
 518 int channel_listener_state_is_valid(channel_listener_state_t state);
 519
 520 int channel_state_can_transition(channel_state_t from, channel_state_t to);
 521 int channel_listener_state_can_transition(channel_listener_state_t from,
 522                                           channel_listener_state_t to);
 523
 524 const char * channel_state_to_string(channel_state_t state);
 525 const char *
 526 channel_listener_state_to_string(channel_listener_state_t state);
 527
 528 /* Abstract channel operations */
 529
 530 void channel_mark_for_close(channel_t *chan);
 531 int channel_write_packed_cell(channel_t *chan, packed_cell_t *cell);
 532
 533 void channel_listener_mark_for_close(channel_listener_t *chan_l);
 534
 535 /* Channel callback registrations */
 536
 537 /* Listener callback */
 538 void channel_listener_set_listener_fn(channel_listener_t *chan,
 539                                       channel_listener_fn_ptr listener);
 540
 541 /* Incoming cell callbacks */
 542 channel_cell_handler_fn_ptr channel_get_cell_handler(channel_t *chan);
 543
 544 channel_var_cell_handler_fn_ptr
 545 channel_get_var_cell_handler(channel_t *chan);
 546
 547 void channel_set_cell_handlers(channel_t *chan,
 548                                channel_cell_handler_fn_ptr cell_handler,
 549                                channel_var_cell_handler_fn_ptr
 550                                  var_cell_handler);
 551
 552 /* Clean up closed channels and channel listeners periodically; these are
 553  * called from run_scheduled_events() in main.c.
 554  */
 555 void channel_run_cleanup(void);
 556 void channel_listener_run_cleanup(void);
 557
 558 /* Close all channels and deallocate everything */
 559 void channel_free_all(void);
 560
 561 /* Dump some statistics in the log */
 562 void channel_dumpstats(int severity);
 563 void channel_listener_dumpstats(int severity);
 564
 565 #ifdef TOR_CHANNEL_INTERNAL_
 566
 567 #ifdef CHANNEL_PRIVATE_
 568
 569 STATIC void channel_add_to_digest_map(channel_t *chan);
 570
 571 #endif /* defined(CHANNEL_PRIVATE_) */
 572
 573 /* Channel operations for subclasses and internal use only */
 574
 575 /* Initialize a newly allocated channel - do this first in subclass
 576  * constructors.
 577  */
 578
 579 void channel_init(channel_t *chan);
 580 void channel_init_listener(channel_listener_t *chan);
 581
 582 /* Channel registration/unregistration */
 583 void channel_register(channel_t *chan);
 584 void channel_unregister(channel_t *chan);
 585
 586 /* Channel listener registration/unregistration */
 587 void channel_listener_register(channel_listener_t *chan_l);
 588 void channel_listener_unregister(channel_listener_t *chan_l);
 589
 590 /* Close from below */
 591 void channel_close_from_lower_layer(channel_t *chan);
 592 void channel_close_for_error(channel_t *chan);
 593 void channel_closed(channel_t *chan);
 594
 595 /* Free a channel */
 596 void channel_free_(channel_t *chan);
 597 #define channel_free(chan) FREE_AND_NULL(channel_t, channel_free_, (chan))
 598 void channel_listener_free_(channel_listener_t *chan_l);
 599 #define channel_listener_free(chan_l) \
 600   FREE_AND_NULL(channel_listener_t, channel_listener_free_, (chan_l))
 601
 602 /* State/metadata setters */
 603
 604 void channel_change_state(channel_t *chan, channel_state_t to_state);
 605 void channel_change_state_open(channel_t *chan);
 606 void channel_clear_identity_digest(channel_t *chan);
 607 void channel_clear_remote_end(channel_t *chan);
 608 void channel_mark_local(channel_t *chan);
 609 void channel_mark_incoming(channel_t *chan);
 610 void channel_mark_outgoing(channel_t *chan);
 611 void channel_mark_remote(channel_t *chan);
 612 void channel_set_identity_digest(channel_t *chan,
 613                              const char *identity_digest,
 614                              const struct ed25519_public_key_t *ed_identity);
 615
 616 void channel_listener_change_state(channel_listener_t *chan_l,
 617                                    channel_listener_state_t to_state);
 618
 619 /* Timestamp updates */
 620 void channel_timestamp_created(channel_t *chan);
 621 void channel_timestamp_active(channel_t *chan);
 622 void channel_timestamp_recv(channel_t *chan);
 623 void channel_timestamp_xmit(channel_t *chan);
 624
 625 void channel_listener_timestamp_created(channel_listener_t *chan_l);
 626 void channel_listener_timestamp_active(channel_listener_t *chan_l);
 627 void channel_listener_timestamp_accepted(channel_listener_t *chan_l);
 628
 629 /* Incoming channel handling */
 630 void channel_listener_process_incoming(channel_listener_t *listener);
 631 void channel_listener_queue_incoming(channel_listener_t *listener,
 632                                      channel_t *incoming);
 633
 634 /* Incoming cell handling */
 635 void channel_process_cell(channel_t *chan, cell_t *cell);
 636
 637 /* Request from lower layer for more cells if available */
 638 MOCK_DECL(ssize_t, channel_flush_some_cells,
 639           (channel_t *chan, ssize_t num_cells));
 640
 641 /* Query if data available on this channel */
 642 MOCK_DECL(int, channel_more_to_flush, (channel_t *chan));
 643
 644 /* Notify flushed outgoing for dirreq handling */
 645 void channel_notify_flushed(channel_t *chan);
 646
 647 /* Handle stuff we need to do on open like notifying circuits */
 648 void channel_do_open_actions(channel_t *chan);
 649
 650 #endif /* defined(TOR_CHANNEL_INTERNAL_) */
 651
 652 /* Helper functions to perform operations on channels */
 653
 654 int channel_send_destroy(circid_t circ_id, channel_t *chan,
 655                          int reason);
 656
 657 /*
 658  * Outside abstract interfaces that should eventually get turned into
 659  * something transport/address format independent.
 660  */
 661
 662 channel_t * channel_connect(const tor_addr_t *addr, uint16_t port,
 663                             const char *rsa_id_digest,
 664                             const struct ed25519_public_key_t *ed_id);
 665
 666 channel_t * channel_get_for_extend(const char *rsa_id_digest,
 667                                    const struct ed25519_public_key_t *ed_id,
 668                                    const tor_addr_t *target_addr,
 669                                    const char **msg_out,
 670                                    int *launch_out);
 671
 672 /* Ask which of two channels is better for circuit-extension purposes */
 673 int channel_is_better(channel_t *a, channel_t *b);
 674
 675 /** Channel lookups
 676  */
 677
 678 channel_t * channel_find_by_global_id(uint64_t global_identifier);
 679 channel_t * channel_find_by_remote_identity(const char *rsa_id_digest,
 680                                     const struct ed25519_public_key_t *ed_id);
 681
 682 /** For things returned by channel_find_by_remote_digest(), walk the list.
 683  * The RSA key will match for all returned elements; the Ed25519 key might not.
 684  */
 685 channel_t * channel_next_with_rsa_identity(channel_t *chan);
 686
 687 /*
 688  * Helper macros to lookup state of given channel.
 689  */
 690
 691 #define CHANNEL_IS_CLOSED(chan) (channel_is_in_state((chan), \
 692                                  CHANNEL_STATE_CLOSED))
 693 #define CHANNEL_IS_OPENING(chan) (channel_is_in_state((chan), \
 694                                   CHANNEL_STATE_OPENING))
 695 #define CHANNEL_IS_OPEN(chan) (channel_is_in_state((chan), \
 696                                CHANNEL_STATE_OPEN))
 697 #define CHANNEL_IS_MAINT(chan) (channel_is_in_state((chan), \
 698                                 CHANNEL_STATE_MAINT))
 699 #define CHANNEL_IS_CLOSING(chan) (channel_is_in_state((chan), \
 700                                   CHANNEL_STATE_CLOSING))
 701 #define CHANNEL_IS_ERROR(chan) (channel_is_in_state((chan), \
 702                                 CHANNEL_STATE_ERROR))
 703
 704 #define CHANNEL_FINISHED(chan) (CHANNEL_IS_CLOSED(chan) || \
 705                                 CHANNEL_IS_ERROR(chan))
 706
 707 #define CHANNEL_CONDEMNED(chan) (CHANNEL_IS_CLOSING(chan) || \
 708                                  CHANNEL_FINISHED(chan))
 709
 710 #define CHANNEL_CAN_HANDLE_CELLS(chan) (CHANNEL_IS_OPENING(chan) || \
 711                                         CHANNEL_IS_OPEN(chan) || \
 712                                         CHANNEL_IS_MAINT(chan))
 713
 714 static inline int
 715 channel_is_in_state(channel_t *chan, channel_state_t state)
 716 {
 717   return chan->state == state;
 718 }
 719
 720 /*
 721  * Metadata queries/updates
 722  */
 723
 724 const char * channel_describe_transport(channel_t *chan);
 725 MOCK_DECL(void, channel_dump_statistics, (channel_t *chan, int severity));
 726 void channel_dump_transport_statistics(channel_t *chan, int severity);
 727 const char * channel_get_actual_remote_descr(channel_t *chan);
 728 const char * channel_get_actual_remote_address(channel_t *chan);
 729 MOCK_DECL(int, channel_get_addr_if_possible, (channel_t *chan,
 730                                               tor_addr_t *addr_out));
 731 const char * channel_get_canonical_remote_descr(channel_t *chan);
 732 int channel_has_queued_writes(channel_t *chan);
 733 int channel_is_bad_for_new_circs(channel_t *chan);
 734 void channel_mark_bad_for_new_circs(channel_t *chan);
 735 int channel_is_canonical(channel_t *chan);
 736 int channel_is_canonical_is_reliable(channel_t *chan);
 737 int channel_is_client(const channel_t *chan);
 738 int channel_is_local(channel_t *chan);
 739 int channel_is_incoming(channel_t *chan);
 740 int channel_is_outgoing(channel_t *chan);
 741 void channel_mark_client(channel_t *chan);
 742 void channel_clear_client(channel_t *chan);
 743 int channel_matches_extend_info(channel_t *chan, extend_info_t *extend_info);
 744 int channel_matches_target_addr_for_extend(channel_t *chan,
 745                                            const tor_addr_t *target);
 746 unsigned int channel_num_circuits(channel_t *chan);
 747 MOCK_DECL(void,channel_set_circid_type,(channel_t *chan,
 748                                         crypto_pk_t *identity_rcvd,
 749                                         int consider_identity));
 750 void channel_timestamp_client(channel_t *chan);
 751
 752 const char * channel_listener_describe_transport(channel_listener_t *chan_l);
 753 void channel_listener_dump_statistics(channel_listener_t *chan_l,
 754                                       int severity);
 755 void channel_listener_dump_transport_statistics(channel_listener_t *chan_l,
 756                                                 int severity);
 757 void channel_check_for_duplicates(void);
 758
 759 void channel_update_bad_for_new_circs(const char *digest, int force);
 760
 761 /* Flow control queries */
 762 int channel_num_cells_writeable(channel_t *chan);
 763
 764 /* Timestamp queries */
 765 time_t channel_when_created(channel_t *chan);
 766 time_t channel_when_last_client(channel_t *chan);
 767 time_t channel_when_last_xmit(channel_t *chan);
 768
 769 /* Counter queries */
 770 int packed_cell_is_destroy(channel_t *chan,
 771                            const packed_cell_t *packed_cell,
 772                            circid_t *circid_out);
 773
 774 /* Declare the handle helpers */
 775 HANDLE_DECL(channel, channel_s,)
 776 #define channel_handle_free(h)    \
 777   FREE_AND_NULL(channel_handle_t, channel_handle_free_, (h))
 778 #undef tor_timer_t
 779
 780 #endif /* !defined(TOR_CHANNEL_H) */