1 /* Copyright (c) 2019, The Tor Project, Inc. */
2 /* See LICENSE for licensing information */
6 * \brief Code that is related to SENDME cells both in terms of
7 * creating/parsing cells and handling the content.
10 #define SENDME_PRIVATE
12 #include "core/or/or.h"
14 #include "app/config/config.h"
15 #include "core/mainloop/connection.h"
16 #include "core/or/cell_st.h"
17 #include "core/or/circuitlist.h"
18 #include "core/or/circuituse.h"
19 #include "core/or/or_circuit_st.h"
20 #include "core/or/relay.h"
21 #include "core/or/sendme.h"
22 #include "feature/nodelist/networkstatus.h"
23 #include "lib/ctime/di_ops.h"
24 #include "trunnel/sendme.h"
26 /* The maximum supported version. Above that value, the cell can't be
27 * recognized as a valid SENDME. */
28 #define SENDME_MAX_SUPPORTED_VERSION 1
30 /* The cell version constants for when emitting a cell. */
31 #define SENDME_EMIT_MIN_VERSION_DEFAULT 0
32 #define SENDME_EMIT_MIN_VERSION_MIN 0
33 #define SENDME_EMIT_MIN_VERSION_MAX UINT8_MAX
35 /* The cell version constants for when accepting a cell. */
36 #define SENDME_ACCEPT_MIN_VERSION_DEFAULT 0
37 #define SENDME_ACCEPT_MIN_VERSION_MIN 0
38 #define SENDME_ACCEPT_MIN_VERSION_MAX UINT8_MAX
40 /* Return the minimum version given by the consensus (if any) that should be
41 * used when emitting a SENDME cell. */
43 get_emit_min_version(void)
45 return networkstatus_get_param(NULL
, "sendme_emit_min_version",
46 SENDME_EMIT_MIN_VERSION_DEFAULT
,
47 SENDME_EMIT_MIN_VERSION_MIN
,
48 SENDME_EMIT_MIN_VERSION_MAX
);
51 /* Return the minimum version given by the consensus (if any) that should be
52 * accepted when receiving a SENDME cell. */
54 get_accept_min_version(void)
56 return networkstatus_get_param(NULL
, "sendme_accept_min_version",
57 SENDME_ACCEPT_MIN_VERSION_DEFAULT
,
58 SENDME_ACCEPT_MIN_VERSION_MIN
,
59 SENDME_ACCEPT_MIN_VERSION_MAX
);
62 /* Return true iff the given cell digest matches the first digest in the
63 * circuit sendme list. */
65 v1_digest_matches(const circuit_t
*circ
, const uint8_t *cell_digest
)
68 uint8_t *circ_digest
= NULL
;
71 tor_assert(cell_digest
);
73 /* We shouldn't have received a SENDME if we have no digests. Log at
74 * protocol warning because it can be tricked by sending many SENDMEs
75 * without prior data cell. */
76 if (circ
->sendme_last_digests
== NULL
||
77 smartlist_len(circ
->sendme_last_digests
) == 0) {
78 log_fn(LOG_PROTOCOL_WARN
, LD_PROTOCOL
,
79 "We received a SENDME but we have no cell digests to match. "
84 /* Pop the first element that was added (FIFO) and compare it. */
85 circ_digest
= smartlist_get(circ
->sendme_last_digests
, 0);
86 smartlist_del_keeporder(circ
->sendme_last_digests
, 0);
88 /* Compare the digest with the one in the SENDME. This cell is invalid
89 * without a perfect match. */
90 if (tor_memneq(circ_digest
, cell_digest
, TRUNNEL_SENDME_V1_DIGEST_LEN
)) {
91 log_fn(LOG_PROTOCOL_WARN
, LD_PROTOCOL
,
92 "SENDME v1 cell digest do not match.");
95 /* Digests matches! */
99 /* This digest was popped from the circuit list. Regardless of what happens,
100 * we have no more use for it. */
101 tor_free(circ_digest
);
105 /* Return true iff the given decoded SENDME version 1 cell is valid and
106 * matches the expected digest on the circuit.
108 * Validation is done by comparing the digest in the cell from the previous
109 * cell we saw which tells us that the other side has in fact seen that cell.
110 * See proposal 289 for more details. */
112 cell_v1_is_valid(const sendme_cell_t
*cell
, const circuit_t
*circ
)
117 const uint8_t *cell_digest
= sendme_cell_getconstarray_data_v1_digest(cell
);
118 return v1_digest_matches(circ
, cell_digest
);
121 /* Return true iff the given cell version can be handled or if the minimum
122 * accepted version from the consensus is known to us. */
124 cell_version_is_valid(uint8_t cell_version
)
126 int accept_version
= get_accept_min_version();
128 /* Can we handle this version? */
129 if (accept_version
> SENDME_MAX_SUPPORTED_VERSION
) {
130 log_fn(LOG_PROTOCOL_WARN
, LD_PROTOCOL
,
131 "Unable to handle SENDME version %u. We only support <= %d "
132 "(from consensus). Probably your tor is too old?",
133 accept_version
, cell_version
);
137 /* We only accept a SENDME cell from what the consensus tells us. */
138 if (cell_version
< accept_version
) {
139 log_info(LD_PROTOCOL
, "Unacceptable SENDME version %d. Only "
140 "accepting %u (taken from the consensus). "
142 cell_version
, accept_version
);
151 /* Return true iff the encoded SENDME cell in cell_payload of length
152 * cell_payload_len is valid. For each version:
155 * 1: Authenticated with last cell digest.
157 * This is the main critical function to make sure we can continue to
158 * send/recv cells on a circuit. If the SENDME is invalid, the circuit should
159 * be mark for close. */
161 sendme_is_valid(const circuit_t
*circ
, const uint8_t *cell_payload
,
162 size_t cell_payload_len
)
164 uint8_t cell_version
;
165 sendme_cell_t
*cell
= NULL
;
168 tor_assert(cell_payload
);
170 /* An empty payload means version 0 so skip trunnel parsing. We won't be
171 * able to parse a 0 length buffer into a valid SENDME cell. */
172 if (cell_payload_len
== 0) {
175 /* First we'll decode the cell so we can get the version. */
176 if (sendme_cell_parse(&cell
, cell_payload
, cell_payload_len
) < 0) {
177 log_fn(LOG_PROTOCOL_WARN
, LD_PROTOCOL
,
178 "Unparseable SENDME cell received. Closing circuit.");
181 cell_version
= sendme_cell_get_version(cell
);
184 /* Validate that we can handle this cell version. */
185 if (!cell_version_is_valid(cell_version
)) {
189 /* Validate depending on the version now. */
190 switch (cell_version
) {
192 if (!cell_v1_is_valid(cell
, circ
)) {
197 /* Fallthrough. Version 0, there is no work to be done on the payload so
198 * it is necessarily valid if we pass the version validation. */
200 /* Unknown version means we can't handle it so fallback to version 0. */
205 sendme_cell_free(cell
);
208 sendme_cell_free(cell
);
212 /* Build and encode a version 1 SENDME cell into payload, which must be at
213 * least of RELAY_PAYLOAD_SIZE bytes, using the digest for the cell data.
215 * Return the size in bytes of the encoded cell in payload. A negative value
216 * is returned on encoding failure. */
218 build_cell_payload_v1(crypto_digest_t
*cell_digest
, uint8_t *payload
)
221 sendme_cell_t
*cell
= NULL
;
223 tor_assert(cell_digest
);
226 cell
= sendme_cell_new();
228 /* Building a payload for version 1. */
229 sendme_cell_set_version(cell
, 0x01);
230 /* Set the data length field for v1. */
231 sendme_cell_set_data_len(cell
, TRUNNEL_SENDME_V1_DIGEST_LEN
);
233 /* Copy the digest into the data payload. */
234 crypto_digest_get_digest(cell_digest
,
235 (char *) sendme_cell_getarray_data_v1_digest(cell
),
236 sendme_cell_get_data_len(cell
));
238 /* Finally, encode the cell into the payload. */
239 len
= sendme_cell_encode(payload
, RELAY_PAYLOAD_SIZE
, cell
);
241 sendme_cell_free(cell
);
245 /* Send a circuit-level SENDME on the given circuit using the layer_hint if
246 * not NULL. The digest is only used for version 1.
248 * Return 0 on success else a negative value and the circuit will be closed
249 * because we failed to send the cell on it. */
251 send_circuit_level_sendme(circuit_t
*circ
, crypt_path_t
*layer_hint
,
252 crypto_digest_t
*cell_digest
)
254 uint8_t emit_version
;
255 uint8_t payload
[RELAY_PAYLOAD_SIZE
];
259 tor_assert(cell_digest
);
261 emit_version
= get_emit_min_version();
262 switch (emit_version
) {
264 payload_len
= build_cell_payload_v1(cell_digest
, payload
);
265 if (BUG(payload_len
< 0)) {
266 /* Unable to encode the cell, abort. We can recover from this by closing
267 * the circuit but in theory it should never happen. */
270 log_debug(LD_PROTOCOL
, "Emitting SENDME version 1 cell.");
273 /* Fallthrough because default is to use v0. */
275 /* Unknown version, fallback to version 0 meaning no payload. */
280 if (relay_send_command_from_edge(0, circ
, RELAY_COMMAND_SENDME
,
281 (char *) payload
, payload_len
,
284 "SENDME relay_send_command_from_edge failed. Circuit's closed.");
285 return -1; /* the circuit's closed, don't continue */
290 /** Called when we've just received a relay data cell, when we've just
291 * finished flushing all bytes to stream <b>conn</b>, or when we've flushed
292 * *some* bytes to the stream <b>conn</b>.
294 * If conn->outbuf is not too full, and our deliver window is low, send back a
295 * suitable number of stream-level sendme cells.
298 sendme_connection_edge_consider_sending(edge_connection_t
*conn
)
302 int log_domain
= TO_CONN(conn
)->type
== CONN_TYPE_AP
? LD_APP
: LD_EXIT
;
304 /* Don't send it if we still have data to deliver. */
305 if (connection_outbuf_too_full(TO_CONN(conn
))) {
309 if (circuit_get_by_edge_conn(conn
) == NULL
) {
310 /* This can legitimately happen if the destroy has already arrived and
311 * torn down the circuit. */
312 log_info(log_domain
, "No circuit associated with edge connection. "
313 "Skipping sending SENDME.");
317 while (conn
->deliver_window
<=
318 (STREAMWINDOW_START
- STREAMWINDOW_INCREMENT
)) {
319 log_debug(log_domain
, "Outbuf %" TOR_PRIuSZ
", queuing stream SENDME.",
320 TO_CONN(conn
)->outbuf_flushlen
);
321 conn
->deliver_window
+= STREAMWINDOW_INCREMENT
;
322 if (connection_edge_send_command(conn
, RELAY_COMMAND_SENDME
,
324 log_warn(LD_BUG
, "connection_edge_send_command failed while sending "
325 "a SENDME. Circuit probably closed, skipping.");
326 goto end
; /* The circuit's closed, don't continue */
334 /** Check if the deliver_window for circuit <b>circ</b> (at hop
335 * <b>layer_hint</b> if it's defined) is low enough that we should
336 * send a circuit-level sendme back down the circuit. If so, send
337 * enough sendmes that the window would be overfull if we sent any
341 sendme_circuit_consider_sending(circuit_t
*circ
, crypt_path_t
*layer_hint
)
343 crypto_digest_t
*digest
;
345 while ((layer_hint
? layer_hint
->deliver_window
: circ
->deliver_window
) <=
346 CIRCWINDOW_START
- CIRCWINDOW_INCREMENT
) {
347 log_debug(LD_CIRC
,"Queuing circuit sendme.");
349 layer_hint
->deliver_window
+= CIRCWINDOW_INCREMENT
;
350 digest
= layer_hint
->crypto
.sendme_digest
;
352 circ
->deliver_window
+= CIRCWINDOW_INCREMENT
;
353 digest
= TO_OR_CIRCUIT(circ
)->crypto
.sendme_digest
;
355 if (send_circuit_level_sendme(circ
, layer_hint
, digest
) < 0) {
356 return; /* The circuit's closed, don't continue */
361 /* Process a circuit-level SENDME cell that we just received. The layer_hint,
362 * if not NULL, is the Exit hop of the connection which means that we are a
363 * client. In that case, circ must be an origin circuit. The cell_body_len is
364 * the length of the SENDME cell payload (excluding the header). The
365 * cell_payload is the payload.
367 * Return 0 on success that is the SENDME is valid and the package window has
368 * been updated properly.
370 * On error, a negative value is returned which indicate that the circuit must
371 * be closed using the value as the reason for it. */
373 sendme_process_circuit_level(crypt_path_t
*layer_hint
,
374 circuit_t
*circ
, const uint8_t *cell_payload
,
375 uint16_t cell_payload_len
)
378 tor_assert(cell_payload
);
380 /* If we are the origin of the circuit, we are the Client so we use the
381 * layer hint (the Exit hop) for the package window tracking. */
382 if (CIRCUIT_IS_ORIGIN(circ
)) {
383 if ((layer_hint
->package_window
+ CIRCWINDOW_INCREMENT
) >
384 CIRCWINDOW_START_MAX
) {
385 static struct ratelim_t exit_warn_ratelim
= RATELIM_INIT(600);
386 log_fn_ratelim(&exit_warn_ratelim
, LOG_WARN
, LD_PROTOCOL
,
387 "Unexpected sendme cell from exit relay. "
389 return -END_CIRC_REASON_TORPROTOCOL
;
391 layer_hint
->package_window
+= CIRCWINDOW_INCREMENT
;
392 log_debug(LD_APP
, "circ-level sendme at origin, packagewindow %d.",
393 layer_hint
->package_window
);
395 /* We count circuit-level sendme's as valid delivered data because they
396 * are rate limited. */
397 circuit_read_valid_data(TO_ORIGIN_CIRCUIT(circ
), cell_payload_len
);
399 /* Validate the SENDME cell. Depending on the version, different
400 * validation can be done. An invalid SENDME requires us to close the
401 * circuit. It is only done if we are the Exit of the circuit. */
402 if (!sendme_is_valid(circ
, cell_payload
, cell_payload_len
)) {
403 return -END_CIRC_REASON_TORPROTOCOL
;
406 /* We aren't the origin of this circuit so we are the Exit and thus we
407 * track the package window with the circuit object. */
408 if ((circ
->package_window
+ CIRCWINDOW_INCREMENT
) >
409 CIRCWINDOW_START_MAX
) {
410 static struct ratelim_t client_warn_ratelim
= RATELIM_INIT(600);
411 log_fn_ratelim(&client_warn_ratelim
, LOG_PROTOCOL_WARN
, LD_PROTOCOL
,
412 "Unexpected sendme cell from client. "
413 "Closing circ (window %d).", circ
->package_window
);
414 return -END_CIRC_REASON_TORPROTOCOL
;
416 circ
->package_window
+= CIRCWINDOW_INCREMENT
;
417 log_debug(LD_EXIT
, "circ-level sendme at non-origin, packagewindow %d.",
418 circ
->package_window
);
424 /* Process a stream-level SENDME cell that we just received. The conn is the
425 * edge connection (stream) that the circuit circ is associated with. The
426 * cell_body_len is the length of the payload (excluding the header).
428 * Return 0 on success that is the SENDME is valid and the package window has
429 * been updated properly.
431 * On error, a negative value is returned which indicate that the circuit must
432 * be closed using the value as the reason for it. */
434 sendme_process_stream_level(edge_connection_t
*conn
, circuit_t
*circ
,
435 uint16_t cell_body_len
)
440 /* Don't allow the other endpoint to request more than our maximum (i.e.
441 * initial) stream SENDME window worth of data. Well-behaved stock clients
442 * will not request more than this max (as per the check in the while loop
443 * of sendme_connection_edge_consider_sending()). */
444 if ((conn
->package_window
+ STREAMWINDOW_INCREMENT
) >
445 STREAMWINDOW_START_MAX
) {
446 static struct ratelim_t stream_warn_ratelim
= RATELIM_INIT(600);
447 log_fn_ratelim(&stream_warn_ratelim
, LOG_PROTOCOL_WARN
, LD_PROTOCOL
,
448 "Unexpected stream sendme cell. Closing circ (window %d).",
449 conn
->package_window
);
450 return -END_CIRC_REASON_TORPROTOCOL
;
452 /* At this point, the stream sendme is valid */
453 conn
->package_window
+= STREAMWINDOW_INCREMENT
;
455 /* We count circuit-level sendme's as valid delivered data because they are
457 if (CIRCUIT_IS_ORIGIN(circ
)) {
458 circuit_read_valid_data(TO_ORIGIN_CIRCUIT(circ
), cell_body_len
);
461 log_debug(CIRCUIT_IS_ORIGIN(circ
) ? LD_APP
: LD_EXIT
,
462 "stream-level sendme, package_window now %d.",
463 conn
->package_window
);
467 /* Called when a relay DATA cell is received on the given circuit. If
468 * layer_hint is NULL, this means we are the Exit end point else we are the
469 * Client. Update the deliver window and return its new value. */
471 sendme_circuit_data_received(circuit_t
*circ
, crypt_path_t
*layer_hint
)
473 int deliver_window
, domain
;
475 if (CIRCUIT_IS_ORIGIN(circ
)) {
476 tor_assert(layer_hint
);
477 --layer_hint
->deliver_window
;
478 deliver_window
= layer_hint
->deliver_window
;
481 tor_assert(!layer_hint
);
482 --circ
->deliver_window
;
483 deliver_window
= circ
->deliver_window
;
487 log_debug(domain
, "Circuit deliver_window now %d.", deliver_window
);
488 return deliver_window
;
491 /* Called when a relay DATA cell is received for the given edge connection
492 * conn. Update the deliver window and return its new value. */
494 sendme_stream_data_received(edge_connection_t
*conn
)
497 return --conn
->deliver_window
;
500 /* Called when a relay DATA cell is packaged on the given circuit. If
501 * layer_hint is NULL, this means we are the Exit end point else we are the
502 * Client. Update the package window and return its new value. */
504 sendme_note_circuit_data_packaged(circuit_t
*circ
, crypt_path_t
*layer_hint
)
506 int package_window
, domain
;
510 if (CIRCUIT_IS_ORIGIN(circ
)) {
512 tor_assert(layer_hint
);
513 --layer_hint
->package_window
;
514 package_window
= layer_hint
->package_window
;
518 tor_assert(!layer_hint
);
519 --circ
->package_window
;
520 package_window
= circ
->package_window
;
524 log_debug(domain
, "Circuit package_window now %d.", package_window
);
525 return package_window
;
528 /* Called when a relay DATA cell is packaged for the given edge connection
529 * conn. Update the package window and return its new value. */
531 sendme_note_stream_data_packaged(edge_connection_t
*conn
)
534 return --conn
->package_window
;
537 /* Note the cell digest in the circuit sendme last digests FIFO if applicable.
538 * It is safe to pass a circuit that isn't meant to track those digests. */
540 sendme_note_cell_digest(circuit_t
*circ
)
546 /* We only keep the cell digest if we are the Exit on that circuit and if
547 * this cell is the last one before the client should send a SENDME. */
548 if (CIRCUIT_IS_ORIGIN(circ
)) {
551 /* Is this the last cell before a SENDME? The idea is that if the
552 * package_window reaches a multiple of the increment, after this cell, we
553 * should expect a SENDME. */
554 if (((circ
->package_window
- 1) % CIRCWINDOW_INCREMENT
) != 0) {
558 /* Only note the digest if we actually have the digest of the previous cell
559 * recorded. It should never happen in theory as we always record the last
560 * digest for the v1 SENDME. */
561 if (TO_OR_CIRCUIT(circ
)->crypto
.sendme_digest
) {
562 digest
= tor_malloc_zero(TRUNNEL_SENDME_V1_DIGEST_LEN
);
563 crypto_digest_get_digest(TO_OR_CIRCUIT(circ
)->crypto
.sendme_digest
,
564 (char *) digest
, TRUNNEL_SENDME_V1_DIGEST_LEN
);
565 if (circ
->sendme_last_digests
== NULL
) {
566 circ
->sendme_last_digests
= smartlist_new();
568 smartlist_add(circ
->sendme_last_digests
, digest
);