channel.h 27 KB

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