Skip to main content

tor_proto/relay/channel/
create_handler.rs

1//! Handler for CREATE* cells.
2
3use crate::FlowCtrlParameters;
4use crate::ccparams::{
5    AlgorithmDiscriminants, CongestionWindowParams, FixedWindowParams, RoundTripEstimatorParams,
6    VegasParams,
7};
8use crate::channel::Channel;
9use crate::circuit::celltypes::{CreateRequest, CreateResponse};
10use crate::circuit::circhop::{HandshakeParamsError, HopSettings};
11use crate::circuit::{
12    CircuitRxSender, HandshakeSubprotocols, InvalidHandshakeSubprotocolError, UniqId,
13};
14use crate::client::circuit::padding::PaddingController;
15use crate::crypto::binding::CircuitBinding;
16use crate::crypto::cell::CryptInit as _;
17use crate::crypto::cell::{
18    CgoRelayCrypto, InboundRelayLayer, OutboundRelayLayer, RelayLayer, Tor1RelayCrypto,
19};
20use crate::crypto::handshake::RelayHandshakeError;
21use crate::crypto::handshake::ServerHandshake as _;
22use crate::crypto::handshake::fast::CreateFastServer;
23use crate::crypto::handshake::ntor::{NtorServer, NtorServerKeys};
24use crate::crypto::handshake::ntor_v3::{NtorV3Server, NtorV3ServerKeys};
25use crate::memquota::SpecificAccount as _;
26use crate::memquota::{ChannelAccount, CircuitAccount};
27use crate::relay::channel_provider::ChannelProvider;
28use crate::relay::reactor::Reactor;
29use crate::relay::{IncomingStreamRequestFilter, RelayCirc};
30use crate::stream::IncomingStream;
31use futures::channel::mpsc;
32use futures::{SinkExt, Stream};
33use smallvec::SmallVec;
34use std::sync::{Arc, RwLock, Weak};
35use tor_cell::chancell::ChanMsg as _;
36use tor_cell::chancell::CircId;
37use tor_cell::chancell::msg::{
38    CreateFast, Created2, CreatedFast, Destroy, DestroyReason, HandshakeType,
39};
40use tor_cell::relaycell::RelayCmd;
41use tor_cell::relaycell::extend::{
42    CcRequest, CcResponse, CircRequestExt, CircResponseExt, SubprotocolRequest,
43};
44use tor_error::{ErrorKind, HasKind, debug_report, internal, into_internal, warn_report};
45use tor_linkspec::OwnedChanTarget;
46use tor_llcrypto::pk::curve25519;
47use tor_llcrypto::pk::ed25519::Ed25519Identity;
48use tor_llcrypto::pk::rsa::RsaIdentity;
49use tor_memquota::mq_queue::ChannelSpec as _;
50use tor_memquota::mq_queue::MpscSpec;
51use tor_relay_crypto::pk::{RelayNtorKeypair, RelayNtorKeys};
52use tor_rtcompat::SpawnExt as _;
53use tor_rtcompat::{DynTimeProvider, Runtime};
54use tracing::{debug, trace};
55
56/// Everything needed to handle CREATE* messages on channels.
57#[derive(derive_more::Debug)]
58pub struct CreateRequestHandler {
59    /// Something that can launch channels. Typically the `ChanMgr`.
60    chan_provider: Weak<dyn ChannelProvider<BuildSpec = OwnedChanTarget> + Send + Sync>,
61    /// Circuit-related network parameters.
62    circ_net_params: RwLock<CircNetParameters>,
63    /// The circuit extension keys.
64    #[debug(skip)]
65    ntor_keys: RwLock<RelayNtorKeys>,
66    /// An [`IncomingStreamRequestFilter`] factory for checking whether the user wants
67    /// this request, or wants to reject it immediately.
68    ///
69    /// Used for obtaining a current [`IncomingStreamRequestFilter`]
70    /// for building a circuit reactor.
71    //
72    // TODO(relay): it's likely this will end up changing quite a bit once we start
73    // figuring out exactly how the config/reconfigure() logic and IncomingStreamRequestFilter
74    // should function for relays.
75    #[debug(skip)]
76    incoming_filter_factory: Box<dyn IncomingStreamRequestFilterFactory + Send + Sync>,
77    /// The allowed incoming stream commands.
78    ///
79    /// Used for rejecting BEGIN and RESOLVE if we are not configured to be an exit.
80    ///
81    // TODO(relay): we might use this for rejecting BEGIN_DIR too,
82    // if we decide to allow relays to opt out of being dir mirrors.
83    // See https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/4107/diffs#note_3426447
84    allowed_stream_cmds: SmallVec<[RelayCmd; 3]>,
85    /// A sender for the [`Stream`]s of `IncomingStream` of all circuits.
86    ///
87    /// The receiver will receive one [`Stream`] (of tor streams) per circuit.
88    ///
89    /// This being a bounded MPSC might seem a bit risky, because in theory,
90    /// if the receiver is not reading fast enough, sending will block.
91    /// In practice, however, it should never block (or buffer very much at all,
92    /// for that matter), because the user (arti-relay) is expected to read from
93    /// this in a tight loop, and spawn a task for handling each [`Stream`].
94    ///
95    /// Note: because this MPSC is not associated with any particular circuit or channel,
96    /// it does not participate in the memquota system (see [crate::memquota]).
97    #[debug(skip)]
98    circuit_stream_tx: mpsc::Sender<Box<dyn Stream<Item = IncomingStream> + Send + Sync + Unpin>>,
99}
100
101// We make the CREATE-handling methods of `CreateRequestHandler` async
102// since we expect that in the future we may want to offload the crypto to a worker thread.
103#[expect(clippy::unused_async)]
104impl CreateRequestHandler {
105    /// Build a new [`CreateRequestHandler`], and a [`CircuitIncomingStreamReceiver`]
106    /// for receiving new streams that are opened on any incoming circuits.
107    pub fn new(
108        chan_provider: Weak<dyn ChannelProvider<BuildSpec = OwnedChanTarget> + Send + Sync>,
109        circ_net_params: CircNetParameters,
110        ntor_keys: RelayNtorKeys,
111        incoming_filter_factory: Box<dyn IncomingStreamRequestFilterFactory + Send + Sync>,
112        allowed_stream_cmds: &[RelayCmd],
113    ) -> (Self, CircuitIncomingStreamReceiver) {
114        // TODO(relay-tuning): this MPSC can be a bottleneck,
115        // as all the channels on this relay will want to send one item on it
116        // each time a new circuit is created.
117        //
118        // The value set here is a guesstimate.
119        const CIRC_STREAM_BUF_SIZE: usize = 1024;
120
121        // This is not associated with any particular circuit
122        // (it is for *all* circuits), so it doesn't participate in memquota
123        // (see circuit_stream_tx docs)
124        #[allow(clippy::disallowed_methods)]
125        let (stream_tx, stream_rx) = mpsc::channel(CIRC_STREAM_BUF_SIZE);
126
127        let handler = Self {
128            chan_provider,
129            circ_net_params: RwLock::new(circ_net_params),
130            ntor_keys: RwLock::new(ntor_keys),
131            incoming_filter_factory,
132            allowed_stream_cmds: allowed_stream_cmds.into(),
133            circuit_stream_tx: stream_tx,
134        };
135
136        let circuit_stream_rx = CircuitIncomingStreamReceiver {
137            circuit_stream_rx: stream_rx,
138        };
139
140        (handler, circuit_stream_rx)
141    }
142
143    /// Update the circuit parameters from a network consensus.
144    pub fn update_params(&self, circ_net_params: CircNetParameters) {
145        *self.circ_net_params.write().expect("rwlock poisoned") = circ_net_params;
146    }
147
148    /// Update the handler with a new set of circuit extension keys.
149    ///
150    /// This is called periodically by the relay key rotation task.
151    pub fn update_ntor_keys(&self, ntor_keys: RelayNtorKeys) {
152        *self.ntor_keys.write().expect("rwlock poisoned") = ntor_keys;
153    }
154
155    /// Handle a CREATE* cell.
156    ///
157    /// This intentionally does not return a [`crate::Error`] so that we don't accidentally shut
158    /// down the channel reactor when we really should be returning a DESTROY. Shutting down a
159    /// channel may cause us to leak information about paths of circuits travelling through this
160    /// relay. This is especially important here since we're handling data that is controllable from
161    /// the other end of the circuit.
162    #[allow(clippy::too_many_arguments)]
163    pub(crate) async fn handle_create<R: Runtime>(
164        &self,
165        runtime: &R,
166        channel: &Arc<Channel>,
167        our_ed25519_id: &Ed25519Identity,
168        our_rsa_id: &RsaIdentity,
169        circ_id: CircId,
170        msg: &CreateRequest,
171        memquota: &ChannelAccount,
172        circ_unique_id: UniqId,
173    ) -> Result<(CreateResponse, RelayCircComponents), Destroy> {
174        let result = self
175            .handle_create_inner(
176                runtime,
177                channel,
178                our_ed25519_id,
179                our_rsa_id,
180                circ_id,
181                msg,
182                memquota,
183                circ_unique_id,
184            )
185            .await;
186
187        match result {
188            Ok(x) => Ok(x),
189            Err(e) => {
190                // TODO(relay): The log messages throughout could be very noisy, so should have rate limiting.
191                let cmd = msg.cmd();
192                debug_report!(&e, %cmd, "Failed to handle circuit create request");
193
194                // `tor-spec/tearing-down-circuits.md`:
195                //
196                // > Implementations SHOULD always use the NONE reason to avoid side channels: [...]
197                Err(Destroy::new(DestroyReason::NONE))
198            }
199        }
200    }
201
202    /// See [`Self::handle_create`].
203    #[allow(clippy::too_many_arguments)]
204    async fn handle_create_inner<R: Runtime>(
205        &self,
206        runtime: &R,
207        channel: &Arc<Channel>,
208        our_ed25519_id: &Ed25519Identity,
209        our_rsa_id: &RsaIdentity,
210        circ_id: CircId,
211        msg: &CreateRequest,
212        memquota: &ChannelAccount,
213        circ_unique_id: UniqId,
214    ) -> Result<(CreateResponse, RelayCircComponents), HandleCreateError> {
215        // Perform the handshake crypto and build the response.
216        let handshake_components = match msg {
217            CreateRequest::CreateFast(msg) => self.handle_create_fast(msg).await?,
218            CreateRequest::Create2(msg) => match msg.handshake_type() {
219                HandshakeType::NTOR_V3 => {
220                    self.handle_create2_ntorv3(msg.body(), our_ed25519_id)
221                        .await?
222                }
223                HandshakeType::NTOR => self.handle_create2_ntor(msg.body(), our_rsa_id).await?,
224                x @ HandshakeType::TAP | x => {
225                    return Err(HandleCreateError::Create2HandshakeType(x));
226                }
227            },
228        };
229
230        let memquota = CircuitAccount::new(memquota)?;
231
232        // We use a large mpsc queue here since a circuit should never block the channel,
233        // and we hope that memquota will help us if an attacker intentionally fills this buffer.
234        // We use `10_000_000` since `usize::MAX` causes `futures::channel::mpsc` to panic.
235        // TODO(relay): We should switch to an unbounded queue, but the circuit reactor is expecting
236        // a bounded queue.
237        let time_provider = DynTimeProvider::new(runtime.clone());
238        let account = memquota.as_raw_account();
239        let (sender, receiver) =
240            MpscSpec::new(10_000_000).new_mq(time_provider.clone(), account)?;
241        let (sender, receiver) = crate::circuit::circ_sender::channel(sender, receiver);
242
243        // TODO(relay): Do we really want a client padding machine here?
244        let (padding_ctrl, padding_stream) =
245            crate::client::circuit::padding::new_padding(DynTimeProvider::new(runtime.clone()));
246
247        // Upgrade the channel provider, which in practice is the `ChanMgr` so this should not fail.
248        let Some(chan_provider) = self.chan_provider.upgrade() else {
249            return Err(internal!("Unable to upgrade weak `ChannelProvider`").into());
250        };
251
252        // Create an IncomingStreamRequestFilter for this circuit.
253        // This will get applied to every stream request (BEGIN, BEGIN_DIR, RESOLVE)
254        // arriving on the circuit.
255        //
256        // Note: once built, a circuit reactor's IncomingStreamRequestFilter cannot be changed
257        // (it's fixed for the entire duration of the circuit).
258        let incoming_filter = self.incoming_filter_factory.current_filter();
259
260        // Build the relay circuit reactor.
261        let (reactor, circ, incoming_streams) = Reactor::new(
262            runtime.clone(),
263            channel,
264            circ_id,
265            circ_unique_id,
266            receiver,
267            handshake_components.crypto_in,
268            handshake_components.crypto_out,
269            &handshake_components.hop_settings,
270            chan_provider,
271            padding_ctrl.clone(),
272            padding_stream,
273            incoming_filter,
274            &self.allowed_stream_cmds,
275            &memquota,
276        )
277        .map_err(into_internal!("Failed to start circuit reactor"))?;
278
279        let mut circuit_stream_tx = self.circuit_stream_tx.clone();
280        // Start the reactor in a task.
281        let () = runtime.spawn(async move {
282            if let Err(e) = circuit_stream_tx.send(Box::new(incoming_streams)).await {
283                warn_report!(e, "IncomingStream handler disappeared?!");
284                // If we get here, it means the relay stream handler task has gone away,
285                // so there won't be anything handling the incoming streams.
286                //
287                // The reactor is dropped, making the RelayCirc returned below
288                // in the RelayCircComponents unusable
289                // (RelayCirc::is_closing() will return `true`).
290                drop(reactor);
291            } else {
292                // Only spawn the circuit reactor if the incoming stream handler was
293                // able to receive our message
294                match reactor.run().await {
295                    Ok(()) => {}
296                    Err(e) => {
297                        debug_report!(e, "Relay circuit reactor exited with an error");
298                    }
299                }
300            }
301        })?;
302
303        Ok((
304            handshake_components.response,
305            RelayCircComponents {
306                circ,
307                sender,
308                padding_ctrl,
309            },
310        ))
311    }
312
313    /// The handshake code for a CREATE_FAST request.
314    async fn handle_create_fast(
315        &self,
316        msg: &CreateFast,
317    ) -> Result<CompletedHandshakeComponents, HandleCreateError> {
318        // TODO(relay): We might want to offload this to a CPU worker in the future.
319        let (keygen, handshake_msg) = CreateFastServer::server(
320            &mut rand::rng(),
321            // The CREATE_FAST handshake doesn't accept or return extensions,
322            // so this `AuxDataReply` is a no-op.
323            &mut |_: &()| Some(()),
324            // The CREATE_FAST handshake doesn't use any keys.
325            &[],
326            msg.handshake(),
327        )?;
328
329        let circ_net_params = self
330            .circ_net_params
331            .read()
332            .expect("rwlock poisoned")
333            .clone();
334
335        // No subprotocols are requested during a CREATE_FAST handshake.
336        let subprotos = HandshakeSubprotocols::default();
337
338        let hop_settings = HopSettings::from_handshake_params(
339            circ_net_params,
340            // CREATE_FAST always uses fixed-window flow control.
341            AlgorithmDiscriminants::FixedWindow,
342            subprotos,
343        )?;
344
345        let crypt = Tor1RelayCrypto::construct(keygen)
346            .map_err(into_internal!("Circuit crypt state construction failed"))?;
347
348        let (crypto_out, crypto_in, _binding) = split_relay_layer(crypt);
349
350        let response = CreatedFast::new(handshake_msg);
351        let response = CreateResponse::CreatedFast(response);
352
353        trace!("Completed CREATE_FAST handshake");
354
355        Ok(CompletedHandshakeComponents {
356            response,
357            hop_settings,
358            crypto_out,
359            crypto_in,
360        })
361    }
362
363    /// The handshake code for a CREATE2 ntor (non-v3) request.
364    async fn handle_create2_ntor(
365        &self,
366        msg_body: &[u8],
367        our_rsa_id: &RsaIdentity,
368    ) -> Result<CompletedHandshakeComponents, HandleCreateError> {
369        let ntor_keys = self.with_ntor_keys(|k| NtorSecretKey::new(our_rsa_id, Arc::clone(k)));
370
371        // TODO(relay): We might want to offload this to a CPU worker in the future.
372        let (keygen, handshake_msg) = NtorServer::server(
373            &mut rand::rng(),
374            // The ntor (non-v3) handshake doesn't accept or return extensions,
375            // so this `AuxDataReply` is a no-op.
376            &mut |_: &()| Some(()),
377            ntor_keys.as_ref(),
378            msg_body,
379        )?;
380
381        let circ_net_params = self
382            .circ_net_params
383            .read()
384            .expect("rwlock poisoned")
385            .clone();
386
387        // No subprotocols are requested during an ntor (non-v3) handshake.
388        let subprotos = HandshakeSubprotocols::default();
389
390        let hop_settings = HopSettings::from_handshake_params(
391            circ_net_params,
392            // CREATE2 with ntor (non-v3) always uses fixed-window flow control.
393            AlgorithmDiscriminants::FixedWindow,
394            subprotos,
395        )?;
396
397        let crypt = Tor1RelayCrypto::construct(keygen)
398            .map_err(into_internal!("Circuit crypt state construction failed"))?;
399
400        let (crypto_out, crypto_in, _binding) = split_relay_layer(crypt);
401
402        let response = Created2::new(handshake_msg);
403        let response = CreateResponse::Created2(response);
404
405        trace!("Completed ntor handshake");
406
407        Ok(CompletedHandshakeComponents {
408            response,
409            hop_settings,
410            crypto_out,
411            crypto_in,
412        })
413    }
414
415    /// The handshake code for a CREATE2 ntor-v3 request.
416    async fn handle_create2_ntorv3(
417        &self,
418        msg_body: &[u8],
419        our_ed25519_id: &Ed25519Identity,
420    ) -> Result<CompletedHandshakeComponents, HandleCreateError> {
421        let ntor_keys =
422            self.with_ntor_keys(|k| NtorV3SecretKey::new(our_ed25519_id, Arc::clone(k)));
423
424        let circ_net_params = self
425            .circ_net_params
426            .read()
427            .expect("rwlock poisoned")
428            .clone();
429
430        // These extensions can be negotiated during the handshake.
431        let mut cc_algorithm = AlgorithmDiscriminants::FixedWindow;
432
433        // These subprotocols were requested during the handshake.
434        // They are not validated.
435        let mut subprotos = SubprotocolRequest::default();
436
437        // Helper which processes extension requests and returns any responses.
438        // Returns `None` if the handshake should fail.
439        let mut ext_reply_fn = |client_exts: &[CircRequestExt]| {
440            let mut response_exts = Vec::new();
441
442            // https://spec.torproject.org/tor-spec/create-created-cells.html#additional-data
443            //
444            // > Unless otherwise specified in the documentation for an extension type:
445            // > - [...]
446            // > - Parties MUST ignore any occurrence of an extension with a given type after the first such occurrence.
447            //
448            // TODO: Is there something nicer that we can do here?
449            // We could use accessors like `ExtList::get_cc_request()`
450            // which iterate over the extension list for each extension,
451            // but using an enum match like we do below is kind of nice.
452            let mut handled_cc_request = false;
453            let mut handled_subproto_request = false;
454
455            for ext in client_exts {
456                match ext {
457                    CircRequestExt::CcRequest(CcRequest { .. }) => {
458                        if handled_cc_request {
459                            continue;
460                        }
461                        handled_cc_request = true;
462
463                        cc_algorithm = AlgorithmDiscriminants::Vegas;
464
465                        let sendme_inc: u8 = circ_net_params.cc.cwnd.sendme_inc();
466                        let response = CcResponse::new(sendme_inc);
467                        response_exts.push(CircResponseExt::CcResponse(response));
468                    }
469                    // The given `SubprotocolRequest` stores a list of `NumberedSubver`,
470                    // but a circuit extension request is limited to 255 bytes (127 subprotocols).
471                    // So while a malicious client could send us a lot of invalid subprotocols,
472                    // this limit prevents this list from being excessively large.
473                    CircRequestExt::SubprotocolRequest(subproto_request) => {
474                        if handled_subproto_request {
475                            continue;
476                        }
477                        handled_subproto_request = true;
478
479                        // We don't check the requested subprotocols here.
480                        subprotos = subproto_request.clone();
481                    }
482                    CircRequestExt::Unrecognized(ext) => {
483                        // https://spec.torproject.org/tor-spec/create-created-cells.html#additional-data
484                        //
485                        // > Parties MUST ignore extensions with `EXT_FIELD_TYPE` bodies they do not recognize.
486                        debug!(
487                            ?ext,
488                            "CREATE2 ntor-v3 handshake requested unrecognized extension",
489                        );
490                    }
491                    ext => {
492                        // https://spec.torproject.org/tor-spec/create-created-cells.html#additional-data
493                        //
494                        // > Parties MUST ignore extensions with `EXT_FIELD_TYPE` bodies they do not recognize.
495                        //
496                        // We recognize this but don't know what to do with it.
497                        // We haven't implemented it, or it doesn't make sense
498                        // (for example `CircRequestExt::ProofOfWork`).
499                        // So we'll just behave as if we don't recognize it.
500                        debug!(
501                            ?ext,
502                            "CREATE2 ntor-v3 handshake requested unsupported extension",
503                        );
504                    }
505                }
506            }
507
508            Some(response_exts)
509        };
510
511        // TODO(relay): We might want to offload this to a CPU worker in the future.
512        let (keygen, handshake_msg) = NtorV3Server::server(
513            &mut rand::rng(),
514            &mut ext_reply_fn,
515            ntor_keys.as_ref(),
516            msg_body,
517        )?;
518
519        // Ensure that the client did not request invalid/unsupported subprotocols.
520        let subprotos = HandshakeSubprotocols::try_from_request(subprotos)?;
521
522        let hop_settings =
523            HopSettings::from_handshake_params(circ_net_params, cc_algorithm, subprotos)?;
524
525        let (crypto_out, crypto_in, _binding) = if subprotos.relay_crypt_cgo {
526            let crypt = CgoRelayCrypto::construct(keygen)
527                .map_err(into_internal!("Circuit crypt state construction failed"))?;
528            split_relay_layer(crypt)
529        } else {
530            let crypt = Tor1RelayCrypto::construct(keygen)
531                .map_err(into_internal!("Circuit crypt state construction failed"))?;
532            split_relay_layer(crypt)
533        };
534
535        let response = Created2::new(handshake_msg);
536        let response = CreateResponse::Created2(response);
537
538        trace!(?cc_algorithm, ?subprotos, "Completed ntor-v3 handshake");
539
540        Ok(CompletedHandshakeComponents {
541            response,
542            hop_settings,
543            crypto_out,
544            crypto_in,
545        })
546    }
547
548    /// Helper to get the ntor keypairs after some transformation `map`.
549    ///
550    /// The `map` transformation must be fast since it blocks a read lock.
551    /// The returned keys are sorted with the most recent key first.
552    ///
553    /// It would be nice if this just returned an iterator,
554    /// but the read lock prevents this.
555    fn with_ntor_keys<T>(&self, map: impl FnMut(&Arc<RelayNtorKeypair>) -> T) -> impl AsRef<[T]> {
556        let ntor_keys = self.ntor_keys.read().expect("rwlock poisoned");
557        let ntor_keys = [Some(ntor_keys.latest()), ntor_keys.previous()];
558        ntor_keys
559            .into_iter()
560            .flatten()
561            .map(map)
562            .collect::<SmallVec<[T; 2]>>()
563    }
564}
565
566/// The server's RSA identity and ntor keypair.
567#[derive(derive_more::Constructor)]
568struct NtorSecretKey<'a> {
569    /// The server's RSA identity.
570    ident: &'a RsaIdentity,
571    /// The server's ntor keypair.
572    keys: Arc<RelayNtorKeypair>,
573}
574
575impl<'a> NtorServerKeys for NtorSecretKey<'a> {
576    fn ident(&self) -> &RsaIdentity {
577        self.ident
578    }
579
580    fn public_key(&self) -> &curve25519::PublicKey {
581        self.keys.public_raw()
582    }
583
584    fn secret_key(&self) -> &curve25519::StaticSecret {
585        self.keys.secret()
586    }
587}
588
589/// The server's Ed25519 identity and ntor keypair.
590#[derive(derive_more::Constructor)]
591struct NtorV3SecretKey<'a> {
592    /// The server's Ed25519 identity.
593    ident: &'a Ed25519Identity,
594    /// The server's ntor keypair.
595    keys: Arc<RelayNtorKeypair>,
596}
597
598impl<'a> NtorV3ServerKeys for NtorV3SecretKey<'a> {
599    fn ident(&self) -> &Ed25519Identity {
600        self.ident
601    }
602
603    fn public_key(&self) -> &curve25519::PublicKey {
604        self.keys.public_raw()
605    }
606
607    fn secret_key(&self) -> &curve25519::StaticSecret {
608        self.keys.secret()
609    }
610}
611
612/// A receiver of [`Stream`]s (one for each incoming circuit),
613/// where each `Stream` produces [`IncomingStream`]s for that circuit.
614///
615// Note: in theory, it would be nice if we could get rid of this type altogether.
616// In an ideal world, I would've instead
617//
618//   * added a `RelayCirc::take_incoming_streams()` method for obtaining
619//     the futures::Stream of IncomingStream of that circuit
620//   * made the CreateRequestHandler send each Arc<RelayCirc> over to arti-relay for handling
621//   * made arti-relay obtain the futures::Stream<Item = IncomingStream> of each RelayCirc
622//     by calling `RelayCirc::take_incoming_streams()`
623//
624// However, that would involve adding some locking/interior mutability within RelayCirc
625// (which is always behind an Arc), or extending mq_queue::Receiver to be Clone,
626// which would be tricky to pull off (see the comment on mq_queue::Receiver about this).
627pub struct CircuitIncomingStreamReceiver {
628    /// The receiver for the [`Stream`]s of `IncomingStream` of all circuits.
629    ///
630    /// Receives one [`Stream`] (of tor streams) per circuit.
631    /// Each of these will be handled in a new task.
632    circuit_stream_rx: mpsc::Receiver<<Self as Stream>::Item>,
633}
634
635impl Stream for CircuitIncomingStreamReceiver {
636    // TODO: it would be nice if we could return a type-erased Stream here
637    // (impl Stream<...>), but impl Trait in associated types is unstable.
638    // See rust issue #63063 <https://github.com/rust-lang/rust/issues/63063>
639    type Item = Box<dyn Stream<Item = IncomingStream> + Send + Sync + Unpin>;
640
641    fn poll_next(
642        mut self: std::pin::Pin<&mut Self>,
643        cx: &mut std::task::Context<'_>,
644    ) -> std::task::Poll<Option<Self::Item>> {
645        use futures::StreamExt as _;
646
647        self.circuit_stream_rx.poll_next_unpin(cx)
648    }
649}
650
651/// Helper function to split a `RelayLayer` into forward and backward type-erased trait objects.
652fn split_relay_layer<F, B>(
653    crypt: impl RelayLayer<F, B>,
654) -> (
655    Box<dyn OutboundRelayLayer + Send>,
656    Box<dyn InboundRelayLayer + Send>,
657    CircuitBinding,
658)
659where
660    F: OutboundRelayLayer + Send + 'static,
661    B: InboundRelayLayer + Send + 'static,
662{
663    let (crypto_out, crypto_in, binding) = crypt.split_relay_layer();
664    let (crypto_out, crypto_in) = (Box::new(crypto_out), Box::new(crypto_in));
665
666    (crypto_out, crypto_in, binding)
667}
668
669/// An error that occurred while handling a CREATE* request.
670#[derive(Debug, thiserror::Error)]
671enum HandleCreateError {
672    /// Circuit relay handshake failed.
673    #[error("Circuit relay handshake failed")]
674    Handshake(#[from] RelayHandshakeError),
675    /// Circuit relay handshake failed.
676    #[error("Failed to process the circuit relay handshake parameters")]
677    HandshakeParameters(#[from] HandshakeParamsError),
678    /// Requested subprotocols which aren't supported.
679    #[error("Client requested subprotocol(s) which aren't supported")]
680    HandshakeSubprotocols(#[from] InvalidHandshakeSubprotocolError),
681    /// The requested handshake type is unsupported.
682    #[error("Unsupported handshake type {0}")]
683    Create2HandshakeType(HandshakeType),
684    /// A memquota error.
685    #[error("Memquota error")]
686    Memquota(#[from] tor_memquota::Error),
687    /// Error when spawning a task.
688    #[error("Runtime task spawn error")]
689    Spawn(#[from] futures::task::SpawnError),
690    /// An internal error.
691    ///
692    /// Note that other variants (such as `Handshake` containing a [`RelayHandshakeError`])
693    /// may themselves contain internal errors.
694    #[error("Internal error")]
695    Internal(#[from] tor_error::Bug),
696}
697
698impl HasKind for HandleCreateError {
699    fn kind(&self) -> ErrorKind {
700        match self {
701            Self::Handshake(e) => e.kind(),
702            Self::HandshakeParameters(e) => e.kind(),
703            Self::HandshakeSubprotocols(e) => e.kind(),
704            Self::Create2HandshakeType(_) => ErrorKind::NotImplemented,
705            Self::Memquota(e) => e.kind(),
706            Self::Spawn(e) => e.kind(),
707            Self::Internal(_) => ErrorKind::Internal,
708        }
709    }
710}
711
712/// The components of a completed CREATE* handshake.
713struct CompletedHandshakeComponents {
714    /// The message to send in response.
715    response: CreateResponse,
716    /// The negotiated hop settings.
717    hop_settings: HopSettings,
718    /// Outbound onion crypto.
719    crypto_out: Box<dyn OutboundRelayLayer + Send>,
720    /// Inbound onion crypto.
721    crypto_in: Box<dyn InboundRelayLayer + Send>,
722}
723
724/// A collection of objects built for a new relay circuit.
725pub(crate) struct RelayCircComponents {
726    /// The relay circuit handle.
727    pub(crate) circ: Arc<RelayCirc>,
728    /// Used to send data from the channel to the circuit reactor.
729    pub(crate) sender: CircuitRxSender,
730    /// The circuit's padding controller.
731    pub(crate) padding_ctrl: PaddingController,
732}
733
734/// Congestion control network parameters.
735#[derive(Debug, Clone)]
736#[allow(clippy::exhaustive_structs)]
737pub struct CongestionControlNetParams {
738    /// Fixed-window algorithm parameters.
739    pub fixed_window: FixedWindowParams,
740
741    /// Vegas algorithm parameters for exit circuits.
742    // NOTE: In this module we are handling CREATE* cells,
743    // which only happens for non-hs circuits.
744    // So we don't need to store the vegas hs parameters here.
745    pub vegas_exit: VegasParams,
746
747    /// Congestion window parameters.
748    pub cwnd: CongestionWindowParams,
749
750    /// RTT calculation parameters.
751    pub rtt: RoundTripEstimatorParams,
752
753    /// Flow control parameters to use for all streams on this circuit.
754    pub flow_ctrl: FlowCtrlParameters,
755}
756
757impl CongestionControlNetParams {
758    #[cfg(test)]
759    // These have been copied from C-tor.
760    pub(crate) fn defaults_for_tests() -> Self {
761        Self {
762            fixed_window: FixedWindowParams::defaults_for_tests(),
763            vegas_exit: VegasParams::defaults_for_tests(),
764            cwnd: CongestionWindowParams::defaults_for_tests(),
765            rtt: RoundTripEstimatorParams::defaults_for_tests(),
766            flow_ctrl: FlowCtrlParameters::defaults_for_tests(),
767        }
768    }
769}
770
771/// Network consensus parameters for handling incoming circuits.
772///
773/// Unlike `CircParameters`,
774/// this is unopinionated and contains all relevant consensus parameters,
775/// which is needed when handling an incoming CREATE* request where the
776/// circuit origin chooses the type/settings
777/// (for example congestion control type) of the circuit.
778#[derive(Debug, Clone)]
779#[allow(clippy::exhaustive_structs)]
780pub struct CircNetParameters {
781    /// Congestion control network parameters.
782    pub cc: CongestionControlNetParams,
783}
784
785/// An [`IncomingStreamRequestFilter`] factory for building [`IncomingStreamRequestFilter`]s.
786///
787/// Each time a new circuit is opened, the [`CreateRequestHandler`] calls
788/// [`IncomingStreamRequestFilterFactory::current_filter`] to build
789/// an [`IncomingStreamRequestFilter`] for the circuit.
790pub trait IncomingStreamRequestFilterFactory {
791    /// Return the [`IncomingStreamRequestFilter`] to apply to the incoming stream requests
792    /// arriving on a circuit.
793    fn current_filter(&self) -> Box<dyn IncomingStreamRequestFilter>;
794}
795
796impl<F> IncomingStreamRequestFilterFactory for F
797where
798    F: Fn() -> Box<dyn IncomingStreamRequestFilter>,
799{
800    fn current_filter(&self) -> Box<dyn IncomingStreamRequestFilter> {
801        (self)()
802    }
803}
804
805#[cfg(test)]
806mod test {
807    // @@ begin test lint list maintained by maint/add_warning @@
808    #![allow(clippy::bool_assert_comparison)]
809    #![allow(clippy::clone_on_copy)]
810    #![allow(clippy::dbg_macro)]
811    #![allow(clippy::mixed_attributes_style)]
812    #![allow(clippy::print_stderr)]
813    #![allow(clippy::print_stdout)]
814    #![allow(clippy::single_char_pattern)]
815    #![allow(clippy::unwrap_used)]
816    #![allow(clippy::unchecked_time_subtraction)]
817    #![allow(clippy::useless_vec)]
818    #![allow(clippy::needless_pass_by_value)]
819    #![allow(clippy::string_slice)] // See arti#2571
820    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
821
822    use tor_cell::chancell::msg::{AnyChanMsg, Create2, CreateFast, HandshakeType};
823    use tor_cell::chancell::{AnyChanCell, ChanCmd, ChanMsg as _};
824    use tor_rtcompat::test_with_one_runtime;
825
826    use crate::channel::test_utils;
827    use crate::circuit::CircParameters;
828
829    /// Test the CREATE_FAST handshake.
830    #[test]
831    fn create_fast() {
832        test_with_one_runtime!(|rt| async move {
833            let mut conn_inspector = test_utils::ConnInspector::new();
834
835            let (client_chan, relay_chan, _circuit_stream_rx, _target_builder) =
836                test_utils::new_channel_pair_with_keys(&rt, &conn_inspector);
837
838            let pending_tunnel = test_utils::new_pending_tunnel(&rt, &client_chan).await;
839
840            let circ_params = CircParameters::default();
841
842            let tunnel = pending_tunnel
843                .create_firsthop_fast(circ_params)
844                .await
845                .unwrap();
846
847            // Client sent a CREATE_FAST, relay responded with a CREATED_FAST.
848            assert_eq!(
849                conn_inspector.try_client_cell().unwrap().msg().cmd(),
850                ChanCmd::CREATE_FAST,
851            );
852            assert_eq!(
853                conn_inspector.try_relay_cell().unwrap().msg().cmd(),
854                ChanCmd::CREATED_FAST,
855            );
856
857            drop(tunnel);
858
859            assert_eq!(
860                conn_inspector.client_cell().await.unwrap().msg().cmd(),
861                ChanCmd::DESTROY,
862            );
863
864            // Wait for both channels to close (ignoring any channel errors).
865            let wait_fut =
866                futures::future::join(client_chan.wait_for_close(), relay_chan.wait_for_close());
867            drop((client_chan, relay_chan));
868            let _ = wait_fut.await;
869
870            // We don't expect any other messages to have been sent.
871            assert!(conn_inspector.try_client_cell().is_none());
872            assert!(conn_inspector.try_relay_cell().is_none());
873        });
874    }
875
876    /// Test the CREATE_FAST handshake, but with a modified handshake payload.
877    #[test]
878    fn create_fast_fail() {
879        test_with_one_runtime!(|rt| async move {
880            let mut conn_inspector = test_utils::ConnInspector::new();
881
882            // Rewrite any client-sent CREATE_FAST messages to cause the client to fail the
883            // handshake when processing the CREATED_FAST.
884            conn_inspector.set_client_cell_modifier(|cell: &mut AnyChanCell| {
885                let circ_id = cell.circid();
886                if let AnyChanMsg::CreateFast(msg) = cell.msg() {
887                    let mut new_handshake = msg.handshake().to_vec();
888
889                    // Flip all bits.
890                    for byte in &mut new_handshake {
891                        *byte = !*byte;
892                    }
893
894                    // Reassemble the CREATE_FAST cell with the incorrect handshake body.
895                    let new_msg = CreateFast::new(new_handshake);
896                    *cell = AnyChanCell::new(circ_id, AnyChanMsg::CreateFast(new_msg));
897                }
898            });
899
900            let (client_chan, relay_chan, _circuit_stream_rx, _target_builder) =
901                test_utils::new_channel_pair_with_keys(&rt, &conn_inspector);
902
903            let pending_tunnel = test_utils::new_pending_tunnel(&rt, &client_chan).await;
904
905            let circ_params = CircParameters::default();
906
907            // I don't think it's possible to modify the CREATE_FAST cell to make the relay fail the
908            // handshake (the CREATE_FAST payload consists of only random bytes),
909            // so the relay will respond successfully with a CREATED_FAST.
910            // But the client will fail since the CREATED_FAST will contain garbage bytes.
911
912            // The relay successfully processed the handshake,
913            // but the client fails to validate the handshake since the handshake data was modified.
914            assert!(matches!(
915                pending_tunnel.create_firsthop_fast(circ_params).await,
916                Err(crate::Error::BadCircHandshakeAuth),
917            ));
918
919            // Client sent a CREATE_FAST, relay responded with a CREATED_FAST.
920            assert_eq!(
921                conn_inspector.try_client_cell().unwrap().msg().cmd(),
922                ChanCmd::CREATE_FAST,
923            );
924            assert_eq!(
925                conn_inspector.try_relay_cell().unwrap().msg().cmd(),
926                ChanCmd::CREATED_FAST,
927            );
928
929            // Since the `create_firsthop_fast()` failed above,
930            // the client should have sent a DESTROY.
931            assert_eq!(
932                conn_inspector.client_cell().await.unwrap().msg().cmd(),
933                ChanCmd::DESTROY,
934            );
935
936            // Wait for both channels to close (ignoring any channel errors).
937            let wait_fut =
938                futures::future::join(client_chan.wait_for_close(), relay_chan.wait_for_close());
939            drop((client_chan, relay_chan));
940            let _ = wait_fut.await;
941
942            // We don't expect any other messages to have been sent.
943            assert!(conn_inspector.try_client_cell().is_none());
944            assert!(conn_inspector.try_relay_cell().is_none());
945        });
946    }
947
948    /// Test the client with the "Relay=1" subprotocol (corresponds to the TAP handshake),
949    /// which Arti doesn't support.
950    #[test]
951    fn tap() {
952        test_with_one_runtime!(|rt| async move {
953            let mut conn_inspector = test_utils::ConnInspector::new();
954
955            let (client_chan, _relay_chan, _circuit_stream_rx, mut target_builder) =
956                test_utils::new_channel_pair_with_keys(&rt, &conn_inspector);
957
958            let pending_tunnel = test_utils::new_pending_tunnel(&rt, &client_chan).await;
959
960            let circ_params = CircParameters::default();
961
962            // https://spec.torproject.org/tor-spec/subprotocol-versioning.html
963            // 1 = RELAY_BASE
964            let protocols = "Relay=1".parse().unwrap();
965            let target = target_builder.protocols(protocols).build().unwrap();
966
967            // TODO: This should fail since we don't support TAP handshakes.
968            // But the channel will do an ntor handshake anyway even though it's not supported.
969            // https://gitlab.torproject.org/tpo/core/arti/-/work_items/2489
970            let _tunnel = pending_tunnel
971                .create_firsthop(&target, circ_params)
972                .await
973                .unwrap();
974
975            // TODO: As above, this is wrong.
976            assert_eq!(
977                conn_inspector.try_client_cell().unwrap().msg().cmd(),
978                ChanCmd::CREATE2,
979            );
980            assert_eq!(
981                conn_inspector.try_relay_cell().unwrap().msg().cmd(),
982                ChanCmd::CREATED2,
983            );
984        });
985    }
986
987    /// Test the CREATE2 ntor handshake.
988    #[test]
989    fn ntor() {
990        test_with_one_runtime!(|rt| async move {
991            let mut conn_inspector = test_utils::ConnInspector::new();
992
993            let (client_chan, relay_chan, _circuit_stream_rx, mut target_builder) =
994                test_utils::new_channel_pair_with_keys(&rt, &conn_inspector);
995
996            // https://spec.torproject.org/tor-spec/subprotocol-versioning.html
997            // 2 = RELAY_NTOR
998            // 3 = RELAY_EXTEND_IPv6
999            for relay_version in [2, 3] {
1000                let pending_tunnel = test_utils::new_pending_tunnel(&rt, &client_chan).await;
1001
1002                let circ_params = CircParameters::default();
1003
1004                let protocols = format!("Relay=2-{relay_version}").parse().unwrap();
1005                let target = target_builder.protocols(protocols).build().unwrap();
1006
1007                let tunnel = pending_tunnel
1008                    .create_firsthop(&target, circ_params)
1009                    .await
1010                    .unwrap();
1011
1012                let client_cell = conn_inspector.try_client_cell().unwrap().msg().clone();
1013                let relay_cell = conn_inspector.try_relay_cell().unwrap().msg().clone();
1014
1015                // Client sent a CREATE2, relay responded with a CREATED2.
1016                assert_eq!(client_cell.cmd(), ChanCmd::CREATE2);
1017                assert_eq!(relay_cell.cmd(), ChanCmd::CREATED2);
1018
1019                // Check that it was an ntor handshake.
1020                let AnyChanMsg::Create2(client_cell) = client_cell else {
1021                    unreachable!("CREATE2 checked above");
1022                };
1023                assert_eq!(client_cell.handshake_type(), HandshakeType::NTOR);
1024
1025                drop(tunnel);
1026
1027                assert_eq!(
1028                    conn_inspector.client_cell().await.unwrap().msg().cmd(),
1029                    ChanCmd::DESTROY,
1030                );
1031
1032                // We don't expect any other messages to have been sent.
1033                assert!(conn_inspector.try_client_cell().is_none());
1034                assert!(conn_inspector.try_relay_cell().is_none());
1035            }
1036
1037            // Wait for both channels to close (ignoring any channel errors).
1038            let wait_fut =
1039                futures::future::join(client_chan.wait_for_close(), relay_chan.wait_for_close());
1040            drop((client_chan, relay_chan));
1041            let _ = wait_fut.await;
1042
1043            // We don't expect any other messages to have been sent.
1044            assert!(conn_inspector.try_client_cell().is_none());
1045            assert!(conn_inspector.try_relay_cell().is_none());
1046        });
1047    }
1048
1049    /// Test the CREATE2 ntor handshake, but with a modified handshake payload.
1050    #[test]
1051    fn ntor_fail() {
1052        test_with_one_runtime!(|rt| async move {
1053            let mut conn_inspector = test_utils::ConnInspector::new();
1054
1055            // Rewrite any client-sent CREATE2 messages to cause the relay to fail the handshake.
1056            conn_inspector.set_client_cell_modifier(|cell: &mut AnyChanCell| {
1057                let circ_id = cell.circid();
1058                if let AnyChanMsg::Create2(msg) = cell.msg() {
1059                    let mut new_body = msg.body().to_vec();
1060
1061                    // Flip some arbitrarily chosen byte.
1062                    new_body[10] = !new_body[10];
1063
1064                    // Reassemble the CREATE2 cell with the incorrect handshake body.
1065                    let new_msg = Create2::new(msg.handshake_type(), new_body);
1066                    *cell = AnyChanCell::new(circ_id, AnyChanMsg::Create2(new_msg));
1067                }
1068            });
1069
1070            let (client_chan, relay_chan, _circuit_stream_rx, mut target_builder) =
1071                test_utils::new_channel_pair_with_keys(&rt, &conn_inspector);
1072
1073            // https://spec.torproject.org/tor-spec/subprotocol-versioning.html
1074            // 2 = RELAY_NTOR
1075            // 3 = RELAY_EXTEND_IPv6
1076            for relay_version in [2, 3] {
1077                let pending_tunnel = test_utils::new_pending_tunnel(&rt, &client_chan).await;
1078
1079                let circ_params = CircParameters::default();
1080
1081                let protocols = format!("Relay=2-{relay_version}").parse().unwrap();
1082                let target = target_builder.protocols(protocols).build().unwrap();
1083
1084                // The relay refuses the circuit handshake since the CREATED2 cell had some
1085                // intentional issue with the handshake body.
1086                assert!(matches!(
1087                    pending_tunnel.create_firsthop(&target, circ_params).await,
1088                    Err(crate::Error::CircRefused(_)),
1089                ));
1090
1091                // Client sent a CREATE2, relay responded with a DESTROY.
1092                assert_eq!(
1093                    conn_inspector.try_client_cell().unwrap().msg().cmd(),
1094                    ChanCmd::CREATE2,
1095                );
1096                assert_eq!(
1097                    conn_inspector.try_relay_cell().unwrap().msg().cmd(),
1098                    ChanCmd::DESTROY,
1099                );
1100
1101                // We don't expect any other messages to have been sent.
1102                assert!(conn_inspector.try_client_cell().is_none());
1103                assert!(conn_inspector.try_relay_cell().is_none());
1104            }
1105
1106            // Wait for both channels to close (ignoring any channel errors).
1107            let wait_fut =
1108                futures::future::join(client_chan.wait_for_close(), relay_chan.wait_for_close());
1109            drop((client_chan, relay_chan));
1110            let _ = wait_fut.await;
1111
1112            // We don't expect any other messages to have been sent.
1113            assert!(conn_inspector.try_client_cell().is_none());
1114            assert!(conn_inspector.try_relay_cell().is_none());
1115        });
1116    }
1117
1118    /// Test the CREATE2 ntor-v3 handshake.
1119    #[test]
1120    fn ntor_v3() {
1121        test_with_one_runtime!(|rt| async move {
1122            let mut conn_inspector = test_utils::ConnInspector::new();
1123
1124            let (client_chan, relay_chan, _circuit_stream_rx, mut target_builder) =
1125                test_utils::new_channel_pair_with_keys(&rt, &conn_inspector);
1126
1127            // https://spec.torproject.org/tor-spec/subprotocol-versioning.html
1128            // 4 = RELAY_NTORV3
1129            // 5 = RELAY_NEGOTIATE_SUBPROTO
1130            // 6 = RELAY_CRYPT_CGO
1131            for relay_version in [4, 5, 6] {
1132                let pending_tunnel = test_utils::new_pending_tunnel(&rt, &client_chan).await;
1133
1134                let circ_params = CircParameters::default();
1135
1136                let protocols = format!("Relay=4-{relay_version}").parse().unwrap();
1137                let target = target_builder.protocols(protocols).build().unwrap();
1138
1139                let tunnel = pending_tunnel
1140                    .create_firsthop(&target, circ_params)
1141                    .await
1142                    .unwrap();
1143
1144                let client_cell = conn_inspector.try_client_cell().unwrap().msg().clone();
1145                let relay_cell = conn_inspector.try_relay_cell().unwrap().msg().clone();
1146
1147                // Client sent a CREATE2, relay responded with a CREATED2.
1148                assert_eq!(client_cell.cmd(), ChanCmd::CREATE2);
1149                assert_eq!(relay_cell.cmd(), ChanCmd::CREATED2);
1150
1151                // Check that it was an ntor-v3 handshake.
1152                let AnyChanMsg::Create2(client_cell) = client_cell else {
1153                    unreachable!("CREATE2 checked above");
1154                };
1155                assert_eq!(client_cell.handshake_type(), HandshakeType::NTOR_V3);
1156
1157                // TODO: It would be nice if we had a way to check that CGO was in use when
1158                // `relay_version` is >=6, but I don't see a nice way to do that.
1159
1160                drop(tunnel);
1161
1162                assert_eq!(
1163                    conn_inspector.client_cell().await.unwrap().msg().cmd(),
1164                    ChanCmd::DESTROY,
1165                );
1166
1167                // We don't expect any other messages to have been sent.
1168                assert!(conn_inspector.try_client_cell().is_none());
1169                assert!(conn_inspector.try_relay_cell().is_none());
1170            }
1171
1172            // Wait for both channels to close (ignoring any channel errors).
1173            let wait_fut =
1174                futures::future::join(client_chan.wait_for_close(), relay_chan.wait_for_close());
1175            drop((client_chan, relay_chan));
1176            let _ = wait_fut.await;
1177
1178            // We don't expect any other messages to have been sent.
1179            assert!(conn_inspector.try_client_cell().is_none());
1180            assert!(conn_inspector.try_relay_cell().is_none());
1181        });
1182    }
1183
1184    /// Test the CREATE2 ntor-v3 handshake, but with a modified handshake payload.
1185    #[test]
1186    fn ntor_v3_fail() {
1187        test_with_one_runtime!(|rt| async move {
1188            let mut conn_inspector = test_utils::ConnInspector::new();
1189
1190            // Rewrite any client-sent CREATE2 messages to cause the relay to fail the handshake.
1191            conn_inspector.set_client_cell_modifier(|cell: &mut AnyChanCell| {
1192                let circ_id = cell.circid();
1193                if let AnyChanMsg::Create2(msg) = cell.msg() {
1194                    let mut new_body = msg.body().to_vec();
1195
1196                    // Flip some arbitrarily chosen byte.
1197                    new_body[10] = !new_body[10];
1198
1199                    // Reassemble the CREATE2 cell with the incorrect handshake body.
1200                    let new_msg = Create2::new(msg.handshake_type(), new_body);
1201                    *cell = AnyChanCell::new(circ_id, AnyChanMsg::Create2(new_msg));
1202                }
1203            });
1204
1205            let (client_chan, relay_chan, _circuit_stream_rx, mut target_builder) =
1206                test_utils::new_channel_pair_with_keys(&rt, &conn_inspector);
1207
1208            // https://spec.torproject.org/tor-spec/subprotocol-versioning.html
1209            // 4 = RELAY_NTORV3
1210            // 5 = RELAY_NEGOTIATE_SUBPROTO
1211            // 6 = RELAY_CRYPT_CGO
1212            for relay_version in [4, 5, 6] {
1213                let pending_tunnel = test_utils::new_pending_tunnel(&rt, &client_chan).await;
1214
1215                let circ_params = CircParameters::default();
1216
1217                let protocols = format!("Relay=4-{relay_version}").parse().unwrap();
1218                let target = target_builder.protocols(protocols).build().unwrap();
1219
1220                // The relay refuses the circuit handshake since the CREATED2 cell had some
1221                // intentional issue with the handshake body.
1222                assert!(matches!(
1223                    pending_tunnel.create_firsthop(&target, circ_params).await,
1224                    Err(crate::Error::CircRefused(_)),
1225                ));
1226
1227                // Client sent a CREATE2, relay responded with a DESTROY.
1228                assert_eq!(
1229                    conn_inspector.try_client_cell().unwrap().msg().cmd(),
1230                    ChanCmd::CREATE2,
1231                );
1232                assert_eq!(
1233                    conn_inspector.try_relay_cell().unwrap().msg().cmd(),
1234                    ChanCmd::DESTROY,
1235                );
1236
1237                // We don't expect any other messages to have been sent.
1238                assert!(conn_inspector.try_client_cell().is_none());
1239                assert!(conn_inspector.try_relay_cell().is_none());
1240            }
1241
1242            // Wait for both channels to close (ignoring any channel errors).
1243            let wait_fut =
1244                futures::future::join(client_chan.wait_for_close(), relay_chan.wait_for_close());
1245            drop((client_chan, relay_chan));
1246            let _ = wait_fut.await;
1247
1248            // We don't expect any other messages to have been sent.
1249            assert!(conn_inspector.try_client_cell().is_none());
1250            assert!(conn_inspector.try_relay_cell().is_none());
1251        });
1252    }
1253
1254    /// Test the CREATE2 handshake, but with an invalid handshake type.
1255    #[test]
1256    fn create2_invalid_handshake_fail() {
1257        test_with_one_runtime!(|rt| async move {
1258            let mut conn_inspector = test_utils::ConnInspector::new();
1259
1260            // Rewrite any client-sent CREATE2 messages to cause the relay to fail the handshake.
1261            conn_inspector.set_client_cell_modifier(|cell: &mut AnyChanCell| {
1262                let circ_id = cell.circid();
1263                if let AnyChanMsg::Create2(msg) = cell.msg() {
1264                    // Reassemble the CREATE2 cell with the incorrect handshake type.
1265                    let new_msg = tor_cell::chancell::msg::Create2::new(99.into(), msg.body());
1266                    *cell = AnyChanCell::new(circ_id, AnyChanMsg::Create2(new_msg));
1267                }
1268            });
1269
1270            let (client_chan, relay_chan, _circuit_stream_rx, mut target_builder) =
1271                test_utils::new_channel_pair_with_keys(&rt, &conn_inspector);
1272
1273            // https://spec.torproject.org/tor-spec/subprotocol-versioning.html
1274            // 2 = RELAY_NTOR
1275            // 3 = RELAY_EXTEND_IPv6
1276            // 4 = RELAY_NTORV3
1277            // 5 = RELAY_NEGOTIATE_SUBPROTO
1278            // 6 = RELAY_CRYPT_CGO
1279            for relay_version in [2, 6] {
1280                let pending_tunnel = test_utils::new_pending_tunnel(&rt, &client_chan).await;
1281
1282                let circ_params = CircParameters::default();
1283
1284                let protocols = format!("Relay=2-{relay_version}").parse().unwrap();
1285                let target = target_builder.protocols(protocols).build().unwrap();
1286
1287                // The relay refuses the circuit handshake since the CREATED2 cell had some
1288                // unrecognized handshake type.
1289                assert!(matches!(
1290                    pending_tunnel.create_firsthop(&target, circ_params).await,
1291                    Err(crate::Error::CircRefused(_)),
1292                ));
1293
1294                // Client sent a CREATE2, relay responded with a DESTROY.
1295                assert_eq!(
1296                    conn_inspector.try_client_cell().unwrap().msg().cmd(),
1297                    ChanCmd::CREATE2,
1298                );
1299                assert_eq!(
1300                    conn_inspector.try_relay_cell().unwrap().msg().cmd(),
1301                    ChanCmd::DESTROY,
1302                );
1303
1304                // We don't expect any other messages to have been sent.
1305                assert!(conn_inspector.try_client_cell().is_none());
1306                assert!(conn_inspector.try_relay_cell().is_none());
1307            }
1308
1309            // Wait for both channels to close (ignoring any channel errors).
1310            let wait_fut =
1311                futures::future::join(client_chan.wait_for_close(), relay_chan.wait_for_close());
1312            drop((client_chan, relay_chan));
1313            let _ = wait_fut.await;
1314
1315            // We don't expect any other messages to have been sent.
1316            assert!(conn_inspector.try_client_cell().is_none());
1317            assert!(conn_inspector.try_relay_cell().is_none());
1318        });
1319    }
1320}