src/core/or/circuitlist.h

   1 /* Copyright (c) 2001 Matej Pfajfar.
   2  * Copyright (c) 2001-2004, Roger Dingledine.
   3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   4  * Copyright (c) 2007-2021, The Tor Project, Inc. */
   5 /* See LICENSE for licensing information */
   6
   7 /**
   8  * \file circuitlist.h
   9  * \brief Header file for circuitlist.c.
  10  **/
  11
  12 #ifndef TOR_CIRCUITLIST_H
  13 #define TOR_CIRCUITLIST_H
  14
  15 #include "lib/container/handles.h"
  16 #include "lib/testsupport/testsupport.h"
  17 #include "feature/hs/hs_ident.h"
  18 #include "core/or/ocirc_event.h"
  19
  20 /** Circuit state: I'm the origin, still haven't done all my handshakes. */
  21 #define CIRCUIT_STATE_BUILDING 0
  22 /** Circuit state: Waiting to process the onionskin. */
  23 #define CIRCUIT_STATE_ONIONSKIN_PENDING 1
  24 /** Circuit state: I'd like to deliver a create, but my n_chan is still
  25  * connecting. */
  26 #define CIRCUIT_STATE_CHAN_WAIT 2
  27 /** Circuit state: the circuit is open but we don't want to actually use it
  28  * until we find out if a better guard will be available.
  29  */
  30 #define CIRCUIT_STATE_GUARD_WAIT 3
  31 /** Circuit state: onionskin(s) processed, ready to send/receive cells. */
  32 #define CIRCUIT_STATE_OPEN 4
  33
  34 #define CIRCUIT_PURPOSE_MIN_ 1
  35
  36 /* these circuits were initiated elsewhere */
  37 #define CIRCUIT_PURPOSE_OR_MIN_ 1
  38 /** OR-side circuit purpose: normal circuit, at OR. */
  39 #define CIRCUIT_PURPOSE_OR 1
  40 /** OR-side circuit purpose: At OR, from the service, waiting for intro from
  41  * clients. */
  42 #define CIRCUIT_PURPOSE_INTRO_POINT 2
  43 /** OR-side circuit purpose: At OR, from the client, waiting for the service.
  44  */
  45 #define CIRCUIT_PURPOSE_REND_POINT_WAITING 3
  46 /** OR-side circuit purpose: At OR, both circuits have this purpose. */
  47 #define CIRCUIT_PURPOSE_REND_ESTABLISHED 4
  48 #define CIRCUIT_PURPOSE_OR_MAX_ 4
  49
  50 /* these circuits originate at this node */
  51
  52 /* here's how circ client-side purposes work:
  53  *   normal circuits are C_GENERAL.
  54  *   circuits that are c_introducing are either on their way to
  55  *     becoming open, or they are open and waiting for a
  56  *     suitable rendcirc before they send the intro.
  57  *   circuits that are c_introduce_ack_wait have sent the intro,
  58  *     but haven't gotten a response yet.
  59  *   circuits that are c_establish_rend are either on their way
  60  *     to becoming open, or they are open and have sent the
  61  *     establish_rendezvous cell but haven't received an ack.
  62  *   circuits that are c_rend_ready are open and have received a
  63  *     rend ack, but haven't heard from the service yet.
  64  *   circuits that are c_rend_ready_intro_acked are open, and
  65  *     some intro circ has sent its intro and received an ack.
  66  *   circuits that are c_rend_joined are open, have heard from
  67  *     the service, and are talking to it.
  68  */
  69 /** Client-side circuit purpose: Normal circuit, with cpath. */
  70 #define CIRCUIT_PURPOSE_C_GENERAL 5
  71 #define CIRCUIT_PURPOSE_C_HS_MIN_ 6
  72 /** Client-side circuit purpose: at the client, connecting to intro point. */
  73 #define CIRCUIT_PURPOSE_C_INTRODUCING 6
  74 /** Client-side circuit purpose: at the client, sent INTRODUCE1 to intro point,
  75  * waiting for ACK/NAK. */
  76 #define CIRCUIT_PURPOSE_C_INTRODUCE_ACK_WAIT 7
  77 /** Client-side circuit purpose: at the client, introduced and acked, closing.
  78  */
  79 #define CIRCUIT_PURPOSE_C_INTRODUCE_ACKED 8
  80 /** Client-side circuit purpose: at the client, waiting for ack. */
  81 #define CIRCUIT_PURPOSE_C_ESTABLISH_REND 9
  82 /** Client-side circuit purpose: at the client, waiting for the service. */
  83 #define CIRCUIT_PURPOSE_C_REND_READY 10
  84 /** Client-side circuit purpose: at the client, waiting for the service,
  85  * INTRODUCE has been acknowledged. */
  86 #define CIRCUIT_PURPOSE_C_REND_READY_INTRO_ACKED 11
  87 /** Client-side circuit purpose: at the client, rendezvous established. */
  88 #define CIRCUIT_PURPOSE_C_REND_JOINED 12
  89 /** This circuit is used for getting hsdirs */
  90 #define CIRCUIT_PURPOSE_C_HSDIR_GET 13
  91 #define CIRCUIT_PURPOSE_C_HS_MAX_ 13
  92 /** This circuit is used for build time measurement only */
  93 #define CIRCUIT_PURPOSE_C_MEASURE_TIMEOUT 14
  94 /** This circuit is being held open by circuit padding */
  95 #define CIRCUIT_PURPOSE_C_CIRCUIT_PADDING 15
  96 #define CIRCUIT_PURPOSE_C_MAX_ 15
  97
  98 #define CIRCUIT_PURPOSE_S_HS_MIN_ 16
  99 /** Hidden-service-side circuit purpose: at the service, waiting for
 100  * introductions. */
 101 #define CIRCUIT_PURPOSE_S_ESTABLISH_INTRO 16
 102 /** Hidden-service-side circuit purpose: at the service, successfully
 103  * established intro. */
 104 #define CIRCUIT_PURPOSE_S_INTRO 17
 105 /** Hidden-service-side circuit purpose: at the service, connecting to rend
 106  * point. */
 107 #define CIRCUIT_PURPOSE_S_CONNECT_REND 18
 108 /** Hidden-service-side circuit purpose: at the service, rendezvous
 109  * established. */
 110 #define CIRCUIT_PURPOSE_S_REND_JOINED 19
 111 /** This circuit is used for uploading hsdirs */
 112 #define CIRCUIT_PURPOSE_S_HSDIR_POST 20
 113 #define CIRCUIT_PURPOSE_S_HS_MAX_ 20
 114
 115 /** A testing circuit; not meant to be used for actual traffic. It is used for
 116  * bandwidth measurement, reachability test and address discovery from an
 117  * authority using the NETINFO cell. */
 118 #define CIRCUIT_PURPOSE_TESTING 21
 119 /** A controller made this circuit and Tor should not cannibalize it or attach
 120  * streams to it without explicitly being told. */
 121 #define CIRCUIT_PURPOSE_CONTROLLER 22
 122 /** This circuit is used for path bias probing only */
 123 #define CIRCUIT_PURPOSE_PATH_BIAS_TESTING 23
 124
 125 /** This circuit is used for vanguards/restricted paths.
 126  *
 127  *  This type of circuit is *only* created preemptively and never
 128  *  on-demand. When an HS operation needs to take place (e.g. connect to an
 129  *  intro point), these circuits are then cannibalized and repurposed to the
 130  *  actual needed HS purpose. */
 131 #define CIRCUIT_PURPOSE_HS_VANGUARDS 24
 132
 133 #define CIRCUIT_PURPOSE_MAX_ 24
 134 /** A catch-all for unrecognized purposes. Currently we don't expect
 135  * to make or see any circuits with this purpose. */
 136 #define CIRCUIT_PURPOSE_UNKNOWN 255
 137
 138 /** True iff the circuit purpose <b>p</b> is for a circuit that
 139  * originated at this node. */
 140 #define CIRCUIT_PURPOSE_IS_ORIGIN(p) ((p)>CIRCUIT_PURPOSE_OR_MAX_)
 141 /** True iff the circuit purpose <b>p</b> is for a circuit that originated
 142  * here to serve as a client.  (Hidden services don't count here.) */
 143 #define CIRCUIT_PURPOSE_IS_CLIENT(p)  \
 144   ((p)> CIRCUIT_PURPOSE_OR_MAX_ &&    \
 145    (p)<=CIRCUIT_PURPOSE_C_MAX_)
 146 /** True iff the circuit_t <b>c</b> is actually an origin_circuit_t. */
 147 #define CIRCUIT_IS_ORIGIN(c) (CIRCUIT_PURPOSE_IS_ORIGIN((c)->purpose))
 148 /** True iff the circuit purpose <b>p</b> is for an established rendezvous
 149  * circuit. */
 150 #define CIRCUIT_PURPOSE_IS_ESTABLISHED_REND(p) \
 151   ((p) == CIRCUIT_PURPOSE_C_REND_JOINED ||     \
 152    (p) == CIRCUIT_PURPOSE_S_REND_JOINED)
 153 /** True iff the circuit_t c is actually an or_circuit_t */
 154 #define CIRCUIT_IS_ORCIRC(c) (((circuit_t *)(c))->magic == OR_CIRCUIT_MAGIC)
 155
 156 /** True iff this circuit purpose should count towards the global
 157  * pending rate limit (set by MaxClientCircuitsPending). We count all
 158  * general purpose circuits, as well as the first step of client onion
 159  * service connections (HSDir gets). */
 160 #define CIRCUIT_PURPOSE_COUNTS_TOWARDS_MAXPENDING(p) \
 161     ((p) == CIRCUIT_PURPOSE_C_GENERAL || \
 162      (p) == CIRCUIT_PURPOSE_C_HSDIR_GET)
 163
 164 /** Convert a circuit_t* to a pointer to the enclosing or_circuit_t.  Assert
 165  * if the cast is impossible. */
 166 or_circuit_t *TO_OR_CIRCUIT(circuit_t *);
 167 const or_circuit_t *CONST_TO_OR_CIRCUIT(const circuit_t *);
 168 /** Convert a circuit_t* to a pointer to the enclosing origin_circuit_t.
 169  * Assert if the cast is impossible. */
 170 origin_circuit_t *TO_ORIGIN_CIRCUIT(circuit_t *);
 171 const origin_circuit_t *CONST_TO_ORIGIN_CIRCUIT(const circuit_t *);
 172
 173 MOCK_DECL(smartlist_t *, circuit_get_global_list, (void));
 174 smartlist_t *circuit_get_global_origin_circuit_list(void);
 175 int circuit_any_opened_circuits(void);
 176 int circuit_any_opened_circuits_cached(void);
 177 void circuit_cache_opened_circuit_state(int circuits_are_opened);
 178
 179 const char *circuit_state_to_string(int state);
 180 const char *circuit_purpose_to_controller_string(uint8_t purpose);
 181 const char *circuit_purpose_to_controller_hs_state_string(uint8_t purpose);
 182 const char *circuit_purpose_to_string(uint8_t purpose);
 183 void circuit_dump_by_conn(connection_t *conn, int severity);
 184 void circuit_set_p_circid_chan(or_circuit_t *circ, circid_t id,
 185                                channel_t *chan);
 186 void circuit_set_n_circid_chan(circuit_t *circ, circid_t id,
 187                                channel_t *chan);
 188 void channel_mark_circid_unusable(channel_t *chan, circid_t id);
 189 void channel_mark_circid_usable(channel_t *chan, circid_t id);
 190 time_t circuit_id_when_marked_unusable_on_channel(circid_t circ_id,
 191                                                   channel_t *chan);
 192 int circuit_event_status(origin_circuit_t *circ, circuit_status_event_t tp,
 193                          int reason_code);
 194 void circuit_set_state(circuit_t *circ, uint8_t state);
 195 void circuit_close_all_marked(void);
 196 int32_t circuit_initial_package_window(void);
 197 origin_circuit_t *origin_circuit_new(void);
 198 or_circuit_t *or_circuit_new(circid_t p_circ_id, channel_t *p_chan);
 199 circuit_t *circuit_get_by_circid_channel(circid_t circ_id,
 200                                          channel_t *chan);
 201 circuit_t *
 202 circuit_get_by_circid_channel_even_if_marked(circid_t circ_id,
 203                                              channel_t *chan);
 204 int circuit_id_in_use_on_channel(circid_t circ_id, channel_t *chan);
 205 circuit_t *circuit_get_by_edge_conn(edge_connection_t *conn);
 206 void circuit_unlink_all_from_channel(channel_t *chan, int reason);
 207 origin_circuit_t *circuit_get_by_global_id(uint32_t id);
 208 origin_circuit_t *circuit_get_next_by_purpose(origin_circuit_t *start,
 209                                               uint8_t purpose);
 210 origin_circuit_t *circuit_get_next_intro_circ(const origin_circuit_t *start,
 211                                               bool want_client_circ);
 212 origin_circuit_t *circuit_get_next_service_rp_circ(origin_circuit_t *start);
 213 origin_circuit_t *circuit_get_next_service_hsdir_circ(origin_circuit_t *start);
 214 origin_circuit_t *circuit_find_to_cannibalize(uint8_t purpose,
 215                                               extend_info_t *info, int flags);
 216 void circuit_mark_all_unused_circs(void);
 217 void circuit_mark_all_dirty_circs_as_unusable(void);
 218 void circuit_synchronize_written_or_bandwidth(const circuit_t *c,
 219                                               circuit_channel_direction_t dir);
 220 MOCK_DECL(void, circuit_mark_for_close_, (circuit_t *circ, int reason,
 221                                           int line, const char *cfile));
 222 int circuit_get_cpath_len(origin_circuit_t *circ);
 223 int circuit_get_cpath_opened_len(const origin_circuit_t *);
 224 void circuit_clear_cpath(origin_circuit_t *circ);
 225 crypt_path_t *circuit_get_cpath_hop(origin_circuit_t *circ, int hopnum);
 226 void circuit_get_all_pending_on_channel(smartlist_t *out,
 227                                         channel_t *chan);
 228 int circuit_count_pending_on_channel(channel_t *chan);
 229
 230 #define circuit_mark_for_close(c, reason)                               \
 231   circuit_mark_for_close_((c), (reason), __LINE__, SHORT_FILE__)
 232
 233 MOCK_DECL(void, assert_circuit_ok,(const circuit_t *c));
 234 void circuit_free_all(void);
 235 void circuits_handle_oom(size_t current_allocation);
 236
 237 void circuit_clear_testing_cell_stats(circuit_t *circ);
 238
 239 void channel_note_destroy_pending(channel_t *chan, circid_t id);
 240 MOCK_DECL(void, channel_note_destroy_not_pending,
 241           (channel_t *chan, circid_t id));
 242
 243 smartlist_t *circuit_find_circuits_to_upgrade_from_guard_wait(void);
 244
 245 /* Declare the handle helpers */
 246 HANDLE_DECL(circuit, circuit_t, )
 247 #define circuit_handle_free(h)    \
 248     FREE_AND_NULL(circuit_handle_t, circuit_handle_free_, (h))
 249
 250 #ifdef CIRCUITLIST_PRIVATE
 251 STATIC void circuit_free_(circuit_t *circ);
 252 #define circuit_free(circ) FREE_AND_NULL(circuit_t, circuit_free_, (circ))
 253 STATIC size_t n_cells_in_circ_queues(const circuit_t *c);
 254 STATIC uint32_t circuit_max_queued_data_age(const circuit_t *c, uint32_t now);
 255 STATIC uint32_t circuit_max_queued_cell_age(const circuit_t *c, uint32_t now);
 256 STATIC uint32_t circuit_max_queued_item_age(const circuit_t *c, uint32_t now);
 257 #endif /* defined(CIRCUITLIST_PRIVATE) */
 258
 259 #endif /* !defined(TOR_CIRCUITLIST_H) */