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