Tor  0.4.3.0-alpha-dev
circuitlist.h
Go to the documentation of this file.
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-2019, 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"
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. if they have a
64  * buildstate->pending_final_cpath then they're expecting a
65  * cell from the service, else they're not.
66  * circuits that are c_rend_ready_intro_acked are open, and
67  * some intro circ has sent its intro and received an ack.
68  * circuits that are c_rend_joined are open, have heard from
69  * the service, and are talking to it.
70  */
71 /** Client-side circuit purpose: Normal circuit, with cpath. */
72 #define CIRCUIT_PURPOSE_C_GENERAL 5
73 #define CIRCUIT_PURPOSE_C_HS_MIN_ 6
74 /** Client-side circuit purpose: at the client, connecting to intro point. */
75 #define CIRCUIT_PURPOSE_C_INTRODUCING 6
76 /** Client-side circuit purpose: at the client, sent INTRODUCE1 to intro point,
77  * waiting for ACK/NAK. */
78 #define CIRCUIT_PURPOSE_C_INTRODUCE_ACK_WAIT 7
79 /** Client-side circuit purpose: at the client, introduced and acked, closing.
80  */
81 #define CIRCUIT_PURPOSE_C_INTRODUCE_ACKED 8
82 /** Client-side circuit purpose: at the client, waiting for ack. */
83 #define CIRCUIT_PURPOSE_C_ESTABLISH_REND 9
84 /** Client-side circuit purpose: at the client, waiting for the service. */
85 #define CIRCUIT_PURPOSE_C_REND_READY 10
86 /** Client-side circuit purpose: at the client, waiting for the service,
87  * INTRODUCE has been acknowledged. */
88 #define CIRCUIT_PURPOSE_C_REND_READY_INTRO_ACKED 11
89 /** Client-side circuit purpose: at the client, rendezvous established. */
90 #define CIRCUIT_PURPOSE_C_REND_JOINED 12
91 /** This circuit is used for getting hsdirs */
92 #define CIRCUIT_PURPOSE_C_HSDIR_GET 13
93 #define CIRCUIT_PURPOSE_C_HS_MAX_ 13
94 /** This circuit is used for build time measurement only */
95 #define CIRCUIT_PURPOSE_C_MEASURE_TIMEOUT 14
96 /** This circuit is being held open by circuit padding */
97 #define CIRCUIT_PURPOSE_C_CIRCUIT_PADDING 15
98 #define CIRCUIT_PURPOSE_C_MAX_ 15
99 
100 #define CIRCUIT_PURPOSE_S_HS_MIN_ 16
101 /** Hidden-service-side circuit purpose: at the service, waiting for
102  * introductions. */
103 #define CIRCUIT_PURPOSE_S_ESTABLISH_INTRO 16
104 /** Hidden-service-side circuit purpose: at the service, successfully
105  * established intro. */
106 #define CIRCUIT_PURPOSE_S_INTRO 17
107 /** Hidden-service-side circuit purpose: at the service, connecting to rend
108  * point. */
109 #define CIRCUIT_PURPOSE_S_CONNECT_REND 18
110 /** Hidden-service-side circuit purpose: at the service, rendezvous
111  * established. */
112 #define CIRCUIT_PURPOSE_S_REND_JOINED 19
113 /** This circuit is used for uploading hsdirs */
114 #define CIRCUIT_PURPOSE_S_HSDIR_POST 20
115 #define CIRCUIT_PURPOSE_S_HS_MAX_ 20
116 
117 /** A testing circuit; not meant to be used for actual traffic. */
118 #define CIRCUIT_PURPOSE_TESTING 21
119 /** A controller made this circuit and Tor should not use it. */
120 #define CIRCUIT_PURPOSE_CONTROLLER 22
121 /** This circuit is used for path bias probing only */
122 #define CIRCUIT_PURPOSE_PATH_BIAS_TESTING 23
123 
124 /** This circuit is used for vanguards/restricted paths.
125  *
126  * This type of circuit is *only* created preemptively and never
127  * on-demand. When an HS operation needs to take place (e.g. connect to an
128  * intro point), these circuits are then cannibalized and repurposed to the
129  * actual needed HS purpose. */
130 #define CIRCUIT_PURPOSE_HS_VANGUARDS 24
131 
132 #define CIRCUIT_PURPOSE_MAX_ 24
133 /** A catch-all for unrecognized purposes. Currently we don't expect
134  * to make or see any circuits with this purpose. */
135 #define CIRCUIT_PURPOSE_UNKNOWN 255
136 
137 /** True iff the circuit purpose <b>p</b> is for a circuit that
138  * originated at this node. */
139 #define CIRCUIT_PURPOSE_IS_ORIGIN(p) ((p)>CIRCUIT_PURPOSE_OR_MAX_)
140 /** True iff the circuit purpose <b>p</b> is for a circuit that originated
141  * here to serve as a client. (Hidden services don't count here.) */
142 #define CIRCUIT_PURPOSE_IS_CLIENT(p) \
143  ((p)> CIRCUIT_PURPOSE_OR_MAX_ && \
144  (p)<=CIRCUIT_PURPOSE_C_MAX_)
145 /** True iff the circuit_t <b>c</b> is actually an origin_circuit_t. */
146 #define CIRCUIT_IS_ORIGIN(c) (CIRCUIT_PURPOSE_IS_ORIGIN((c)->purpose))
147 /** True iff the circuit purpose <b>p</b> is for an established rendezvous
148  * circuit. */
149 #define CIRCUIT_PURPOSE_IS_ESTABLISHED_REND(p) \
150  ((p) == CIRCUIT_PURPOSE_C_REND_JOINED || \
151  (p) == CIRCUIT_PURPOSE_S_REND_JOINED)
152 /** True iff the circuit_t c is actually an or_circuit_t */
153 #define CIRCUIT_IS_ORCIRC(c) (((circuit_t *)(c))->magic == OR_CIRCUIT_MAGIC)
154 
155 /** True iff this circuit purpose should count towards the global
156  * pending rate limit (set by MaxClientCircuitsPending). We count all
157  * general purpose circuits, as well as the first step of client onion
158  * service connections (HSDir gets). */
159 #define CIRCUIT_PURPOSE_COUNTS_TOWARDS_MAXPENDING(p) \
160  ((p) == CIRCUIT_PURPOSE_C_GENERAL || \
161  (p) == CIRCUIT_PURPOSE_C_HSDIR_GET)
162 
163 /** Convert a circuit_t* to a pointer to the enclosing or_circuit_t. Assert
164  * if the cast is impossible. */
166 const or_circuit_t *CONST_TO_OR_CIRCUIT(const circuit_t *);
167 /** Convert a circuit_t* to a pointer to the enclosing origin_circuit_t.
168  * Assert if the cast is impossible. */
170 const origin_circuit_t *CONST_TO_ORIGIN_CIRCUIT(const circuit_t *);
171 
176 void circuit_cache_opened_circuit_state(int circuits_are_opened);
177 
178 const char *circuit_state_to_string(int state);
179 const char *circuit_purpose_to_controller_string(uint8_t purpose);
180 const char *circuit_purpose_to_controller_hs_state_string(uint8_t purpose);
181 const char *circuit_purpose_to_string(uint8_t purpose);
182 void circuit_dump_by_conn(connection_t *conn, int severity);
184  channel_t *chan);
186  channel_t *chan);
187 void channel_mark_circid_unusable(channel_t *chan, circid_t id);
188 void channel_mark_circid_usable(channel_t *chan, circid_t id);
190  channel_t *chan);
192  int reason_code);
193 void circuit_set_state(circuit_t *circ, uint8_t state);
194 void circuit_close_all_marked(void);
195 int32_t circuit_initial_package_window(void);
197 or_circuit_t *or_circuit_new(circid_t p_circ_id, channel_t *p_chan);
199  channel_t *chan);
200 circuit_t *
202  channel_t *chan);
203 int circuit_id_in_use_on_channel(circid_t circ_id, channel_t *chan);
205 void circuit_unlink_all_from_channel(channel_t *chan, int reason);
208  const rend_data_t *rend_data);
210  const uint8_t *digest, uint8_t purpose);
212  bool want_client_circ);
214 origin_circuit_t *circuit_get_next_service_hsdir_circ(origin_circuit_t *start);
216  extend_info_t *info, int flags);
221 MOCK_DECL(void, circuit_mark_for_close_, (circuit_t *circ, int reason,
222  int line, const char *cfile));
228  channel_t *chan);
229 int circuit_count_pending_on_channel(channel_t *chan);
230 
231 #define circuit_mark_for_close(c, reason) \
232  circuit_mark_for_close_((c), (reason), __LINE__, SHORT_FILE__)
233 
234 MOCK_DECL(void, assert_circuit_ok,(const circuit_t *c));
235 void circuit_free_all(void);
236 void circuits_handle_oom(size_t current_allocation);
237 
239 
240 void channel_note_destroy_pending(channel_t *chan, circid_t id);
242  (channel_t *chan, circid_t id));
243 
245 
246 /* Declare the handle helpers */
247 HANDLE_DECL(circuit, circuit_t, )
248 #define circuit_handle_free(h) \
249  FREE_AND_NULL(circuit_handle_t, circuit_handle_free_, (h))
250 
251 #ifdef CIRCUITLIST_PRIVATE
252 STATIC void circuit_free_(circuit_t *circ);
253 #define circuit_free(circ) FREE_AND_NULL(circuit_t, circuit_free_, (circ))
254 STATIC size_t n_cells_in_circ_queues(const circuit_t *c);
255 STATIC uint32_t circuit_max_queued_data_age(const circuit_t *c, uint32_t now);
256 STATIC uint32_t circuit_max_queued_cell_age(const circuit_t *c, uint32_t now);
257 STATIC uint32_t circuit_max_queued_item_age(const circuit_t *c, uint32_t now);
258 #endif /* defined(CIRCUITLIST_PRIVATE) */
259 
260 #endif /* !defined(TOR_CIRCUITLIST_H) */
int32_t circuit_initial_package_window(void)
Definition: circuitlist.c:973
or_circuit_t * or_circuit_new(circid_t p_circ_id, channel_t *p_chan)
Definition: circuitlist.c:1088
origin_circuit_t * circuit_get_next_service_rp_circ(origin_circuit_t *start)
Definition: circuitlist.c:1776
origin_circuit_t * TO_ORIGIN_CIRCUIT(circuit_t *)
Definition: circuitlist.c:166
void circuit_set_p_circid_chan(or_circuit_t *circ, circid_t id, channel_t *chan)
Definition: circuitlist.c:451
time_t circuit_id_when_marked_unusable_on_channel(circid_t circ_id, channel_t *chan)
Definition: circuitlist.c:1559
void circuit_cache_opened_circuit_state(int circuits_are_opened)
Definition: circuitlist.c:742
void circuit_synchronize_written_or_bandwidth(const circuit_t *c, circuit_channel_direction_t dir)
Definition: circuitlist.c:2140
void circuit_mark_all_dirty_circs_as_unusable(void)
Definition: circuitlist.c:2112
void circuit_mark_all_unused_circs(void)
Definition: circuitlist.c:2093
void channel_mark_circid_usable(channel_t *chan, circid_t id)
Definition: circuitlist.c:386
smartlist_t * circuit_get_global_origin_circuit_list(void)
Definition: circuitlist.c:701
origin_circuit_t * circuit_get_ready_rend_circ_by_rend_data(const rend_data_t *rend_data)
Definition: circuitlist.c:1687
void circuit_dump_by_conn(connection_t *conn, int severity)
Definition: circuitlist.c:1384
Macros for C weak-handle implementation.
const char * circuit_purpose_to_controller_string(uint8_t purpose)
Definition: circuitlist.c:780
void circuit_mark_for_close_(circuit_t *circ, int reason, int line, const char *cfile)
Definition: circuitlist.c:2197
void circuit_set_n_circid_chan(circuit_t *circ, circid_t id, channel_t *chan)
Definition: circuitlist.c:474
origin_circuit_t * circuit_get_next_intro_circ(const origin_circuit_t *start, bool want_client_circ)
Definition: circuitlist.c:1724
circuit_t * circuit_get_by_circid_channel_even_if_marked(circid_t circ_id, channel_t *chan)
Definition: circuitlist.c:1532
STATIC size_t n_cells_in_circ_queues(const circuit_t *c)
Definition: circuitlist.c:2503
const char * circuit_state_to_string(int state)
Definition: circuitlist.c:760
int circuit_any_opened_circuits(void)
Definition: circuitlist.c:716
#define STATIC
Definition: testsupport.h:32
or_circuit_t * TO_OR_CIRCUIT(circuit_t *)
Definition: circuitlist.c:154
STATIC uint32_t circuit_max_queued_item_age(const circuit_t *c, uint32_t now)
Definition: circuitlist.c:2616
void circuit_clear_testing_cell_stats(circuit_t *circ)
Definition: circuitlist.c:1109
circuit_t * circuit_get_by_edge_conn(edge_connection_t *conn)
Definition: circuitlist.c:1578
void channel_mark_circid_unusable(channel_t *chan, circid_t id)
Definition: circuitlist.c:353
int circuit_count_pending_on_channel(channel_t *chan)
Definition: circuitlist.c:607
void circuit_set_state(circuit_t *circ, uint8_t state)
Definition: circuitlist.c:543
origin_circuit_t * circuit_get_next_by_pk_and_purpose(origin_circuit_t *start, const uint8_t *digest, uint8_t purpose)
Definition: circuitlist.c:1810
origin_circuit_t * circuit_find_to_cannibalize(uint8_t purpose, extend_info_t *info, int flags)
Definition: circuitlist.c:1903
void circuits_handle_oom(size_t current_allocation)
Definition: circuitlist.c:2670
smartlist_t * circuit_find_circuits_to_upgrade_from_guard_wait(void)
Definition: circuitlist.c:2013
int circuit_get_cpath_opened_len(const origin_circuit_t *)
Definition: circuitlist.c:2057
Header file containing circuit and connection identifier data for the whole HS subsytem.
STATIC uint32_t circuit_max_queued_data_age(const circuit_t *c, uint32_t now)
Definition: circuitlist.c:2601
void circuit_free_all(void)
Definition: circuitlist.c:1297
const char * circuit_purpose_to_string(uint8_t purpose)
Definition: circuitlist.c:901
smartlist_t * circuit_get_global_list(void)
Definition: circuitlist.c:692
const char * circuit_purpose_to_controller_hs_state_string(uint8_t purpose)
Definition: circuitlist.c:841
STATIC void circuit_free_(circuit_t *circ)
Definition: circuitlist.c:1122
void channel_note_destroy_pending(channel_t *chan, circid_t id)
Definition: circuitlist.c:409
void circuit_unlink_all_from_channel(channel_t *chan, int reason)
Definition: circuitlist.c:1595
STATIC uint32_t circuit_max_queued_cell_age(const circuit_t *c, uint32_t now)
Definition: circuitlist.c:2536
void channel_note_destroy_not_pending(channel_t *chan, circid_t id)
Definition: circuitlist.c:429
crypt_path_t * circuit_get_cpath_hop(origin_circuit_t *circ, int hopnum)
Definition: circuitlist.c:2077
int circuit_get_cpath_len(origin_circuit_t *circ)
Definition: circuitlist.c:2041
void circuit_clear_cpath(origin_circuit_t *circ)
Definition: circuitlist.c:1273
uint32_t circid_t
Definition: or.h:608
void circuit_get_all_pending_on_channel(smartlist_t *out, channel_t *chan)
Definition: circuitlist.c:576
Macros to implement mocking and selective exposure for the test code.
void assert_circuit_ok(const circuit_t *c)
Definition: circuitlist.c:2793
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
int circuit_any_opened_circuits_cached(void)
Definition: circuitlist.c:753
origin_circuit_t * circuit_get_by_global_id(uint32_t id)
Definition: circuitlist.c:1425
Header file for ocirc_event.c.
void circuit_close_all_marked(void)
Definition: circuitlist.c:660
int circuit_event_status(origin_circuit_t *circ, circuit_status_event_t tp, int reason_code)
Definition: circuitlist.c:499
circuit_t * circuit_get_by_circid_channel(circid_t circ_id, channel_t *chan)
Definition: circuitlist.c:1517
circuit_channel_direction_t
Definition: or.h:494
origin_circuit_t * origin_circuit_new(void)
Definition: circuitlist.c:1016
circuit_status_event_t
Definition: ocirc_event.h:19
int circuit_id_in_use_on_channel(circid_t circ_id, channel_t *chan)
Definition: circuitlist.c:1546