channel.h 26.6 KB
Newer Older
Nick Mathewson's avatar
Nick Mathewson committed
1
/* * Copyright (c) 2012-2019, The Tor Project, Inc. */
2
3
4
5
6
7
8
/* See LICENSE for licensing information */

/**
 * \file channel.h
 * \brief Header file for channel.c
 **/

9
10
#ifndef TOR_CHANNEL_H
#define TOR_CHANNEL_H
11

12
13
#include "core/or/or.h"
#include "core/or/circuitmux.h"
14
#include "lib/container/handles.h"
15
#include "lib/crypt_ops/crypto_ed25519.h"
16

17
18
#include "tor_queue.h"

19
20
21
#define tor_timer_t timeout
struct tor_timer_t;

22
/* Channel handler function pointer typedefs */
23
typedef void (*channel_listener_fn_ptr)(channel_listener_t *, channel_t *);
24
25
26
typedef void (*channel_cell_handler_fn_ptr)(channel_t *, cell_t *);
typedef void (*channel_var_cell_handler_fn_ptr)(channel_t *, var_cell_t *);

27
28
29
30
31
32
33
34
35
36
37
/**
 * This enum is used by channelpadding to decide when to pad channels.
 * Don't add values to it without updating the checks in
 * channelpadding_decide_to_pad_channel().
 */
typedef enum {
    CHANNEL_USED_NOT_USED_FOR_FULL_CIRCS = 0,
    CHANNEL_USED_FOR_FULL_CIRCS,
    CHANNEL_USED_FOR_USER_TRAFFIC,
} channel_usage_info_t;

38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
/** Possible rules for generating circuit IDs on an OR connection. */
typedef enum {
  CIRC_ID_TYPE_LOWER=0, /**< Pick from 0..1<<15-1. */
  CIRC_ID_TYPE_HIGHER=1, /**< Pick from 1<<15..1<<16-1. */
  /** The other side of a connection is an OP: never create circuits to it,
   * and let it use any circuit ID it wants. */
  CIRC_ID_TYPE_NEITHER=2
} circ_id_type_t;
#define circ_id_type_bitfield_t ENUM_BF(circ_id_type_t)

/* channel states for channel_t */

typedef enum {
  /*
   * Closed state - channel is inactive
   *
   * Permitted transitions from:
   *   - CHANNEL_STATE_CLOSING
   * Permitted transitions to:
   *   - CHANNEL_STATE_OPENING
   */
  CHANNEL_STATE_CLOSED = 0,
  /*
   * Opening state - channel is trying to connect
   *
   * Permitted transitions from:
   *   - CHANNEL_STATE_CLOSED
   * Permitted transitions to:
   *   - CHANNEL_STATE_CLOSING
   *   - CHANNEL_STATE_ERROR
   *   - CHANNEL_STATE_OPEN
   */
  CHANNEL_STATE_OPENING,
  /*
   * Open state - channel is active and ready for use
   *
   * Permitted transitions from:
   *   - CHANNEL_STATE_MAINT
   *   - CHANNEL_STATE_OPENING
   * Permitted transitions to:
   *   - CHANNEL_STATE_CLOSING
   *   - CHANNEL_STATE_ERROR
   *   - CHANNEL_STATE_MAINT
   */
  CHANNEL_STATE_OPEN,
  /*
   * Maintenance state - channel is temporarily offline for subclass specific
   *   maintenance activities such as TLS renegotiation.
   *
   * Permitted transitions from:
   *   - CHANNEL_STATE_OPEN
   * Permitted transitions to:
   *   - CHANNEL_STATE_CLOSING
   *   - CHANNEL_STATE_ERROR
   *   - CHANNEL_STATE_OPEN
   */
  CHANNEL_STATE_MAINT,
  /*
   * Closing state - channel is shutting down
   *
   * Permitted transitions from:
   *   - CHANNEL_STATE_MAINT
   *   - CHANNEL_STATE_OPEN
   * Permitted transitions to:
   *   - CHANNEL_STATE_CLOSED,
   *   - CHANNEL_STATE_ERROR
   */
  CHANNEL_STATE_CLOSING,
  /*
   * Error state - channel has experienced a permanent error
   *
   * Permitted transitions from:
   *   - CHANNEL_STATE_CLOSING
   *   - CHANNEL_STATE_MAINT
   *   - CHANNEL_STATE_OPENING
   *   - CHANNEL_STATE_OPEN
   * Permitted transitions to:
   *   - None
   */
  CHANNEL_STATE_ERROR,
  /*
   * Placeholder for maximum state value
   */
  CHANNEL_STATE_LAST
} channel_state_t;

/* channel listener states for channel_listener_t */

typedef enum {
  /*
   * Closed state - channel listener is inactive
   *
   * Permitted transitions from:
   *   - CHANNEL_LISTENER_STATE_CLOSING
   * Permitted transitions to:
   *   - CHANNEL_LISTENER_STATE_LISTENING
   */
  CHANNEL_LISTENER_STATE_CLOSED = 0,
  /*
   * Listening state - channel listener is listening for incoming
   * connections
   *
   * Permitted transitions from:
   *   - CHANNEL_LISTENER_STATE_CLOSED
   * Permitted transitions to:
   *   - CHANNEL_LISTENER_STATE_CLOSING
   *   - CHANNEL_LISTENER_STATE_ERROR
   */
  CHANNEL_LISTENER_STATE_LISTENING,
  /*
   * Closing state - channel listener is shutting down
   *
   * Permitted transitions from:
   *   - CHANNEL_LISTENER_STATE_LISTENING
   * Permitted transitions to:
   *   - CHANNEL_LISTENER_STATE_CLOSED,
   *   - CHANNEL_LISTENER_STATE_ERROR
   */
  CHANNEL_LISTENER_STATE_CLOSING,
  /*
   * Error state - channel listener has experienced a permanent error
   *
   * Permitted transitions from:
   *   - CHANNEL_STATE_CLOSING
   *   - CHANNEL_STATE_LISTENING
   * Permitted transitions to:
   *   - None
   */
  CHANNEL_LISTENER_STATE_ERROR,
  /*
   * Placeholder for maximum state value
   */
  CHANNEL_LISTENER_STATE_LAST
} channel_listener_state_t;

Nick Mathewson's avatar
Nick Mathewson committed
173
/**
Andrea Shepard's avatar
Andrea Shepard committed
174
 * Channel struct; see the channel_t typedef in or.h.  A channel is an
175
176
177
178
179
180
181
 * abstract interface for the OR-to-OR connection, similar to connection_or_t,
 * but without the strong coupling to the underlying TLS implementation.  They
 * are constructed by calling a protocol-specific function to open a channel
 * to a particular node, and once constructed support the abstract operations
 * defined below.
 */
struct channel_s {
Nick Mathewson's avatar
Nick Mathewson committed
182
  /** Magic number for type-checking cast macros */
183
184
  uint32_t magic;

185
186
187
  /** List entry for hashtable for global-identifier lookup. */
  HT_ENTRY(channel_s) gidmap_node;

188
189
190
  /** Handle entry for handle-based lookup */
  HANDLE_ENTRY(channel, channel_s);

Nick Mathewson's avatar
Nick Mathewson committed
191
  /** Current channel state */
192
193
  channel_state_t state;

Nick Mathewson's avatar
Nick Mathewson committed
194
  /** Globally unique ID number for a channel over the lifetime of a Tor
195
   * process.  This may not be 0.
196
197
198
   */
  uint64_t global_identifier;

Nick Mathewson's avatar
Nick Mathewson committed
199
  /** Should we expect to see this channel in the channel lists? */
200
201
  unsigned char registered:1;

202
203
204
  /** has this channel ever been open? */
  unsigned int has_been_open:1;

205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
  /**
   * This field indicates if the other side has enabled or disabled
   * padding via either the link protocol version or
   * channelpadding_negotiate cells.
   *
   * Clients can override this with ConnectionPadding in torrc to
   * disable or force padding to relays, but relays cannot override the
   * client's request.
   */
  unsigned int padding_enabled:1;

  /** Cached value of our decision to pad (to avoid expensive
   * checks during critical path statistics counting). */
  unsigned int currently_padding:1;

  /** Is there a pending netflow padding callback? */
  unsigned int pending_padding_callback:1;

223
224
225
  /** Is our peer likely to consider this channel canonical? */
  unsigned int is_canonical_to_peer:1;

226
227
228
229
  /** Has this channel ever been used for non-directory traffic?
   * Used to decide what channels to pad, and when. */
  channel_usage_info_t channel_usage;

230
231
232
  /** When should we send a cell for netflow padding? 0 means no padding is
   *  scheduled. */
  monotime_coarse_t next_padding_time;
233
234

  /** The callback pointer for the padding callbacks */
235
  struct tor_timer_t *padding_timer;
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
  /** The handle to this channel (to free on canceled timers) */
  struct channel_handle_t *timer_handle;

  /**
   * These two fields specify the minimum and maximum negotiated timeout
   * values for inactivity (send or receive) before we decide to pad a
   * channel. These fields can be set either via a PADDING_NEGOTIATE cell,
   * or the torrc option ReducedConnectionPadding. The consensus parameters
   * nf_ito_low and nf_ito_high are used to ensure that padding can only be
   * negotiated to be less frequent than what is specified in the consensus.
   * (This is done to prevent wingnut clients from requesting excessive
   * padding).
   *
   * The actual timeout value is randomly chosen between these two values
   * as per the table in channelpadding_get_netflow_inactive_timeout_ms(),
   * after ensuring that these values do not specify lower timeouts than
   * the consensus parameters.
   *
   * If these are 0, we have not negotiated or specified custom padding
   * times, and instead use consensus defaults. */
  uint16_t padding_timeout_low_ms;
  uint16_t padding_timeout_high_ms;

259
260
261
262
263
264
265
266
267
  /** Why did we close?
   */
  enum {
    CHANNEL_NOT_CLOSING = 0,
    CHANNEL_CLOSE_REQUESTED,
    CHANNEL_CLOSE_FROM_BELOW,
    CHANNEL_CLOSE_FOR_ERROR
  } reason_for_closing;

268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
  /** State variable for use by the scheduler */
  enum {
    /*
     * The channel is not open, or it has a full output buffer but no queued
     * cells.
     */
    SCHED_CHAN_IDLE = 0,
    /*
     * The channel has space on its output buffer to write, but no queued
     * cells.
     */
    SCHED_CHAN_WAITING_FOR_CELLS,
    /*
     * The scheduler has queued cells but no output buffer space to write.
     */
    SCHED_CHAN_WAITING_TO_WRITE,
    /*
     * The scheduler has both queued cells and output buffer space, and is
     * eligible for the scheduler loop.
     */
    SCHED_CHAN_PENDING
  } scheduler_state;

291
292
293
  /** Heap index for use by the scheduler */
  int sched_heap_idx;

Nick Mathewson's avatar
Nick Mathewson committed
294
  /** Timestamps for both cell channels and listeners */
295
296
297
  time_t timestamp_created; /* Channel created */
  time_t timestamp_active; /* Any activity */

298
  /**
299
   * This is a monotonic timestamp that marks when we
300
301
302
303
304
305
306
307
   * believe the channel has actually sent or received data to/from
   * the wire. Right now, it is used to determine when we should send
   * a padding cell for channelpadding.
   *
   * XXX: Are we setting timestamp_xfer_ms in the right places to
   * accurately reflect actual network data transfer? Or might this be
   * very wrong wrt when bytes actually go on the wire?
   */
308
  monotime_coarse_t timestamp_xfer;
309

310
311
  /* Methods implemented by the lower layer */

Nick Mathewson's avatar
Nick Mathewson committed
312
  /** Free a channel */
313
  void (*free_fn)(channel_t *);
Nick Mathewson's avatar
Nick Mathewson committed
314
  /** Close an open channel */
315
  void (*close)(channel_t *);
Nick Mathewson's avatar
Nick Mathewson committed
316
  /** Describe the transport subclass for this channel */
317
  const char * (*describe_transport)(channel_t *);
Nick Mathewson's avatar
Nick Mathewson committed
318
  /** Optional method to dump transport-specific statistics on the channel */
319
  void (*dumpstats)(channel_t *, int);
320

Nick Mathewson's avatar
Nick Mathewson committed
321
  /** Registered handlers for incoming cells */
322
323
324
325
326
  channel_cell_handler_fn_ptr cell_handler;
  channel_var_cell_handler_fn_ptr var_cell_handler;

  /* Methods implemented by the lower layer */

Nick Mathewson's avatar
Nick Mathewson committed
327
  /**
328
329
330
331
332
   * Ask the lower layer for an estimate of the average overhead for
   * transmissions on this channel.
   */
  double (*get_overhead_estimate)(channel_t *);
  /*
333
334
335
336
337
338
339
   * Ask the underlying transport what the remote endpoint address is, in
   * a tor_addr_t.  This is optional and subclasses may leave this NULL.
   * If they implement it, they should write the address out to the
   * provided tor_addr_t *, and return 1 if successful or 0 if no address
   * available.
   */
  int (*get_remote_addr)(channel_t *, tor_addr_t *);
340
341
  int (*get_transport_name)(channel_t *chan, char **transport_out);

342
343
#define GRD_FLAG_ORIGINAL 1
#define GRD_FLAG_ADDR_ONLY 2
Nick Mathewson's avatar
Nick Mathewson committed
344
  /**
345
346
347
348
   * Get a text description of the remote endpoint; canonicalized if the flag
   * GRD_FLAG_ORIGINAL is not set, or the one we originally connected
   * to/received from if it is.  If GRD_FLAG_ADDR_ONLY is set, we return only
   * the original address.
349
350
   */
  const char * (*get_remote_descr)(channel_t *, int);
Nick Mathewson's avatar
Nick Mathewson committed
351
  /** Check if the lower layer has queued writes */
352
  int (*has_queued_writes)(channel_t *);
Nick Mathewson's avatar
Nick Mathewson committed
353
  /**
354
355
   * Ask the lower layer if this is 'canonical', for a transport-specific
   * definition of canonical.
356
   */
357
  int (*is_canonical)(channel_t *);
Nick Mathewson's avatar
Nick Mathewson committed
358
  /** Check if this channel matches a specified extend_info_t */
359
  int (*matches_extend_info)(channel_t *, extend_info_t *);
Nick Mathewson's avatar
Nick Mathewson committed
360
  /** Check if this channel matches a target address when extending */
361
  int (*matches_target)(channel_t *, const tor_addr_t *);
362
363
  /* Ask the lower layer how many bytes it has queued but not yet sent */
  size_t (*num_bytes_queued)(channel_t *);
364
365
366
  /* Ask the lower layer how many cells can be written */
  int (*num_cells_writeable)(channel_t *);
  /* Write a cell to an open channel */
367
  int (*write_cell)(channel_t *, cell_t *);
Nick Mathewson's avatar
Nick Mathewson committed
368
  /** Write a packed cell to an open channel */
369
  int (*write_packed_cell)(channel_t *, packed_cell_t *);
Nick Mathewson's avatar
Nick Mathewson committed
370
  /** Write a variable-length cell to an open channel */
371
372
  int (*write_var_cell)(channel_t *, var_cell_t *);

Nick Mathewson's avatar
Nick Mathewson committed
373
  /**
374
375
376
377
378
379
380
   * Hash of the public RSA key for the other side's RSA identity key -- or
   * zeroes if we don't have an RSA identity in mind for the other side, and
   * it hasn't shown us one.
   *
   * Note that this is the RSA identity that we hope the other side has -- not
   * necessarily its true identity.  Don't believe this identity unless
   * authentication has happened.
381
382
   */
  char identity_digest[DIGEST_LEN];
383
  /**
384
385
386
387
388
389
390
   * Ed25519 key for the other side of this channel -- or zeroes if we don't
   * have an Ed25519 identity in mind for the other side, and it hasn't shown
   * us one.
   *
   * Note that this is the identity that we hope the other side has -- not
   * necessarily its true identity.  Don't believe this identity unless
   * authentication has happened.
391
   */
392
  struct ed25519_public_key_t ed25519_identity;
393

Nick Mathewson's avatar
Nick Mathewson committed
394
  /**
395
396
   * Linked list of channels with the same RSA identity digest, for use with
   * the digest->channel map
397
   */
398
  TOR_LIST_ENTRY(channel_s) next_with_same_id;
399

Nick Mathewson's avatar
Nick Mathewson committed
400
  /** Circuit mux for circuits sending on this channel */
401
  circuitmux_t *cmux;
402

Nick Mathewson's avatar
Nick Mathewson committed
403
  /** Circuit ID generation stuff for use by circuitbuild.c */
404

Nick Mathewson's avatar
Nick Mathewson committed
405
  /**
406
407
408
   * When we send CREATE cells along this connection, which half of the
   * space should we use?
   */
Nick Mathewson's avatar
Nick Mathewson committed
409
  circ_id_type_bitfield_t circ_id_type:2;
410
  /* DOCDOC */
411
  unsigned wide_circ_ids:1;
412

Nick Mathewson's avatar
Nick Mathewson committed
413
  /** For how many circuits are we n_chan?  What about p_chan? */
414
  unsigned int num_n_circuits, num_p_circuits;
415

Nick Mathewson's avatar
Nick Mathewson committed
416
  /**
417
418
419
420
421
422
423
424
425
   * True iff this channel shouldn't get any new circs attached to it,
   * because the connection is too old, or because there's a better one.
   * More generally, this flag is used to note an unhealthy connection;
   * for example, if a bad connection fails we shouldn't assume that the
   * router itself has a problem.
   */
  unsigned int is_bad_for_new_circs:1;

  /** True iff we have decided that the other end of this connection
426
427
   * is a client or bridge relay.  Connections with this flag set should never
   * be used to satisfy an EXTEND request. */
428
429
430
431
432
433
434
435
436
437
438
439
  unsigned int is_client:1;

  /** Set if the channel was initiated remotely (came from a listener) */
  unsigned int is_incoming:1;

  /** Set by lower layer if this is local; i.e., everything it communicates
   * with for this channel returns true for is_local_addr().  This is used
   * to decide whether to declare reachability when we receive something on
   * this channel in circuitbuild.c
   */
  unsigned int is_local:1;

440
441
442
443
  /** Have we logged a warning about circID exhaustion on this channel?
   * If so, when? */
  ratelim_t last_warned_circ_ids_exhausted;

444
445
446
447
448
  /** Channel timestamps for cell channels */
  time_t timestamp_client; /* Client used this, according to relay.c */
  time_t timestamp_recv; /* Cell received from lower layer */
  time_t timestamp_xmit; /* Cell sent to lower layer */

449
450
451
452
  /** Timestamp for run_connection_housekeeping(). We update this once a
   * second when we run housekeeping and find a circuit on this channel, and
   * whenever we add a circuit to the channel. */
  time_t timestamp_last_had_circuits;
453
454
455
456
457
458
459

  /** Unique ID for measuring direct network status requests;vtunneled ones
   * come over a circuit_t, which has a dirreq_id field as well, but is a
   * distinct namespace. */
  uint64_t dirreq_id;

  /** Channel counters for cell channels */
460
461
  uint64_t n_cells_recved, n_bytes_recved;
  uint64_t n_cells_xmitted, n_bytes_xmitted;
462
463
464
465
466
467
468
469
470
471
472
};

struct channel_listener_s {
  /* Current channel listener state */
  channel_listener_state_t state;

  /* Globally unique ID number for a channel over the lifetime of a Tor
   * process.
   */
  uint64_t global_identifier;

Nick Mathewson's avatar
Nick Mathewson committed
473
  /** Should we expect to see this channel in the channel lists? */
474
475
476
477
478
479
480
481
482
483
484
  unsigned char registered:1;

  /** Why did we close?
   */
  enum {
    CHANNEL_LISTENER_NOT_CLOSING = 0,
    CHANNEL_LISTENER_CLOSE_REQUESTED,
    CHANNEL_LISTENER_CLOSE_FROM_BELOW,
    CHANNEL_LISTENER_CLOSE_FOR_ERROR
  } reason_for_closing;

Nick Mathewson's avatar
Nick Mathewson committed
485
  /** Timestamps for both cell channels and listeners */
486
487
488
489
490
  time_t timestamp_created; /* Channel created */
  time_t timestamp_active; /* Any activity */

  /* Methods implemented by the lower layer */

Nick Mathewson's avatar
Nick Mathewson committed
491
  /** Free a channel */
492
  void (*free_fn)(channel_listener_t *);
Nick Mathewson's avatar
Nick Mathewson committed
493
  /** Close an open channel */
494
  void (*close)(channel_listener_t *);
Nick Mathewson's avatar
Nick Mathewson committed
495
  /** Describe the transport subclass for this channel */
496
  const char * (*describe_transport)(channel_listener_t *);
Nick Mathewson's avatar
Nick Mathewson committed
497
  /** Optional method to dump transport-specific statistics on the channel */
498
499
  void (*dumpstats)(channel_listener_t *, int);

Nick Mathewson's avatar
Nick Mathewson committed
500
  /** Registered listen handler to call on incoming connection */
501
502
  channel_listener_fn_ptr listener;

Nick Mathewson's avatar
Nick Mathewson committed
503
  /** List of pending incoming connections */
504
505
  smartlist_t *incoming_list;

Nick Mathewson's avatar
Nick Mathewson committed
506
  /** Timestamps for listeners */
507
508
  time_t timestamp_accepted;

Nick Mathewson's avatar
Nick Mathewson committed
509
  /** Counters for listeners */
510
  uint64_t n_accepted;
511
512
513
514
515
};

/* Channel state manipulations */

int channel_state_is_valid(channel_state_t state);
516
517
int channel_listener_state_is_valid(channel_listener_state_t state);

518
int channel_state_can_transition(channel_state_t from, channel_state_t to);
519
520
521
int channel_listener_state_can_transition(channel_listener_state_t from,
                                          channel_listener_state_t to);

522
const char * channel_state_to_string(channel_state_t state);
523
524
const char *
channel_listener_state_to_string(channel_listener_state_t state);
525
526
527

/* Abstract channel operations */

528
void channel_mark_for_close(channel_t *chan);
529
int channel_write_packed_cell(channel_t *chan, packed_cell_t *cell);
530

531
532
void channel_listener_mark_for_close(channel_listener_t *chan_l);

533
534
535
/* Channel callback registrations */

/* Listener callback */
536
537
void channel_listener_set_listener_fn(channel_listener_t *chan,
                                      channel_listener_fn_ptr listener);
538
539

/* Incoming cell callbacks */
540
541
542
543
544
channel_cell_handler_fn_ptr channel_get_cell_handler(channel_t *chan);

channel_var_cell_handler_fn_ptr
channel_get_var_cell_handler(channel_t *chan);

545
void channel_set_cell_handlers(channel_t *chan,
546
547
548
                               channel_cell_handler_fn_ptr cell_handler,
                               channel_var_cell_handler_fn_ptr
                                 var_cell_handler);
549

550
551
/* Clean up closed channels and channel listeners periodically; these are
 * called from run_scheduled_events() in main.c.
552
553
 */
void channel_run_cleanup(void);
554
void channel_listener_run_cleanup(void);
555
556
557
558

/* Close all channels and deallocate everything */
void channel_free_all(void);

559
560
/* Dump some statistics in the log */
void channel_dumpstats(int severity);
561
void channel_listener_dumpstats(int severity);
562

563
#ifdef TOR_CHANNEL_INTERNAL_
564

565
566
#ifdef CHANNEL_PRIVATE_

567
568
STATIC void channel_add_to_digest_map(channel_t *chan);

569
#endif /* defined(CHANNEL_PRIVATE_) */
570

571
572
573
574
575
576
/* Channel operations for subclasses and internal use only */

/* Initialize a newly allocated channel - do this first in subclass
 * constructors.
 */

577
578
void channel_init(channel_t *chan);
void channel_init_listener(channel_listener_t *chan);
579
580
581
582
583

/* Channel registration/unregistration */
void channel_register(channel_t *chan);
void channel_unregister(channel_t *chan);

584
585
586
587
/* Channel listener registration/unregistration */
void channel_listener_register(channel_listener_t *chan_l);
void channel_listener_unregister(channel_listener_t *chan_l);

588
589
590
591
592
593
/* Close from below */
void channel_close_from_lower_layer(channel_t *chan);
void channel_close_for_error(channel_t *chan);
void channel_closed(channel_t *chan);

/* Free a channel */
594
void channel_free_(channel_t *chan);
595
#define channel_free(chan) FREE_AND_NULL(channel_t, channel_free_, (chan))
596
void channel_listener_free_(channel_listener_t *chan_l);
597
598
#define channel_listener_free(chan_l) \
  FREE_AND_NULL(channel_listener_t, channel_listener_free_, (chan_l))
599
600
601
602

/* State/metadata setters */

void channel_change_state(channel_t *chan, channel_state_t to_state);
603
void channel_change_state_open(channel_t *chan);
604
605
606
607
608
void channel_clear_identity_digest(channel_t *chan);
void channel_clear_remote_end(channel_t *chan);
void channel_mark_local(channel_t *chan);
void channel_mark_incoming(channel_t *chan);
void channel_mark_outgoing(channel_t *chan);
609
void channel_mark_remote(channel_t *chan);
610
void channel_set_identity_digest(channel_t *chan,
611
612
                             const char *identity_digest,
                             const struct ed25519_public_key_t *ed_identity);
613

614
615
616
void channel_listener_change_state(channel_listener_t *chan_l,
                                   channel_listener_state_t to_state);

617
618
619
620
621
622
/* Timestamp updates */
void channel_timestamp_created(channel_t *chan);
void channel_timestamp_active(channel_t *chan);
void channel_timestamp_recv(channel_t *chan);
void channel_timestamp_xmit(channel_t *chan);

623
624
625
626
void channel_listener_timestamp_created(channel_listener_t *chan_l);
void channel_listener_timestamp_active(channel_listener_t *chan_l);
void channel_listener_timestamp_accepted(channel_listener_t *chan_l);

627
/* Incoming channel handling */
628
629
630
void channel_listener_process_incoming(channel_listener_t *listener);
void channel_listener_queue_incoming(channel_listener_t *listener,
                                     channel_t *incoming);
631
632

/* Incoming cell handling */
633
void channel_process_cell(channel_t *chan, cell_t *cell);
634
635

/* Request from lower layer for more cells if available */
636
637
MOCK_DECL(ssize_t, channel_flush_some_cells,
          (channel_t *chan, ssize_t num_cells));
638
639

/* Query if data available on this channel */
640
MOCK_DECL(int, channel_more_to_flush, (channel_t *chan));
641
642
643
644
645
646
647

/* Notify flushed outgoing for dirreq handling */
void channel_notify_flushed(channel_t *chan);

/* Handle stuff we need to do on open like notifying circuits */
void channel_do_open_actions(channel_t *chan);

648
#endif /* defined(TOR_CHANNEL_INTERNAL_) */
649
650
651
652
653
654
655
656
657
658
659
660

/* Helper functions to perform operations on channels */

int channel_send_destroy(circid_t circ_id, channel_t *chan,
                         int reason);

/*
 * Outside abstract interfaces that should eventually get turned into
 * something transport/address format independent.
 */

channel_t * channel_connect(const tor_addr_t *addr, uint16_t port,
661
                            const char *rsa_id_digest,
662
                            const struct ed25519_public_key_t *ed_id);
663

664
channel_t * channel_get_for_extend(const char *rsa_id_digest,
665
                                   const struct ed25519_public_key_t *ed_id,
666
667
668
669
670
                                   const tor_addr_t *target_addr,
                                   const char **msg_out,
                                   int *launch_out);

/* Ask which of two channels is better for circuit-extension purposes */
671
int channel_is_better(channel_t *a, channel_t *b);
672
673
674
675
676

/** Channel lookups
 */

channel_t * channel_find_by_global_id(uint64_t global_identifier);
677
channel_t * channel_find_by_remote_identity(const char *rsa_id_digest,
678
                                    const struct ed25519_public_key_t *ed_id);
679
680

/** For things returned by channel_find_by_remote_digest(), walk the list.
681
 * The RSA key will match for all returned elements; the Ed25519 key might not.
682
 */
683
channel_t * channel_next_with_rsa_identity(channel_t *chan);
684

685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
/*
 * Helper macros to lookup state of given channel.
 */

#define CHANNEL_IS_CLOSED(chan) (channel_is_in_state((chan), \
                                 CHANNEL_STATE_CLOSED))
#define CHANNEL_IS_OPENING(chan) (channel_is_in_state((chan), \
                                  CHANNEL_STATE_OPENING))
#define CHANNEL_IS_OPEN(chan) (channel_is_in_state((chan), \
                               CHANNEL_STATE_OPEN))
#define CHANNEL_IS_MAINT(chan) (channel_is_in_state((chan), \
                                CHANNEL_STATE_MAINT))
#define CHANNEL_IS_CLOSING(chan) (channel_is_in_state((chan), \
                                  CHANNEL_STATE_CLOSING))
#define CHANNEL_IS_ERROR(chan) (channel_is_in_state((chan), \
                                CHANNEL_STATE_ERROR))

#define CHANNEL_FINISHED(chan) (CHANNEL_IS_CLOSED(chan) || \
                                CHANNEL_IS_ERROR(chan))

#define CHANNEL_CONDEMNED(chan) (CHANNEL_IS_CLOSING(chan) || \
                                 CHANNEL_FINISHED(chan))

#define CHANNEL_CAN_HANDLE_CELLS(chan) (CHANNEL_IS_OPENING(chan) || \
                                        CHANNEL_IS_OPEN(chan) || \
                                        CHANNEL_IS_MAINT(chan))

712
static inline int
713
714
715
716
717
channel_is_in_state(channel_t *chan, channel_state_t state)
{
  return chan->state == state;
}

718
719
720
721
/*
 * Metadata queries/updates
 */

722
const char * channel_describe_transport(channel_t *chan);
723
MOCK_DECL(void, channel_dump_statistics, (channel_t *chan, int severity));
724
void channel_dump_transport_statistics(channel_t *chan, int severity);
725
const char * channel_get_actual_remote_descr(channel_t *chan);
726
const char * channel_get_actual_remote_address(channel_t *chan);
727
728
MOCK_DECL(int, channel_get_addr_if_possible, (channel_t *chan,
                                              tor_addr_t *addr_out));
729
730
731
732
733
const char * channel_get_canonical_remote_descr(channel_t *chan);
int channel_has_queued_writes(channel_t *chan);
int channel_is_bad_for_new_circs(channel_t *chan);
void channel_mark_bad_for_new_circs(channel_t *chan);
int channel_is_canonical(channel_t *chan);
734
int channel_is_client(const channel_t *chan);
735
736
737
738
int channel_is_local(channel_t *chan);
int channel_is_incoming(channel_t *chan);
int channel_is_outgoing(channel_t *chan);
void channel_mark_client(channel_t *chan);
739
void channel_clear_client(channel_t *chan);
740
int channel_matches_extend_info(channel_t *chan, extend_info_t *extend_info);
741
742
743
int channel_remote_identity_matches(const channel_t *chan,
                                    const char *rsa_id_digest,
                                    const ed25519_public_key_t *ed_id);
744
745
int channel_matches_target_addr_for_extend(channel_t *chan,
                                           const tor_addr_t *target);
746
unsigned int channel_num_circuits(channel_t *chan);
747
748
749
MOCK_DECL(void,channel_set_circid_type,(channel_t *chan,
                                        crypto_pk_t *identity_rcvd,
                                        int consider_identity));
750
751
void channel_timestamp_client(channel_t *chan);

752
753
754
755
756
const char * channel_listener_describe_transport(channel_listener_t *chan_l);
void channel_listener_dump_statistics(channel_listener_t *chan_l,
                                      int severity);
void channel_listener_dump_transport_statistics(channel_listener_t *chan_l,
                                                int severity);
757
void channel_check_for_duplicates(void);
758

759
760
void channel_update_bad_for_new_circs(const char *digest, int force);

761
762
763
/* Flow control queries */
int channel_num_cells_writeable(channel_t *chan);

764
765
766
767
768
/* Timestamp queries */
time_t channel_when_created(channel_t *chan);
time_t channel_when_last_client(channel_t *chan);
time_t channel_when_last_xmit(channel_t *chan);

769
/* Counter queries */
770
771
772
773
int packed_cell_is_destroy(channel_t *chan,
                           const packed_cell_t *packed_cell,
                           circid_t *circid_out);

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) */