Tor  0.4.8.0-alpha-dev
circuit_st.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-2021, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
6 
7 /**
8  * @file circuit_st.h
9  * @brief Base circuit structure.
10  **/
11 
12 #ifndef CIRCUIT_ST_H
13 #define CIRCUIT_ST_H
14 
15 #include "core/or/or.h"
16 
17 #include "lib/container/handles.h"
18 
19 #include "core/or/cell_queue_st.h"
20 #include "ext/ht.h"
21 
22 struct hs_token_t;
26 
27 /** Number of padding state machines on a circuit. */
28 #define CIRCPAD_MAX_MACHINES (2)
29 
30 /** "magic" value for an origin_circuit_t */
31 #define ORIGIN_CIRCUIT_MAGIC 0x35315243u
32 /** "magic" value for an or_circuit_t */
33 #define OR_CIRCUIT_MAGIC 0x98ABC04Fu
34 /** "magic" value for a circuit that would have been freed by circuit_free,
35  * but which we're keeping around until a cpuworker reply arrives. See
36  * circuit_free() for more documentation. */
37 #define DEAD_CIRCUIT_MAGIC 0xdeadc14c
38 
39 /**
40  * A circuit is a path over the onion routing
41  * network. Applications can connect to one end of the circuit, and can
42  * create exit connections at the other end of the circuit. AP and exit
43  * connections have only one circuit associated with them (and thus these
44  * connection types are closed when the circuit is closed), whereas
45  * OR connections multiplex many circuits at once, and stay standing even
46  * when there are no circuits running over them.
47  *
48  * A circuit_t structure can fill one of two roles. First, a or_circuit_t
49  * links two connections together: either an edge connection and an OR
50  * connection, or two OR connections. (When joined to an OR connection, a
51  * circuit_t affects only cells sent to a particular circID on that
52  * connection. When joined to an edge connection, a circuit_t affects all
53  * data.)
54 
55  * Second, an origin_circuit_t holds the cipher keys and state for sending data
56  * along a given circuit. At the OP, it has a sequence of ciphers, each
57  * of which is shared with a single OR along the circuit. Separate
58  * ciphers are used for data going "forward" (away from the OP) and
59  * "backward" (towards the OP). At the OR, a circuit has only two stream
60  * ciphers: one for data going forward, and one for data going backward.
61  */
62 struct circuit_t {
63  uint32_t magic; /**< For memory and type debugging: must equal
64  * ORIGIN_CIRCUIT_MAGIC or OR_CIRCUIT_MAGIC. */
65 
66  /** Handle entry for handle-based lookup */
68 
69  /** The channel that is next in this circuit. */
71 
72  /**
73  * The circuit_id used in the next (forward) hop of this circuit;
74  * this is unique to n_chan, but this ordered pair is globally
75  * unique:
76  *
77  * (n_chan->global_identifier, n_circ_id)
78  */
80 
81  /** Queue of cells waiting to be transmitted on n_chan */
83 
84  /**
85  * The hop to which we want to extend this circuit. Should be NULL if
86  * the circuit has attached to a channel.
87  */
89 
90  /** True iff we are waiting for n_chan_cells to become less full before
91  * allowing p_streams to add any more cells. (Origin circuit only.) */
92  unsigned int streams_blocked_on_n_chan : 1;
93  /** True iff we are waiting for p_chan_cells to become less full before
94  * allowing n_streams to add any more cells. (OR circuit only.) */
95  unsigned int streams_blocked_on_p_chan : 1;
96 
97  /** True iff we have queued a delete backwards on this circuit, but not put
98  * it on the output buffer. */
99  unsigned int p_delete_pending : 1;
100  /** True iff we have queued a delete forwards on this circuit, but not put
101  * it on the output buffer. */
102  unsigned int n_delete_pending : 1;
103 
104  /** True iff this circuit has received a DESTROY cell in either direction */
105  unsigned int received_destroy : 1;
106 
107  /** True iff we have sent a sufficiently random data cell since last
108  * we reset send_randomness_after_n_cells. */
110 
111  uint8_t state; /**< Current status of this circuit. */
112  uint8_t purpose; /**< Why are we creating this circuit? */
113 
114  /** How many relay data cells can we package (read from edge streams)
115  * on this circuit before we receive a circuit-level sendme cell asking
116  * for more? */
118  /** How many relay data cells will we deliver (write to edge streams)
119  * on this circuit? When deliver_window gets low, we send some
120  * circuit-level sendme cells to indicate that we're willing to accept
121  * more. */
123  /**
124  * How many cells do we have until we need to send one that contains
125  * sufficient randomness? Used to ensure that authenticated SENDME cells
126  * will reflect some unpredictable information.
127  **/
129 
130  /** FIFO containing the digest of the cells that are just before a SENDME is
131  * sent by the client. It is done at the last cell before our package_window
132  * goes down to 0 which is when we expect a SENDME.
133  *
134  * Our current circuit package window is capped to 1000
135  * (CIRCWINDOW_START_MAX) which is also the start value. The increment is
136  * set to 100 (CIRCWINDOW_INCREMENT) which means we don't allow more than
137  * 1000/100 = 10 outstanding SENDME cells worth of data. Meaning that this
138  * list can not contain more than 10 digests of DIGEST_LEN bytes (20).
139  *
140  * At position i in the list, the digest corresponds to the
141  * (CIRCWINDOW_INCREMENT * i)-nth cell received since we expect a SENDME to
142  * be received containing that cell digest.
143  *
144  * For example, position 2 (starting at 0) means that we've received 300
145  * cells so the 300th cell digest is kept at index 2.
146  *
147  * At maximum, this list contains 200 bytes plus the smartlist overhead. */
149 
150  /** Temporary field used during circuits_handle_oom. */
151  uint32_t age_tmp;
152 
153  /** For storage while n_chan is pending (state CIRCUIT_STATE_CHAN_WAIT). */
155 
156  /** When did circuit construction actually begin (ie send the
157  * CREATE cell or begin cannibalization).
158  *
159  * Note: This timer will get reset if we decide to cannibalize
160  * a circuit. It may also get reset during certain phases of hidden
161  * service circuit use.
162  *
163  * We keep this timestamp with a higher resolution than most so that the
164  * circuit-build-time tracking code can get millisecond resolution.
165  */
166  struct timeval timestamp_began;
167 
168  /** This timestamp marks when the init_circuit_base constructor ran. */
169  struct timeval timestamp_created;
170 
171  /** When the circuit was first used, or 0 if the circuit is clean.
172  *
173  * XXXX Note that some code will artificially adjust this value backward
174  * in time in order to indicate that a circuit shouldn't be used for new
175  * streams, but that it can stay alive as long as it has streams on it.
176  * That's a kludge we should fix.
177  *
178  * XXX The CBT code uses this field to record when HS-related
179  * circuits entered certain states. This usage probably won't
180  * interfere with this field's primary purpose, but we should
181  * document it more thoroughly to make sure of that.
182  *
183  * XXX The SocksPort option KeepaliveIsolateSOCKSAuth will artificially
184  * adjust this value forward each time a suitable stream is attached to an
185  * already constructed circuit, potentially keeping the circuit alive
186  * indefinitely.
187  */
189 
190  uint16_t marked_for_close; /**< Should we close this circuit at the end of
191  * the main loop? (If true, holds the line number
192  * where this circuit was marked.) */
193  const char *marked_for_close_file; /**< For debugging: in which file was this
194  * circuit marked for close? */
195  /** For what reason (See END_CIRC_REASON...) is this circuit being closed?
196  * This field is set in circuit_mark_for_close and used later in
197  * circuit_about_to_free. */
199  /** As marked_for_close_reason, but reflects the underlying reason for
200  * closing this circuit.
201  */
203 
204  /** Unique ID for measuring tunneled network status requests. */
205  uint64_t dirreq_id;
206 
207  /** Index in smartlist of all circuits (global_circuitlist). */
209 
210  /** Various statistics about cells being added to or removed from this
211  * circuit's queues; used only if CELL_STATS events are enabled and
212  * cleared after being sent to control port. */
214 
215  /** If set, points to an HS token that this circuit might be carrying.
216  * Used by the HS circuitmap. */
217  struct hs_token_t *hs_token;
218  /** Hashtable node: used to look up the circuit by its HS token using the HS
219  circuitmap. */
220  HT_ENTRY(circuit_t) hs_circuitmap_node;
221 
222  /** Adaptive Padding state machines: these are immutable. The state machines
223  * that come from the consensus are saved to a global structure, to avoid
224  * per-circuit allocations. This merely points to the global copy in
225  * origin_padding_machines or relay_padding_machines that should never
226  * change or get deallocated.
227  *
228  * Each element of this array corresponds to a different padding machine,
229  * and we can have up to CIRCPAD_MAX_MACHINES such machines. */
231 
232  /** Adaptive Padding machine runtime info for above machines. This is
233  * the per-circuit mutable information, such as the current state and
234  * histogram token counts. Some of it is optional (aka NULL).
235  * If a machine is being shut down, these indexes can be NULL
236  * without the corresponding padding_machine being NULL, while we
237  * wait for the other end to respond to our shutdown request.
238  *
239  * Each element of this array corresponds to a different padding machine,
240  * and we can have up to CIRCPAD_MAX_MACHINES such machines. */
242 
243  /** padding_machine_ctr increments each time a new padding machine
244  * is negotiated. It is used for shutdown conditions, to ensure
245  * that STOP commands actually correspond to the current machine,
246  * and not a previous one. */
248 
249  /** Congestion control fields */
251 };
252 
253 #endif /* !defined(CIRCUIT_ST_H) */
Cell queue structures.
#define CIRCPAD_MAX_MACHINES
Definition: circuit_st.h:28
Macros for C weak-handle implementation.
Master header file for Tor-specific functionality.
uint32_t circid_t
Definition: or.h:488
uint32_t age_tmp
Definition: circuit_st.h:151
unsigned int p_delete_pending
Definition: circuit_st.h:99
struct hs_token_t * hs_token
Definition: circuit_st.h:217
int marked_for_close_reason
Definition: circuit_st.h:198
uint8_t state
Definition: circuit_st.h:111
int global_circuitlist_idx
Definition: circuit_st.h:208
int marked_for_close_orig_reason
Definition: circuit_st.h:202
uint16_t send_randomness_after_n_cells
Definition: circuit_st.h:128
struct create_cell_t * n_chan_create_cell
Definition: circuit_st.h:154
unsigned int have_sent_sufficiently_random_cell
Definition: circuit_st.h:109
unsigned int streams_blocked_on_n_chan
Definition: circuit_st.h:92
uint64_t dirreq_id
Definition: circuit_st.h:205
time_t timestamp_dirty
Definition: circuit_st.h:188
cell_queue_t n_chan_cells
Definition: circuit_st.h:82
uint32_t magic
Definition: circuit_st.h:63
struct circpad_machine_runtime_t * padding_info[CIRCPAD_MAX_MACHINES]
Definition: circuit_st.h:241
smartlist_t * sendme_last_digests
Definition: circuit_st.h:148
unsigned int received_destroy
Definition: circuit_st.h:105
uint16_t marked_for_close
Definition: circuit_st.h:190
const struct circpad_machine_spec_t * padding_machine[CIRCPAD_MAX_MACHINES]
Definition: circuit_st.h:230
uint8_t purpose
Definition: circuit_st.h:112
const char * marked_for_close_file
Definition: circuit_st.h:193
uint32_t padding_machine_ctr
Definition: circuit_st.h:247
unsigned int n_delete_pending
Definition: circuit_st.h:102
HT_ENTRY(circuit_t) hs_circuitmap_node
struct timeval timestamp_began
Definition: circuit_st.h:166
int deliver_window
Definition: circuit_st.h:122
int package_window
Definition: circuit_st.h:117
HANDLE_ENTRY(circuit, circuit_t)
smartlist_t * testing_cell_stats
Definition: circuit_st.h:213
struct timeval timestamp_created
Definition: circuit_st.h:169
unsigned int streams_blocked_on_p_chan
Definition: circuit_st.h:95
channel_t * n_chan
Definition: circuit_st.h:70
extend_info_t * n_hop
Definition: circuit_st.h:88
circid_t n_circ_id
Definition: circuit_st.h:79
struct congestion_control_t * ccontrol
Definition: circuit_st.h:250