tor_proto/circuit/reactor/backward.rs
1//! A circuit's view of the backward state of the circuit.
2
3use crate::channel::Channel;
4use crate::circuit::UniqId;
5use crate::circuit::cell_sender::CircuitCellSender;
6use crate::circuit::reactor::ControlHandler;
7use crate::circuit::reactor::circhop::CircHopList;
8use crate::circuit::reactor::macros::derive_deftly_template_CircuitReactor;
9use crate::circuit::reactor::stream::ReadyStreamMsg;
10use crate::congestion::{CongestionControl, sendme};
11use crate::crypto::cell::RelayCellBody;
12use crate::util::err::ReactorError;
13use crate::util::poll_all::PollAll;
14use crate::{Error, HopNum, Result};
15
16// TODO(circpad): once padding is stabilized, the padding module will be moved out of client.
17use crate::client::circuit::padding::{
18 self, PaddingController, PaddingEvent, PaddingEventStream, QueuedCellPaddingInfo,
19};
20
21use tor_cell::chancell::msg::{AnyChanMsg, Relay};
22use tor_cell::chancell::{AnyChanCell, BoxedCellBody, ChanCmd, CircId};
23use tor_cell::relaycell::msg::{Sendme, SendmeTag};
24use tor_cell::relaycell::{AnyRelayMsgOuter, RelayCellFormat, RelayCmd, StreamId};
25use tor_rtcompat::{DynTimeProvider, Runtime};
26
27use derive_deftly::Deftly;
28use futures::SinkExt;
29use futures::channel::mpsc;
30use futures::{FutureExt as _, StreamExt, future, select_biased};
31use tracing::{debug, trace};
32
33use std::pin::Pin;
34use std::result::Result as StdResult;
35use std::sync::{Arc, Mutex, RwLock};
36
37use crate::circuit::CircuitRxReceiver;
38
39#[cfg(feature = "circ-padding")]
40use crate::circuit::padding::{CircPaddingDisposition, padding_disposition};
41
42#[cfg(feature = "relay")]
43use tor_cell::relaycell::msg::Extended2;
44
45/// The "backward" circuit reactor of a relay.
46///
47/// See the [`reactor`](crate::circuit::reactor) module-level docs.
48///
49/// Shuts downs down if an error occurs, or if the [`Reactor`](super::Reactor),
50/// [`ForwardReactor`](super::ForwardReactor), or if one of the
51/// [`StreamReactor`](super::stream::StreamReactor)s of this circuit shuts down:
52///
53/// * if the `Reactor` shuts down, we are alerted via the ctrl/command mpsc channels
54/// (their sending ends will close, which causes run_once() to return ReactorError::Shutdown)
55/// * if `ForwardReactor` shuts down, the `Reactor` will notice and will itself shut down,
56/// which, in turn, causes the `BackwardReactor` to shut down as described above
57/// * if one of the `StreamReactor`s shuts down, the `ForwardReactor` will
58/// notice when it next tries to deliver a stream message to it, and shut down,
59/// causing the `BackwardReactor` and top-level `Reactor` to follow suit
60#[derive(Deftly)]
61#[derive_deftly(CircuitReactor)]
62#[deftly(reactor_name = "backward reactor")]
63#[deftly(run_inner_fn = "Self::run_once")]
64#[must_use = "If you don't call run() on a reactor, the circuit won't work."]
65pub(super) struct BackwardReactor<B: BackwardHandler> {
66 /// The time provider.
67 time_provider: DynTimeProvider,
68 /// An identifier for logging about this reactor's circuit.
69 unique_id: UniqId,
70 /// The circuit identifier on the backward Tor channel.
71 circ_id: CircId,
72 /// The inbound Tor channel.
73 channel: Arc<Channel>,
74 /// Implementation-dependent part of the reactor.
75 ///
76 /// This enables us to customize the behavior of the reactor,
77 /// depending on whether we are a client or a relay.
78 inner: B,
79 /// The reading end of the outbound Tor channel, if we are not the last hop.
80 ///
81 /// Yields cells moving from the exit towards the client, if we are a middle relay.
82 outbound_chan_rx: Option<CircuitRxReceiver>,
83 /// The per-hop state, shared with the forward reactor.
84 ///
85 /// The backward reactor acquires a read lock to this whenever it needs to
86 ///
87 /// * send a circuit-level SENDME
88 /// * handle a circuit-level SENDME
89 /// * send a padding cell
90 ///
91 // Note: For the sending/handling of SENDMEs, we lock the hop list
92 // to extract the relay cell format and CC state of the hop.
93 // Technically, for the SENDME cases, we could've avoided locking
94 // the hop list from the BWD, by having the FWD share the relay cell format
95 // and CC state in the BackwardReactorCmd::{Send,Handle}Sendme command.
96 // But for the padding case, we *need* the hop list, because we need
97 // to work out what relay cell format to use when sending the padding cell.
98 // But for the sake of simplicity, I made the BWD consult the CircHopList in all cases.
99 //
100 // TODO: the backward reactor only ever reads from this.
101 // Conceptually, it is the forward reactor's HopMgr that owns this list:
102 // only HopMgr can add hops to the list.
103 //
104 // Perhaps we need a specialized abstraction that only allows reading here.
105 // This could be a wrapper over RwLock, providing a read-only API.
106 hops: Arc<RwLock<CircHopList>>,
107 /// The sending end of the backward Tor channel.
108 ///
109 /// Delivers cells towards the other endpoint: towards the client, if we are a relay,
110 /// or towards the exit, if we are a client.
111 inbound_chan_tx: CircuitCellSender,
112 /// Channel for receiving control commands.
113 command_rx: mpsc::UnboundedReceiver<CtrlCmd<B::CtrlCmd>>,
114 /// Channel for receiving control messages.
115 control_rx: mpsc::UnboundedReceiver<CtrlMsg<B::CtrlMsg>>,
116 /// Receiver for [`BackwardReactorCmd`]s coming from the forward reactor.
117 ///
118 /// The sender is in [`ForwardReactor`](super::ForwardReactor), which will forward all cells
119 /// carrying Tor stream data to us.
120 ///
121 /// This serves a dual purpose:
122 ///
123 /// * it enables the `ForwardReactor` to deliver Tor stream data received
124 /// from the other endpoint
125 /// * it lets the `BackwardReactor` know if the `ForwardReactor` has shut down:
126 /// we select! on this MPSC channel in the main loop, so if the `ForwardReactor`
127 /// shuts down, we will get EOS upon calling `.next()`)
128 forward_reactor_rx: mpsc::Receiver<BackwardReactorCmd>,
129 /// A channel for receiving endpoint-bound stream messages from the StreamReactor(s)
130 /// (the stream messages are client-bound if we are a relay, or exit-bound if we are a client).
131 stream_rx: mpsc::Receiver<ReadyStreamMsg>,
132 /// A padding controller to which padding-related events should be reported.
133 padding_ctrl: PaddingController,
134 /// An event stream telling us about padding-related events.
135 padding_event_stream: PaddingEventStream,
136 /// Current rules for blocking traffic, according to the padding controller.
137 #[cfg(feature = "circ-padding")]
138 padding_block: Option<padding::StartBlocking>,
139}
140
141/// A control message aimed at the generic backward reactor.
142pub(crate) enum CtrlMsg<M> {
143 /// Inform the reactor that there's a flow control update for a given stream.
144 ///
145 /// The reactor will decide how to handle this update depending on the type of flow control and
146 /// the current state of the stream.
147 FlowCtrlUpdate {
148 /// The hop that the stream is on.
149 /// Relay circuits use `None`.
150 hop: Option<HopNum>,
151 /// The stream ID that the update is for.
152 stream_id: StreamId,
153 /// The type of flow control update, and any associated metadata.
154 msg: FlowCtrlMsg,
155 },
156 /// An implementation-dependent control message.
157 #[allow(unused)] // TODO(relay)
158 Custom(M),
159}
160
161/// A control command aimed at the generic backward reactor.
162pub(crate) enum CtrlCmd<C> {
163 /// An implementation-dependent control command.
164 #[allow(unused)] // TODO(relay)
165 Custom(C),
166}
167
168/// Trait for customizing the behavior of the backward reactor.
169///
170/// Used for plugging in the implementation-dependent (client vs relay)
171/// parts of the implementation into the generic one.
172pub(crate) trait BackwardHandler: ControlHandler {
173 /// The subclass of ChanMsg that can arrive on this type of circuit.
174 type CircChanMsg: TryFrom<AnyChanMsg, Error = crate::Error> + Send;
175
176 /// Encrypt a RelayCellBody that is moving in the backward direction.
177 fn encrypt_relay_cell(
178 &mut self,
179 cmd: ChanCmd,
180 body: &mut RelayCellBody,
181 hop: Option<HopNum>,
182 ) -> SendmeTag;
183
184 /// Handle a cell that was read from the Tor outbound channel.
185 ///
186 /// Returns an error if the cell should cause the reactor to shut down,
187 /// or a [`BackwardCellDisposition`] specifying how it should be handled.
188 fn handle_backward_cell(
189 &mut self,
190 circ_uniq_id: UniqId,
191 circ_id: CircId,
192 cell: Self::CircChanMsg,
193 ) -> StdResult<BackwardCellDisposition, ReactorError>;
194}
195
196/// What action to take in response to a cell arriving on our outbound Tor channel.
197pub(crate) enum BackwardCellDisposition {
198 /// Forward the cell, writing it to the inbound Tor channel.
199 Forward(AnyChanMsg),
200}
201
202impl<B: BackwardHandler> BackwardReactor<B> {
203 /// Create a new [`BackwardReactor`].
204 #[allow(clippy::too_many_arguments)] // TODO
205 pub(super) fn new<R: Runtime>(
206 runtime: R,
207 channel: &Arc<Channel>,
208 circ_id: CircId,
209 unique_id: UniqId,
210 inner: B,
211 hops: Arc<RwLock<CircHopList>>,
212 forward_reactor_rx: mpsc::Receiver<BackwardReactorCmd>,
213 control_rx: mpsc::UnboundedReceiver<CtrlMsg<B::CtrlMsg>>,
214 command_rx: mpsc::UnboundedReceiver<CtrlCmd<B::CtrlCmd>>,
215 padding_ctrl: PaddingController,
216 padding_event_stream: PaddingEventStream,
217 stream_rx: mpsc::Receiver<ReadyStreamMsg>,
218 ) -> Self {
219 let channel = Arc::clone(channel);
220 let inbound_chan_tx = CircuitCellSender::from_channel_sender(channel.sender());
221
222 Self {
223 time_provider: DynTimeProvider::new(runtime),
224 outbound_chan_rx: None,
225 channel,
226 inner,
227 hops,
228 inbound_chan_tx,
229 unique_id,
230 circ_id,
231 forward_reactor_rx,
232 control_rx,
233 command_rx,
234 stream_rx,
235 padding_ctrl,
236 padding_event_stream,
237 #[cfg(feature = "circ-padding")]
238 padding_block: None,
239 }
240 }
241
242 /// Helper for [`run`](Self::run).
243 ///
244 /// Handles cells arriving on the outbound Tor channel,
245 /// and writes cells to the inbound Tor channel.
246 ///
247 /// Because the Tor application streams, the `forward_reactor_rx` MPSC streams,
248 /// and the outbound Tor channel MPSC stream are driven concurrently using [`PollAll`],
249 /// this function can send up to 3 cells per call over the inbound Tor channel:
250 ///
251 /// * a cell carrying Tor stream data
252 /// * a cell received from the outbound Tor channel, if we are a relay
253 /// (moving from the exit towards the client)
254 /// * a circuit-level SENDME
255 ///
256 /// However, in practice, leaky pipe is not really used,
257 /// and so relays that have application streams (i.e. the exits),
258 /// are not going to have an outbound Tor channel,
259 /// and so this will only really drive Tor stream data,
260 /// delivering at most 2 cells per call.
261 async fn run_once(&mut self) -> StdResult<(), ReactorError> {
262 /// The maximum number of events we expect to handle per reactor loop.
263 ///
264 /// This is bounded by the number of futures we push into the PollAll.
265 const PER_LOOP_EVENT_COUNT: usize = 3;
266
267 // A collection of futures we plan to drive concurrently.
268 let mut poll_all =
269 PollAll::<PER_LOOP_EVENT_COUNT, Option<CircuitEvent<B::CircChanMsg>>>::new();
270
271 // Flush the backward Tor channel sink, and check it for readiness
272 //
273 // TODO(flushing): here and everywhere else we need to flush:
274 //
275 // Currently, we try to flush every time we want to write to the sink,
276 // but may be suboptimal.
277 //
278 // However, we don't actually *wait* for the flush to complete
279 // (we just make a bit of progress by calling poll_flush),
280 // so it's possible that this is actually tolerable.
281 // We should run some tests, and if this turns out to be a performance bottleneck,
282 // we'll have to rethink our flushing approach.
283 let backward_chan_ready = future::poll_fn(|cx| {
284 // The flush outcome doesn't matter,
285 // so we simply move on to the readiness check.
286 // The reason we don't wait on the flush is because we don't
287 // want to flush on *every* reactor loop, but we do want to make
288 // a bit of progress each time.
289 //
290 // (TODO: do we want to handle errors here?)
291 let _ = self.inbound_chan_tx.poll_flush_unpin(cx);
292
293 self.inbound_chan_tx.poll_ready_unpin(cx)
294 });
295
296 // Concurrently, drive :
297 // 1. a future that reads from the StreamReactor, to see if there are
298 // any application streams that have a message to send
299 // (this resolves to a message that needs to be delivered to the peer)
300 poll_all.push(async {
301 // Internally, each stream reactor checks if we're allowed to send anything
302 // that counts towards SENDME windows (and ceases to send us stream data if not)
303 //
304 // The reason we don't check that here is because stream_rx multiplexes stream data
305 // from all hops, and we have no way of knowing which hop will want to send us stream
306 // data next, and therefore we can't know which hop's CC object to use
307 self.stream_rx.next().await.map(CircuitEvent::Send)
308 });
309
310 // 2. the stream of commands coming from the ForwardReactor
311 // (this resolves to a BackwardReactorCmd)
312 poll_all.push(async {
313 let event = match self.forward_reactor_rx.next().await {
314 Some(cmd) => CircuitEvent::Forwarded(cmd),
315 None => {
316 // The forward reactor has crashed, so we have to shut down.
317 CircuitEvent::ForwardShutdown
318 }
319 };
320
321 Some(event)
322 });
323
324 // 3. Messages moving from the outbound channel towards the inbound Tor channel,
325 // if we have an outbound Tor channel.
326 //
327 // NOTE: in practice, clients and exits won't have an outbound Tor channel,
328 // so for them this will be a no-op.
329 poll_all.push(async {
330 let event = if let Some(outbound_chan_rx) = self.outbound_chan_rx.as_mut() {
331 // Forward channel unexpectedly closed, we should close too
332 match outbound_chan_rx.next().await {
333 Some(msg) => match msg.try_into() {
334 Err(e) => CircuitEvent::ProtoViolation(e),
335 Ok(cell) => CircuitEvent::Cell(cell),
336 },
337 None => {
338 // The forward reactor has crashed, so we have to shut down.
339 CircuitEvent::ForwardShutdown
340 }
341 }
342 } else {
343 future::pending().await
344 };
345
346 Some(event)
347 });
348
349 let poll_all = async move {
350 // Avoid polling **any** of the futures if the outgoing sink is blocked.
351 //
352 // This implements backpressure: we avoid reading from our input sources
353 // if we know we're unable to write to the inbound Tor channel sink.
354 //
355 // More specifically, if our inbound Tor channel sink is full and can no longer
356 // accept cells, we stop reading:
357 //
358 // 1. From the application streams (received from StreamReactor), if there are any.
359 //
360 // 2. From the forward_reactor_rx channel, used by the forward reactor to send us
361 //
362 // - a circuit-level SENDME that we have received, or
363 // - a circuit-level SENDME that we need to deliver to the client
364 //
365 // Not reading from the forward_reactor_rx channel, in turn, causes the forward reactor
366 // to block and therefore stop reading from **its** input sources,
367 // propagating backpressure all the way to the other endpoint of the circuit.
368 //
369 // 3. From the outbound Tor channel, if there is one.
370 //
371 // This will delay any SENDMEs the client or exit might have sent along
372 // the way, and therefore count as a congestion signal.
373 //
374 // TODO: memquota setup to make sure this doesn't turn into a memory DOS vector
375 let _ = backward_chan_ready.await;
376
377 // TODO: it's important to not block reading from the forward_reactor_rx channel on the chan
378 // sender readiness (for instance, we should not block the sending of SENDMEs
379 // if the channel is blocked on a padding-induced block).
380 //
381 // This means we will need to move the forward_reactor_rx handling out of the PollAll
382 // to the select_biased! below.
383 poll_all.await
384 };
385
386 let events = select_biased! {
387 res = self.command_rx.next().fuse() => {
388 let cmd = res.ok_or_else(|| ReactorError::Shutdown)?;
389 self.handle_cmd(cmd)?;
390 return Ok(());
391 }
392 res = self.control_rx.next().fuse() => {
393 let msg = res.ok_or_else(|| ReactorError::Shutdown)?;
394 if let Some(new_msg) = self.handle_msg(msg)? {
395 let mut events = <PollAll::<_, _> as Future>::Output::new();
396 events.push(Some(CircuitEvent::Send(new_msg)));
397 events
398 } else {
399 return Ok(());
400 }
401 }
402 res = self.padding_event_stream.next().fuse() => {
403 // If there's a padding event, we need to handle it immediately,
404 // because it might tell us to start blocking the inbound_chan_tx sink,
405 // which, in turn, means we need to stop trying to read from
406 // the application streams.
407 let event = res.ok_or_else(|| ReactorError::Shutdown)?;
408
409 cfg_if::cfg_if! {
410 if #[cfg(feature = "circ-padding")] {
411 self.run_padding_event(event).await?;
412 } else {
413 // If padding isn't enabled, we never generate a padding event,
414 // so we can be sure this case will never be called.
415 void::unreachable(event.0);
416 }
417 }
418 return Ok(())
419 }
420 res = poll_all.fuse() => res,
421 };
422
423 // Note: there shouldn't be more than N < PER_LOOP_EVENT_COUNT events to handle
424 // per reactor loop. We need to be careful here, because we must avoid blocking
425 // the reactor.
426 //
427 // If handling more than one event per loop turns out to be a problem, we may
428 // need to dispatch this to a background task instead.
429 //
430 // TODO(relay): this loop is actually a problem.
431 // As mentioned in the run_once() docs, this will attempt to send up
432 // to 3 cells on the inbound tor Channel (or 2 cells, assuming no leaky pipe).
433 //
434 // The problem is that the readiness check above (see backward_chan_ready)
435 // only checks that the queue has enough room for 1 cell, not *2 cells*.
436 // Trying to send more than 2 cell when there is only room for one
437 // will cause the reactor to block (and because there is nothing
438 // driving the flushing of this channel, this will be a hard block).
439 //
440 // We need to rethink the strategy here (e.g. by flushing in parallel
441 // with handle_event())
442 for event in events.into_iter().flatten() {
443 self.handle_event(event).await?;
444 }
445
446 Ok(())
447 }
448
449 /// Handle a control command.
450 fn handle_cmd(&mut self, cmd: CtrlCmd<B::CtrlCmd>) -> StdResult<(), ReactorError> {
451 match cmd {
452 CtrlCmd::Custom(c) => self.inner.handle_cmd(c),
453 }
454 }
455
456 /// Handle a control message.
457 ///
458 /// This may result in a new stream message that needs to be sent backward.
459 fn handle_msg(
460 &mut self,
461 msg: CtrlMsg<B::CtrlMsg>,
462 ) -> StdResult<Option<ReadyStreamMsg>, ReactorError> {
463 match msg {
464 CtrlMsg::Custom(c) => {
465 // In the future we may also want `inner.handle_msg(c)` to return an
466 // `Option<ReadyStreamMsg>`, and we can pass it through.
467 let () = self.inner.handle_msg(c)?;
468 Ok(None)
469 }
470 CtrlMsg::FlowCtrlUpdate {
471 hop,
472 stream_id,
473 msg,
474 } => match msg {
475 FlowCtrlMsg::Sendme => {
476 // Congestion control decides if we can send stream level SENDMEs or not.
477 let (cell_fmt, cc) = self.hop_info(hop)?;
478 let uses_stream_sendme = cc.lock().expect("poisoned").uses_stream_sendme();
479
480 if !uses_stream_sendme {
481 // Nothing to do, so discard the SENDME.
482 //
483 // TODO(arti#2068): We should do something better here,
484 // like ensure that nothing sends `FlowCtrlMsg::Sendme` when it shouldn't,
485 // and making this an error instead.
486 return Ok(None);
487 }
488
489 let sendme = Sendme::new_empty();
490 let msg = AnyRelayMsgOuter::new(Some(stream_id), sendme.into());
491
492 Ok(Some(ReadyStreamMsg {
493 hop,
494 msg,
495 relay_cell_format: cell_fmt,
496 ccontrol: Arc::clone(&cc),
497 }))
498 }
499 },
500 }
501 }
502
503 /// Perform some circuit-padding-based event on the specified circuit.
504 //
505 // TODO(DEDUP): this is almost identical to the client-side Conflux::run_padding_event()
506 #[cfg(feature = "circ-padding")]
507 async fn run_padding_event(
508 &mut self,
509 padding_event: PaddingEvent,
510 ) -> StdResult<(), ReactorError> {
511 use PaddingEvent as E;
512
513 match padding_event {
514 E::SendPadding(send_padding) => {
515 self.send_padding(send_padding).await?;
516 }
517 E::StartBlocking(start_blocking) => {
518 self.start_blocking_for_padding(start_blocking);
519 }
520 E::StopBlocking => {
521 self.stop_blocking_for_padding();
522 }
523 }
524 Ok(())
525 }
526
527 /// Handle a request from our padding subsystem to send a padding packet.
528 //
529 // TODO(DEDUP): this is almost identical to the client-side Client::send_padding()
530 #[cfg(feature = "circ-padding")]
531 async fn send_padding(&mut self, send_padding: padding::SendPadding) -> Result<()> {
532 use CircPaddingDisposition::*;
533
534 let target_hop = send_padding.hop;
535
536 match padding_disposition(
537 &send_padding,
538 &self.inbound_chan_tx,
539 self.padding_block.as_ref(),
540 ) {
541 QueuePaddingNormally => {
542 let queue_info = self.padding_ctrl.queued_padding(target_hop, send_padding);
543 self.queue_padding_cell_for_hop(target_hop, queue_info)
544 .await?;
545 }
546 QueuePaddingAndBypass => {
547 let queue_info = self.padding_ctrl.queued_padding(target_hop, send_padding);
548 self.queue_padding_cell_for_hop(target_hop, queue_info)
549 .await?;
550 }
551 TreatQueuedCellAsPadding => {
552 self.padding_ctrl
553 .replaceable_padding_already_queued(target_hop, send_padding);
554 }
555 }
556 Ok(())
557 }
558
559 /// Enable padding-based blocking,
560 /// or change the rule for padding-based blocking to the one in `block`.
561 //
562 // TODO(DEDUP): copy of Client::start_blocking_for_padding()
563 #[cfg(feature = "circ-padding")]
564 pub(super) fn start_blocking_for_padding(&mut self, block: padding::StartBlocking) {
565 self.inbound_chan_tx.start_blocking();
566 self.padding_block = Some(block);
567 }
568
569 /// Disable padding-based blocking.
570 ///
571 // TODO(DEDUP): copy of Client::stop_blocking_for_padding()
572 #[cfg(feature = "circ-padding")]
573 pub(super) fn stop_blocking_for_padding(&mut self) {
574 self.inbound_chan_tx.stop_blocking();
575 self.padding_block = None;
576 }
577
578 /// Generate and encrypt a padding cell, and send it to a targeted hop.
579 ///
580 /// Ignores any padding-based blocking.
581 ///
582 // TODO(DEDUP): copy of Client::queue_padding_cell_for_hop()
583 #[cfg(feature = "circ-padding")]
584 async fn queue_padding_cell_for_hop(
585 &mut self,
586 target_hop: HopNum,
587 queue_info: Option<QueuedCellPaddingInfo>,
588 ) -> Result<()> {
589 use tor_cell::relaycell::msg::Drop as DropMsg;
590
591 let msg = AnyRelayMsgOuter::new(None, DropMsg::default().into());
592 let hopnum = Some(target_hop);
593
594 // TODO: the ccontrol state isn't actually needed here, because
595 // DROP cells don't count towards SENDME windows.
596 // Technically, we could avoid unnecessarily Arc::clone()ing the CC state
597 // here, and just extract the relay cell format.
598 // But for that we would need a specialized send_relay_cell_inner()-like function
599 // that doesn't take a CC object, or to make the CC object optional in
600 // send_relay_cell_inner().
601 let (relay_cell_format, ccontrol) = self.hop_info(hopnum)?;
602
603 self.send_relay_cell_inner(hopnum, relay_cell_format, msg, false, &ccontrol, queue_info)
604 .await
605 }
606
607 /// Determine how exactly to handle a request to handle padding.
608 #[cfg(feature = "circ-padding")]
609 #[allow(unused)] // TODO(relay)
610 fn padding_disposition(&self, send_padding: &padding::SendPadding) -> CircPaddingDisposition {
611 crate::circuit::padding::padding_disposition(
612 send_padding,
613 &self.inbound_chan_tx,
614 self.padding_block.as_ref(),
615 )
616 }
617
618 /// Handle a circuit event.
619 async fn handle_event(
620 &mut self,
621 event: CircuitEvent<B::CircChanMsg>,
622 ) -> StdResult<(), ReactorError> {
623 use CircuitEvent::*;
624
625 match event {
626 Cell(cell) => self.handle_backward_cell(cell).await,
627 Send(msg) => {
628 let ReadyStreamMsg {
629 hop,
630 relay_cell_format,
631 msg,
632 ccontrol,
633 } = msg;
634
635 self.send_relay_cell(hop, relay_cell_format, msg, false, &ccontrol)
636 .await?;
637
638 Ok(())
639 }
640 Forwarded(cmd) => self.handle_reactor_cmd(cmd).await,
641 ForwardShutdown => {
642 // The forward reactor has crashed, so we have to shut down.
643 trace!(
644 circ_uniq_id = %self.unique_id,
645 backward_circ_id = %self.circ_id,
646 "Backward relay reactor shutdown (forward reactor has closed)",
647 );
648
649 Err(ReactorError::Shutdown)
650 }
651 ProtoViolation(err) => Err(err.into()),
652 }
653 }
654
655 /// Return the RelayCellFormat and CC state of a given hop.
656 fn hop_info(
657 &self,
658 hopnum: Option<HopNum>,
659 ) -> Result<(RelayCellFormat, Arc<Mutex<CongestionControl>>)> {
660 let hops = self.hops.read().expect("poisoned lock");
661 let hop = hops.get(hopnum)?;
662 let relay_cell_format = hop.settings.relay_crypt_protocol().relay_cell_format();
663 let ccontrol = Arc::clone(&hop.ccontrol);
664
665 Ok((relay_cell_format, ccontrol))
666 }
667
668 /// Handle a command sent to us by the forward reactor.
669 async fn handle_reactor_cmd(&mut self, msg: BackwardReactorCmd) -> StdResult<(), ReactorError> {
670 use BackwardReactorCmd::*;
671
672 match msg {
673 SendRelayMsg { hop, msg } => {
674 self.send_relay_msg(hop, msg).await?;
675 }
676 HandleSendme { hop, sendme } => {
677 self.handle_sendme(hop, sendme).await?;
678 return Ok(());
679 }
680 #[cfg(feature = "relay")]
681 HandleCircuitExtended {
682 hop,
683 extended2,
684 outbound_chan_rx,
685 } => {
686 self.outbound_chan_rx = Some(outbound_chan_rx);
687 let msg = AnyRelayMsgOuter::new(None, extended2.into());
688 self.send_relay_msg(hop, msg).await?;
689
690 debug!(
691 circ_uniq_id = %self.unique_id,
692 backward_circ_id = %self.circ_id,
693 "Extended circuit to the next hop"
694 );
695 }
696 }
697
698 Ok(())
699 }
700
701 /// Send a relay message to the specified hop.
702 async fn send_relay_msg(
703 &mut self,
704 hopnum: Option<HopNum>,
705 msg: AnyRelayMsgOuter,
706 ) -> StdResult<(), ReactorError> {
707 let (relay_cell_format, ccontrol) = self.hop_info(hopnum)?;
708 let cmd = msg.cmd();
709
710 // TODO(relay): remove this log once we add some tests
711 // and confirm relaying cells works as expected
712 // (in practice it will be too noisy to be useful, even at trace level).
713 trace!(
714 circ_uniq_id = %self.unique_id,
715 backward_circ_id = %self.circ_id,
716 hopnum=?hopnum,
717 cmd = %cmd,
718 "Sending backward cell"
719 );
720
721 self.send_relay_cell(hopnum, relay_cell_format, msg, false, &ccontrol)
722 .await?;
723
724 if cmd == RelayCmd::SENDME {
725 // TODO: does note_sendme_sent() need to be fallible?
726 // Neither Vegas nor the fixed-window impl ever return Err
727 ccontrol.lock().expect("poisoned lock").note_sendme_sent()?;
728 }
729
730 Ok(())
731 }
732
733 /// Handle a circuit-level SENDME (stream ID = 0).
734 ///
735 /// Returns an error if the SENDME does not have an authentication tag
736 /// (versions of Tor <=0.3.5 omit the SENDME tag, but we don't support
737 /// those any longer).
738 ///
739 /// Any error returned from this function will shut down the reactor.
740 ///
741 // TODO(DEDUP): duplicates the logic from the client-side Circuit::handle_sendme()
742 async fn handle_sendme(
743 &mut self,
744 hopnum: Option<HopNum>,
745 sendme: Sendme,
746 ) -> StdResult<(), ReactorError> {
747 let tag = sendme
748 .into_sendme_tag()
749 .ok_or_else(|| Error::CircProto("missing tag on circuit sendme".into()))?;
750
751 // NOTE: it's okay to await. We are only awaiting on the congestion_signals
752 // future which *should* resolve immediately
753 let signals = self.inbound_chan_tx.congestion_signals().await;
754
755 let hops = self.hops.read().expect("poisoned lock");
756 let hop = hops.get(hopnum)?;
757
758 // Update the CC object that we received a SENDME along
759 // with possible congestion signals.
760 hop.ccontrol
761 .lock()
762 .expect("poisoned lock")
763 .note_sendme_received(&self.time_provider, tag, signals)?;
764
765 Ok(())
766 }
767
768 /// Encode `msg` and encrypt it, returning the resulting cell
769 /// and tag that should be expected for an authenticated SENDME sent
770 /// in response to that cell.
771 ///
772 // TODO(DEDUP): duplicates the logic from the client-side Circuit::encode_relay_cell()
773 fn encode_relay_cell(
774 &mut self,
775 relay_format: RelayCellFormat,
776 hop: Option<HopNum>,
777 early: bool,
778 msg: AnyRelayMsgOuter,
779 ) -> Result<(AnyChanMsg, SendmeTag)> {
780 let mut body: RelayCellBody = msg
781 .encode(relay_format, &mut rand::rng())
782 .map_err(|e| Error::from_cell_enc(e, "relay cell body"))?
783 .into();
784 let cmd = if early {
785 ChanCmd::RELAY_EARLY
786 } else {
787 ChanCmd::RELAY
788 };
789
790 // Use the implementation-dependent encryption logic
791 let tag = self.inner.encrypt_relay_cell(cmd, &mut body, hop);
792 let msg = Relay::from(BoxedCellBody::from(body));
793 let msg = if early {
794 AnyChanMsg::RelayEarly(msg.into())
795 } else {
796 AnyChanMsg::Relay(msg)
797 };
798
799 Ok((msg, tag))
800 }
801
802 /// Encode `msg`, encrypt it, and send it to the 'hop'th hop.
803 ///
804 /// If there is insufficient outgoing *circuit-level* or *stream-level*
805 /// SENDME window, an error is returned instead.
806 ///
807 /// Does not check whether the cell is well-formed or reasonable.
808 async fn send_relay_cell(
809 &mut self,
810 hop: Option<HopNum>,
811 relay_cell_format: RelayCellFormat,
812 msg: AnyRelayMsgOuter,
813 early: bool,
814 ccontrol: &Arc<Mutex<CongestionControl>>,
815 ) -> Result<()> {
816 self.send_relay_cell_inner(hop, relay_cell_format, msg, early, ccontrol, None)
817 .await
818 }
819
820 /// As [`send_relay_cell`](Self::send_relay_cell), but takes an optional
821 /// [`QueuedCellPaddingInfo`] in `padding_info`.
822 ///
823 /// If `padding_info` is None, `msg` must be non-padding: we report it as such to the
824 /// padding controller.
825 ///
826 // TODO(DEDUP): this contains parts of Circuit::send_relay_cell_inner()
827 async fn send_relay_cell_inner(
828 &mut self,
829 hop: Option<HopNum>,
830 relay_cell_format: RelayCellFormat,
831 msg: AnyRelayMsgOuter,
832 early: bool,
833 ccontrol: &Arc<Mutex<CongestionControl>>,
834 padding_info: Option<QueuedCellPaddingInfo>,
835 ) -> Result<()> {
836 let c_t_w = sendme::cmd_counts_towards_windows(msg.cmd());
837 let (msg, tag) = self.encode_relay_cell(relay_cell_format, hop, early, msg)?;
838 let cell = AnyChanCell::new(Some(self.circ_id), msg);
839
840 // TODO: we use HopNum(0) if we're a relay (i.e. if the hop is None).
841 // Is that ok?
842 let hop = hop.unwrap_or_else(|| HopNum::from(0));
843 // Remember that we've enqueued this cell.
844 let padding_info = padding_info.or_else(|| self.padding_ctrl.queued_data(hop));
845
846 // Note: this future is always `Ready`, because we checked the sink for readiness
847 // before polling the async streams, so await won't block.
848 Pin::new(&mut self.inbound_chan_tx)
849 .send_unbounded((cell, padding_info))
850 .await?;
851
852 if c_t_w {
853 ccontrol
854 .lock()
855 .expect("poisoned lock")
856 .note_data_sent(&self.time_provider, &tag)?;
857 }
858
859 Ok(())
860 }
861
862 /// Handle a backward cell (moving from the exit towards the client).
863 async fn handle_backward_cell(&mut self, cell: B::CircChanMsg) -> StdResult<(), ReactorError> {
864 match self
865 .inner
866 .handle_backward_cell(self.unique_id, self.circ_id, cell)?
867 {
868 BackwardCellDisposition::Forward(cell) => {
869 let cell = AnyChanCell::new(Some(self.circ_id), cell);
870 self.inbound_chan_tx
871 .send((cell, None))
872 .await
873 .map_err(ReactorError::Err)
874 }
875 }
876 }
877}
878
879impl<B: BackwardHandler> Drop for BackwardReactor<B> {
880 fn drop(&mut self) {
881 // This will send a DESTROY down the inbound Tor channel
882 let _ = self.channel.close_circuit(self.circ_id);
883 }
884}
885
886/// A circuit event that must be handled by the [`BackwardReactor`].
887enum CircuitEvent<M> {
888 /// We received a cell that needs to be handled.
889 ///
890 /// (The cell is client-bound if we are a relay, or exit-bound if we are a client).
891 Cell(M),
892 /// A stream has a RELAY cell that needs
893 /// to be packaged and written to our Tor channel.
894 ///
895 /// (The message is client-bound if we are a relay, or exit-bound if we are a client).
896 Send(ReadyStreamMsg),
897 /// We received a cell from the ForwardReactor that we need to handle.
898 ///
899 /// This might be
900 ///
901 /// * a circuit-level SENDME that we have received, or
902 /// * a circuit-level SENDME that we need to deliver to the client
903 Forwarded(BackwardReactorCmd),
904 /// The forward reactor has shut down.
905 ///
906 /// We need to shut down too.
907 ForwardShutdown,
908 /// Protocol violation.
909 ///
910 /// This can happen if we receive a channel message that is not supported on the channel.
911 ProtoViolation(Error),
912}
913
914/// Instructions from the forward reactor.
915pub(crate) enum BackwardReactorCmd {
916 /// A circuit SENDME we received from the other endpoint.
917 HandleSendme {
918 /// The hop the SENDME came on.
919 hop: Option<HopNum>,
920 /// The SENDME.
921 sendme: Sendme,
922 },
923 /// A message we need to send back to the other endpoint.
924 SendRelayMsg {
925 /// The hop to encode the message for.
926 hop: Option<HopNum>,
927 /// The message to send.
928 msg: AnyRelayMsgOuter,
929 },
930 /// This relay circuit was extended by another hop.
931 ///
932 /// This causes the reactor send the `extended2` message on its inbound channel,
933 /// and start reading from `outbound_chan_rx` in the main loop.
934 //
935 ///
936 // TODO: I wish we didn't need to expose this relay-specific variant
937 // in the generic reactor but we have no choice: abstracting it away
938 // means either introducing a mutex between the relay-side forward/backward
939 // handlers, or yet another mpsc between them.
940 #[cfg(feature = "relay")]
941 HandleCircuitExtended {
942 /// The hop to encode the message for.
943 ///
944 /// In practice, this is always None, because only relays use this.
945 hop: Option<HopNum>,
946 /// The cell to send to the specified hop,
947 extended2: Extended2,
948 /// The reading end of the outbound Tor channel, if we are not the last hop.
949 ///
950 /// Yields cells moving from the exit towards the client, if we are a middle relay.
951 outbound_chan_rx: CircuitRxReceiver,
952 },
953}
954
955/// A flow control update message.
956///
957/// TODO(DEDUP): This is a duplicate of the client's
958/// `crate::client::reactor::control::FlowCtrlMsg`.
959#[derive(Debug)]
960pub(crate) enum FlowCtrlMsg {
961 /// Send a SENDME message on this stream.
962 Sendme,
963}