Debian Codegraph @

third_party/rust/neqo-transport/src/connection/mod.rs

raw
1 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
2 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
3 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
4 // option. This file may not be copied, modified, or distributed
5 // except according to those terms.
6
7 // The class implementing a QUIC connection.
8
9 use std::{
10 cell::RefCell,
11 cmp::{max, min},
12 fmt::{self, Debug, Display, Formatter, Write as _},
13 iter, mem,
14 net::{IpAddr, SocketAddr},
15 num::NonZeroUsize,
16 ops::RangeInclusive,
17 rc::{Rc, Weak},
18 time::{Duration, Instant},
19 };
20
21 use neqo_common::{
22 event::Provider as EventProvider, hex, hex_snip_middle, hrtime, qdebug, qerror, qinfo,
23 qlog::NeqoQlog, qtrace, qwarn, Datagram, Decoder, Encoder, IpTos, IpTosEcn, Role,
24 };
25 use neqo_crypto::{
26 agent::CertificateInfo, Agent, AntiReplay, AuthenticationStatus, Cipher, Client, Group,
27 HandshakeState, PrivateKey, PublicKey, ResumptionToken, SecretAgentInfo, SecretAgentPreInfo,
28 Server, ZeroRttChecker,
29 };
30 use smallvec::SmallVec;
31 use strum::IntoEnumIterator as _;
32
33 use crate::{
34 addr_valid::{AddressValidation, NewTokenState},
35 cid::{
36 ConnectionId, ConnectionIdEntry, ConnectionIdGenerator, ConnectionIdManager,
37 ConnectionIdRef, ConnectionIdStore, LOCAL_ACTIVE_CID_LIMIT,
38 },
39 crypto::{Crypto, CryptoDxState, Epoch},
40 ecn,
41 events::{ConnectionEvent, ConnectionEvents, OutgoingDatagramOutcome},
42 frame::{CloseError, Frame, FrameType},
43 packet::{self, DecryptedPacket, PacketBuilder, PacketNumber, PacketType, PublicPacket},
44 path::{Path, PathRef, Paths},
45 qlog,
46 quic_datagrams::{DatagramTracking, QuicDatagrams},
47 recovery::{LossRecovery, RecoveryToken, SendProfile, SentPacket},
48 recv_stream::RecvStreamStats,
49 rtt::{RttEstimate, GRANULARITY, INITIAL_RTT},
50 send_stream::SendStream,
51 stats::{Stats, StatsCell},
52 stream_id::StreamType,
53 streams::{SendOrder, Streams},
54 tparams::{
55 self,
56 TransportParameterId::{
57 self, AckDelayExponent, ActiveConnectionIdLimit, DisableMigration, GreaseQuicBit,
58 InitialSourceConnectionId, MaxAckDelay, MaxDatagramFrameSize, MinAckDelay,
59 OriginalDestinationConnectionId, RetrySourceConnectionId, StatelessResetToken,
60 },
61 TransportParameters, TransportParametersHandler,
62 },
63 tracking::{AckTracker, PacketNumberSpace, RecvdPackets},
64 version::{Version, WireVersion},
65 AppError, CloseReason, Error, Res, StreamId,
66 };
67
68 mod idle;
69 pub mod params;
70 mod saved;
71 mod state;
72 #[cfg(test)]
73 pub mod test_internal;
74
75 use idle::IdleTimeout;
76 pub use params::ConnectionParameters;
77 use params::PreferredAddressConfig;
78 #[cfg(test)]
79 pub use params::ACK_RATIO_SCALE;
80 use saved::SavedDatagrams;
81 use state::StateSignaling;
82 pub use state::{ClosingFrame, State};
83
84 pub use crate::send_stream::{RetransmissionPriority, SendStreamStats, TransmissionPriority};
85
86 /// The number of Initial packets that the client will send in response
87 /// to receiving an undecryptable packet during the early part of the
88 /// handshake. This is a hack, but a useful one.
89 const EXTRA_INITIALS: usize = 4;
90
91 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
92 pub enum ZeroRttState {
93 Init,
94 Sending,
95 AcceptedClient,
96 AcceptedServer,
97 Rejected,
98 }
99
100 #[derive(Clone, Debug, PartialEq, Eq)]
101 /// Type returned from `process()` and `process_output()`. Users are required to
102 /// call these repeatedly until `Callback` or `None` is returned.
103 pub enum Output {
104 /// Connection requires no action.
105 None,
106 /// Connection requires the datagram be sent.
107 Datagram(Datagram),
108 /// Connection requires `process_input()` be called when the `Duration`
109 /// elapses.
110 Callback(Duration),
111 }
112
113 impl Output {
114 /// Convert into an `Option<Datagram>`.
115 #[must_use]
116 pub fn dgram(self) -> Option<Datagram> {
117 match self {
118 Self::Datagram(dg) => Some(dg),
119 _ => None,
120 }
121 }
122
123 /// Get a reference to the Datagram, if any.
124 #[must_use]
125 pub const fn as_dgram_ref(&self) -> Option<&Datagram> {
126 match self {
127 Self::Datagram(dg) => Some(dg),
128 _ => None,
129 }
130 }
131
132 /// Ask how long the caller should wait before calling back.
133 #[must_use]
134 pub const fn callback(&self) -> Duration {
135 match self {
136 Self::Callback(t) => *t,
137 _ => Duration::new(0, 0),
138 }
139 }
140
141 #[must_use]
142 pub fn or_else<F>(self, f: F) -> Self
143 where
144 F: FnOnce() -> Self,
145 {
146 match self {
147 x @ (Self::Datagram(_) | Self::Callback(_)) => x,
148 Self::None => f(),
149 }
150 }
151 }
152
153 impl From<Option<Datagram>> for Output {
154 fn from(value: Option<Datagram>) -> Self {
155 value.map_or(Self::None, Self::Datagram)
156 }
157 }
158
159 /// Used by inner functions like `Connection::output`.
160 enum SendOption {
161 /// Yes, please send this datagram.
162 Yes(Datagram),
163 /// Don't send. If this was blocked on the pacer (the arg is true).
164 No(bool),
165 }
166
167 impl Default for SendOption {
168 fn default() -> Self {
169 Self::No(false)
170 }
171 }
172
173 /// Used by `Connection::preprocess` to determine what to do
174 /// with an packet before attempting to remove protection.
175 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
176 enum PreprocessResult {
177 /// End processing and return successfully.
178 End,
179 /// Stop processing this datagram and move on to the next.
180 Next,
181 /// Continue and process this packet.
182 Continue,
183 }
184
185 /// `AddressValidationInfo` holds information relevant to either
186 /// responding to address validation (`NewToken`, `Retry`) or generating
187 /// tokens for address validation (`Server`).
188 enum AddressValidationInfo {
189 None,
190 // We are a client and have information from `NEW_TOKEN`.
191 NewToken(Vec<u8>),
192 // We are a client and have received a `Retry` packet.
193 Retry {
194 token: Vec<u8>,
195 retry_source_cid: ConnectionId,
196 },
197 // We are a server and can generate tokens.
198 Server(Weak<RefCell<AddressValidation>>),
199 }
200
201 impl AddressValidationInfo {
202 pub fn token(&self) -> &[u8] {
203 match self {
204 Self::NewToken(token) | Self::Retry { token, .. } => token,
205 _ => &[],
206 }
207 }
208
209 pub fn generate_new_token(&self, peer_address: SocketAddr, now: Instant) -> Option<Vec<u8>> {
210 match self {
211 Self::Server(w) => w
212 .upgrade()?
213 .borrow()
214 .generate_new_token(peer_address, now)
215 .ok(),
216 Self::None => None,
217 _ => unreachable!("called a server function on a client"),
218 }
219 }
220 }
221
222 /// A QUIC Connection
223 ///
224 /// First, create a new connection using `new_client()` or `new_server()`.
225 ///
226 /// For the life of the connection, handle activity in the following manner:
227 /// 1. Perform operations using the `stream_*()` methods.
228 /// 1. Call `process_input()` when a datagram is received or the timer expires. Obtain information
229 /// on connection state changes by checking `events()`.
230 /// 1. Having completed handling current activity, repeatedly call `process_output()` for packets to
231 /// send, until it returns `Output::Callback` or `Output::None`.
232 ///
233 /// After the connection is closed (either by calling `close()` or by the
234 /// remote) continue processing until `state()` returns `Closed`.
235 pub struct Connection {
236 role: Role,
237 version: Version,
238 state: State,
239 tps: Rc<RefCell<TransportParametersHandler>>,
240 /// What we are doing with 0-RTT.
241 zero_rtt_state: ZeroRttState,
242 /// All of the network paths that we are aware of.
243 paths: Paths,
244 /// This object will generate connection IDs for the connection.
245 cid_manager: ConnectionIdManager,
246 address_validation: AddressValidationInfo,
247 /// The connection IDs that were provided by the peer.
248 cids: ConnectionIdStore<[u8; 16]>,
249
250 /// The source connection ID that this endpoint uses for the handshake.
251 /// Since we need to communicate this to our peer in tparams, setting this
252 /// value is part of constructing the struct.
253 local_initial_source_cid: ConnectionId,
254 /// The source connection ID from the first packet from the other end.
255 /// This is checked against the peer's transport parameters.
256 remote_initial_source_cid: Option<ConnectionId>,
257 /// The destination connection ID from the first packet from the client.
258 /// This is checked by the client against the server's transport parameters.
259 original_destination_cid: Option<ConnectionId>,
260
261 /// We sometimes save a datagram against the possibility that keys will later
262 /// become available. This avoids reporting packets as dropped during the handshake
263 /// when they are either just reordered or we haven't been able to install keys yet.
264 /// In particular, this occurs when asynchronous certificate validation happens.
265 saved_datagrams: SavedDatagrams,
266 /// Some packets were received, but not tracked.
267 received_untracked: bool,
268
269 /// This is responsible for the `QuicDatagrams`' handling:
270 /// <https://datatracker.ietf.org/doc/html/draft-ietf-quic-datagram>
271 quic_datagrams: QuicDatagrams,
272
273 crypto: Crypto,
274 acks: AckTracker,
275 idle_timeout: IdleTimeout,
276 streams: Streams,
277 state_signaling: StateSignaling,
278 loss_recovery: LossRecovery,
279 events: ConnectionEvents,
280 new_token: NewTokenState,
281 stats: StatsCell,
282 qlog: NeqoQlog,
283 /// A session ticket was received without `NEW_TOKEN`,
284 /// this is when that turns into an event without `NEW_TOKEN`.
285 release_resumption_token_timer: Option<Instant>,
286 conn_params: ConnectionParameters,
287 hrtime: hrtime::Handle,
288
289 /// For testing purposes it is sometimes necessary to inject frames that wouldn't
290 /// otherwise be sent, just to see how a connection handles them. Inserting them
291 /// into packets proper mean that the frames follow the entire processing path.
292 #[cfg(test)]
293 test_frame_writer: Option<Box<dyn test_internal::FrameWriter>>,
294 }
295
296 impl Debug for Connection {
297 fn fmt(&self, f: &mut Formatter) -> fmt::Result {
298 write!(
299 f,
300 "{:?} Connection: {:?} {:?}",
301 self.role,
302 self.state,
303 self.paths.primary()
304 )
305 }
306 }
307
308 impl Connection {
309 /// A long default for timer resolution, so that we don't tax the
310 /// system too hard when we don't need to.
311 const LOOSE_TIMER_RESOLUTION: Duration = Duration::from_millis(50);
312
313 /// Create a new QUIC connection with Client role.
314 /// # Errors
315 /// When NSS fails and an agent cannot be created.
316 pub fn new_client(
317 server_name: impl Into<String>,
318 protocols: &[impl AsRef<str>],
319 cid_generator: Rc<RefCell<dyn ConnectionIdGenerator>>,
320 local_addr: SocketAddr,
321 remote_addr: SocketAddr,
322 conn_params: ConnectionParameters,
323 now: Instant,
324 ) -> Res<Self> {
325 let dcid = ConnectionId::generate_initial();
326 let mut c = Self::new(
327 Role::Client,
328 Agent::from(Client::new(server_name.into(), conn_params.is_greasing())?),
329 cid_generator,
330 protocols,
331 conn_params,
332 )?;
333 c.crypto.states_mut().init(
334 c.conn_params.get_versions().compatible(),
335 Role::Client,
336 &dcid,
337 )?;
338 c.original_destination_cid = Some(dcid);
339 let path = Path::temporary(
340 local_addr,
341 remote_addr,
342 &c.conn_params,
343 NeqoQlog::default(),
344 now,
345 &mut c.stats.borrow_mut(),
346 );
347 c.setup_handshake_path(&Rc::new(RefCell::new(path)), now);
348 Ok(c)
349 }
350
351 /// Create a new QUIC connection with Server role.
352 /// # Errors
353 /// When NSS fails and an agent cannot be created.
354 pub fn new_server(
355 certs: &[impl AsRef<str>],
356 protocols: &[impl AsRef<str>],
357 cid_generator: Rc<RefCell<dyn ConnectionIdGenerator>>,
358 conn_params: ConnectionParameters,
359 ) -> Res<Self> {
360 Self::new(
361 Role::Server,
362 Agent::from(Server::new(certs)?),
363 cid_generator,
364 protocols,
365 conn_params,
366 )
367 }
368
369 fn new<P: AsRef<str>>(
370 role: Role,
371 agent: Agent,
372 cid_generator: Rc<RefCell<dyn ConnectionIdGenerator>>,
373 protocols: &[P],
374 conn_params: ConnectionParameters,
375 ) -> Res<Self> {
376 // Setup the local connection ID.
377 let local_initial_source_cid = cid_generator
378 .borrow_mut()
379 .generate_cid()
380 .ok_or(Error::ConnectionIdsExhausted)?;
381 let mut cid_manager =
382 ConnectionIdManager::new(cid_generator, local_initial_source_cid.clone());
383 let mut tps = conn_params.create_transport_parameter(role, &mut cid_manager)?;
384 tps.local_mut()
385 .set_bytes(InitialSourceConnectionId, local_initial_source_cid.to_vec());
386
387 let tphandler = Rc::new(RefCell::new(tps));
388 let crypto = Crypto::new(
389 conn_params.get_versions().initial(),
390 &conn_params,
391 agent,
392 protocols.iter().map(P::as_ref).map(String::from).collect(),
393 Rc::clone(&tphandler),
394 )?;
395
396 let stats = StatsCell::default();
397 let events = ConnectionEvents::default();
398 let quic_datagrams = QuicDatagrams::new(
399 conn_params.get_datagram_size(),
400 conn_params.get_outgoing_datagram_queue(),
401 conn_params.get_incoming_datagram_queue(),
402 events.clone(),
403 );
404
405 let c = Self {
406 role,
407 version: conn_params.get_versions().initial(),
408 state: State::Init,
409 paths: Paths::default(),
410 cid_manager,
411 tps: Rc::clone(&tphandler),
412 zero_rtt_state: ZeroRttState::Init,
413 address_validation: AddressValidationInfo::None,
414 local_initial_source_cid,
415 remote_initial_source_cid: None,
416 original_destination_cid: None,
417 saved_datagrams: SavedDatagrams::default(),
418 received_untracked: false,
419 crypto,
420 acks: AckTracker::default(),
421 idle_timeout: IdleTimeout::new(conn_params.get_idle_timeout()),
422 streams: Streams::new(tphandler, role, events.clone()),
423 cids: ConnectionIdStore::default(),
424 state_signaling: StateSignaling::Idle,
425 loss_recovery: LossRecovery::new(stats.clone(), conn_params.get_fast_pto()),
426 events,
427 new_token: NewTokenState::new(role),
428 stats,
429 qlog: NeqoQlog::disabled(),
430 release_resumption_token_timer: None,
431 conn_params,
432 hrtime: hrtime::Time::get(Self::LOOSE_TIMER_RESOLUTION),
433 quic_datagrams,
434 #[cfg(test)]
435 test_frame_writer: None,
436 };
437 c.stats.borrow_mut().init(format!("{c}"));
438 Ok(c)
439 }
440
441 /// # Errors
442 /// When the operation fails.
443 pub fn server_enable_0rtt(
444 &mut self,
445 anti_replay: &AntiReplay,
446 zero_rtt_checker: impl ZeroRttChecker + 'static,
447 ) -> Res<()> {
448 self.crypto
449 .server_enable_0rtt(Rc::clone(&self.tps), anti_replay, zero_rtt_checker)
450 }
451
452 /// # Errors
453 /// When the operation fails.
454 pub fn server_enable_ech(
455 &mut self,
456 config: u8,
457 public_name: &str,
458 sk: &PrivateKey,
459 pk: &PublicKey,
460 ) -> Res<()> {
461 self.crypto.server_enable_ech(config, public_name, sk, pk)
462 }
463
464 /// Get the active ECH configuration, which is empty if ECH is disabled.
465 #[must_use]
466 pub fn ech_config(&self) -> &[u8] {
467 self.crypto.ech_config()
468 }
469
470 /// # Errors
471 /// When the operation fails.
472 pub fn client_enable_ech(&mut self, ech_config_list: impl AsRef<[u8]>) -> Res<()> {
473 self.crypto.client_enable_ech(ech_config_list)
474 }
475
476 /// Set or clear the qlog for this connection.
477 pub fn set_qlog(&mut self, qlog: NeqoQlog) {
478 self.loss_recovery.set_qlog(qlog.clone());
479 self.paths.set_qlog(qlog.clone());
480 self.qlog = qlog;
481 }
482
483 /// Get the qlog (if any) for this connection.
484 pub fn qlog_mut(&mut self) -> &mut NeqoQlog {
485 &mut self.qlog
486 }
487
488 /// Get the original destination connection id for this connection. This
489 /// will always be present for `Role::Client` but not if `Role::Server` is in
490 /// `State::Init`.
491 #[must_use]
492 pub const fn odcid(&self) -> Option<&ConnectionId> {
493 self.original_destination_cid.as_ref()
494 }
495
496 /// Set a local transport parameter, possibly overriding a default value.
497 /// This only sets transport parameters without dealing with other aspects of
498 /// setting the value.
499 ///
500 /// # Errors
501 /// When the transport parameter is invalid.
502 /// # Panics
503 /// This panics if the transport parameter is known to this crate.
504 #[cfg(test)]
505 pub fn set_local_tparam(
506 &self,
507 tp: TransportParameterId,
508 value: tparams::TransportParameter,
509 ) -> Res<()> {
510 if *self.state() == State::Init {
511 self.tps.borrow_mut().local_mut().set(tp, value);
512 Ok(())
513 } else {
514 qerror!("Current state: {:?}", self.state());
515 qerror!("Cannot set local tparam when not in an initial connection state");
516 Err(Error::ConnectionState)
517 }
518 }
519
520 /// `odcid` is their original choice for our CID, which we get from the Retry token.
521 /// `remote_cid` is the value from the Source Connection ID field of an incoming packet: what
522 /// the peer wants us to use now. `retry_cid` is what we asked them to use when we sent the
523 /// Retry.
524 pub(crate) fn set_retry_cids(
525 &mut self,
526 odcid: &ConnectionId,
527 remote_cid: ConnectionId,
528 retry_cid: &ConnectionId,
529 ) {
530 debug_assert_eq!(self.role, Role::Server);
531 qtrace!("[{self}] Retry CIDs: odcid={odcid} remote={remote_cid} retry={retry_cid}");
532 // We advertise "our" choices in transport parameters.
533 self.tps
534 .borrow_mut()
535 .local_mut()
536 .set_bytes(OriginalDestinationConnectionId, odcid.to_vec());
537 self.tps
538 .borrow_mut()
539 .local_mut()
540 .set_bytes(RetrySourceConnectionId, retry_cid.to_vec());
541
542 // ...and save their choices for later validation.
543 self.remote_initial_source_cid = Some(remote_cid);
544 }
545
546 fn retry_sent(&self) -> bool {
547 self.tps
548 .borrow()
549 .local()
550 .get_bytes(RetrySourceConnectionId)
551 .is_some()
552 }
553
554 /// Set ALPN preferences. Strings that appear earlier in the list are given
555 /// higher preference.
556 /// # Errors
557 /// When the operation fails, which is usually due to bad inputs or bad connection state.
558 pub fn set_alpn(&mut self, protocols: &[impl AsRef<str>]) -> Res<()> {
559 self.crypto.tls_mut().set_alpn(protocols)?;
560 Ok(())
561 }
562
563 /// Enable a set of ciphers.
564 /// # Errors
565 /// When the operation fails, which is usually due to bad inputs or bad connection state.
566 pub fn set_ciphers(&mut self, ciphers: &[Cipher]) -> Res<()> {
567 if self.state != State::Init {
568 qerror!("[{self}] Cannot enable ciphers in state {:?}", self.state);
569 return Err(Error::ConnectionState);
570 }
571 self.crypto.tls_mut().set_ciphers(ciphers)?;
572 Ok(())
573 }
574
575 /// Enable a set of key exchange groups.
576 /// # Errors
577 /// When the operation fails, which is usually due to bad inputs or bad connection state.
578 pub fn set_groups(&mut self, groups: &[Group]) -> Res<()> {
579 if self.state != State::Init {
580 qerror!("[{self}] Cannot enable groups in state {:?}", self.state);
581 return Err(Error::ConnectionState);
582 }
583 self.crypto.tls_mut().set_groups(groups)?;
584 Ok(())
585 }
586
587 /// Set the number of additional key shares to send in the client hello.
588 /// # Errors
589 /// When the operation fails, which is usually due to bad inputs or bad connection state.
590 pub fn send_additional_key_shares(&mut self, count: usize) -> Res<()> {
591 if self.state != State::Init {
592 qerror!("[{self}] Cannot enable groups in state {:?}", self.state);
593 return Err(Error::ConnectionState);
594 }
595 self.crypto.tls_mut().send_additional_key_shares(count)?;
596 Ok(())
597 }
598
599 fn make_resumption_token(&mut self) -> ResumptionToken {
600 debug_assert_eq!(self.role, Role::Client);
601 debug_assert!(self.crypto.has_resumption_token());
602 // Values less than GRANULARITY are ignored when using the token, so use 0 where needed.
603 let rtt = self.paths.primary().map_or_else(
604 // If we don't have a path, we don't have an RTT.
605 || Duration::from_millis(0),
606 |p| {
607 let rtt = p.borrow().rtt().estimate();
608 if p.borrow().rtt().is_guesstimate() {
609 // When we have no actual RTT sample, do not encode a guestimated RTT larger
610 // than the default initial RTT. (The guess can be very large under lossy
611 // conditions.)
612 if rtt < INITIAL_RTT {
613 rtt
614 } else {
615 Duration::from_millis(0)
616 }
617 } else {
618 rtt
619 }
620 },
621 );
622
623 self.crypto
624 .create_resumption_token(
625 self.new_token.take_token(),
626 self.tps
627 .borrow()
628 .remote_handshake()
629 .as_ref()
630 .expect("should have transport parameters"),
631 self.version,
632 u64::try_from(rtt.as_millis()).unwrap_or(0),
633 )
634 .expect("caller checked if a resumption token existed")
635 }
636
637 fn confirmed(&self) -> bool {
638 self.state == State::Confirmed
639 }
640
641 /// Get the simplest PTO calculation for all those cases where we need
642 /// a value of this approximate order. Don't use this for loss recovery,
643 /// only use it where a more precise value is not important.
644 fn pto(&self) -> Duration {
645 self.paths.primary().map_or_else(
646 || RttEstimate::default().pto(self.confirmed()),
647 |p| p.borrow().rtt().pto(self.confirmed()),
648 )
649 }
650
651 fn create_resumption_token(&mut self, now: Instant) {
652 if self.role == Role::Server || self.state < State::Connected {
653 return;
654 }
655
656 qtrace!(
657 "[{self}] Maybe create resumption token: {} {}",
658 self.crypto.has_resumption_token(),
659 self.new_token.has_token()
660 );
661
662 while self.crypto.has_resumption_token() && self.new_token.has_token() {
663 let token = self.make_resumption_token();
664 self.events.client_resumption_token(token);
665 }
666
667 // If we have a resumption ticket check or set a timer.
668 if self.crypto.has_resumption_token() {
669 let arm = if let Some(expiration_time) = self.release_resumption_token_timer {
670 if expiration_time <= now {
671 let token = self.make_resumption_token();
672 self.events.client_resumption_token(token);
673 self.release_resumption_token_timer = None;
674
675 // This means that we release one session ticket every 3 PTOs
676 // if no NEW_TOKEN frame is received.
677 self.crypto.has_resumption_token()
678 } else {
679 false
680 }
681 } else {
682 true
683 };
684
685 if arm {
686 self.release_resumption_token_timer = Some(now + 3 * self.pto());
687 }
688 }
689 }
690
691 /// The correct way to obtain a resumption token is to wait for the
692 /// `ConnectionEvent::ResumptionToken` event. To emit the event we are waiting for a
693 /// resumption token and a `NEW_TOKEN` frame to arrive. Some servers don't send `NEW_TOKEN`
694 /// frames and in this case, we wait for 3xPTO before emitting an event. This is especially a
695 /// problem for short-lived connections, where the connection is closed before any events are
696 /// released. This function retrieves the token, without waiting for a `NEW_TOKEN` frame to
697 /// arrive.
698 ///
699 /// # Panics
700 ///
701 /// If this is called on a server.
702 pub fn take_resumption_token(&mut self, now: Instant) -> Option<ResumptionToken> {
703 assert_eq!(self.role, Role::Client);
704
705 self.crypto.has_resumption_token().then(|| {
706 let token = self.make_resumption_token();
707 if self.crypto.has_resumption_token() {
708 self.release_resumption_token_timer = Some(now + 3 * self.pto());
709 }
710 token
711 })
712 }
713
714 /// Enable resumption, using a token previously provided.
715 /// This can only be called once and only on the client.
716 /// After calling the function, it should be possible to attempt 0-RTT
717 /// if the token supports that.
718 ///
719 /// This function starts the TLS stack, which means that any configuration change
720 /// to that stack needs to occur prior to calling this.
721 ///
722 /// # Errors
723 /// When the operation fails, which is usually due to bad inputs or bad connection state.
724 pub fn enable_resumption(&mut self, now: Instant, token: impl AsRef<[u8]>) -> Res<()> {
725 if self.state != State::Init {
726 qerror!("[{self}] set token in state {:?}", self.state);
727 return Err(Error::ConnectionState);
728 }
729 if self.role == Role::Server {
730 return Err(Error::ConnectionState);
731 }
732
733 qinfo!(
734 "[{self}] resumption token {}",
735 hex_snip_middle(token.as_ref())
736 );
737 let mut dec = Decoder::from(token.as_ref());
738
739 let version = Version::try_from(
740 dec.decode_uint::<WireVersion>()
741 .ok_or(Error::InvalidResumptionToken)?,
742 )?;
743 qtrace!("[{self}] version {version:?}");
744 if !self.conn_params.get_versions().all().contains(&version) {
745 return Err(Error::DisabledVersion);
746 }
747
748 let rtt = Duration::from_millis(dec.decode_varint().ok_or(Error::InvalidResumptionToken)?);
749 qtrace!("[{self}] RTT {rtt:?}");
750
751 let tp_slice = dec.decode_vvec().ok_or(Error::InvalidResumptionToken)?;
752 qtrace!("[{self}] transport parameters {}", hex(tp_slice));
753 let mut dec_tp = Decoder::from(tp_slice);
754 let tp =
755 TransportParameters::decode(&mut dec_tp).map_err(|_| Error::InvalidResumptionToken)?;
756
757 let init_token = dec.decode_vvec().ok_or(Error::InvalidResumptionToken)?;
758 qtrace!("[{self}] Initial token {}", hex(init_token));
759
760 let tok = dec.decode_remainder();
761 qtrace!("[{self}] TLS token {}", hex(tok));
762
763 match self.crypto.tls_mut() {
764 Agent::Client(ref mut c) => {
765 let res = c.enable_resumption(tok);
766 if let Err(e) = res {
767 self.absorb_error::<Error>(now, Err(Error::from(e)));
768 return Ok(());
769 }
770 }
771 Agent::Server(_) => return Err(Error::WrongRole),
772 }
773
774 self.version = version;
775 self.conn_params.get_versions_mut().set_initial(version);
776 self.tps.borrow_mut().set_version(version);
777 self.tps.borrow_mut().set_remote_0rtt(Some(tp));
778 if !init_token.is_empty() {
779 self.address_validation = AddressValidationInfo::NewToken(init_token.to_vec());
780 }
781 self.paths
782 .primary()
783 .ok_or(Error::InternalError)?
784 .borrow_mut()
785 .rtt_mut()
786 .set_initial(rtt);
787 self.set_initial_limits();
788 // Start up TLS, which has the effect of setting up all the necessary
789 // state for 0-RTT. This only stages the CRYPTO frames.
790 let res = self.client_start(now);
791 self.absorb_error(now, res);
792 Ok(())
793 }
794
795 pub(crate) fn set_validation(&mut self, validation: &Rc<RefCell<AddressValidation>>) {
796 qtrace!("[{self}] Enabling NEW_TOKEN");
797 assert_eq!(self.role, Role::Server);
798 self.address_validation = AddressValidationInfo::Server(Rc::downgrade(validation));
799 }
800
801 /// Send a TLS session ticket AND a `NEW_TOKEN` frame (if possible).
802 /// # Errors
803 /// When the operation fails, which is usually due to bad inputs or bad connection state.
804 pub fn send_ticket(&mut self, now: Instant, extra: &[u8]) -> Res<()> {
805 if self.role == Role::Client {
806 return Err(Error::WrongRole);
807 }
808
809 let tps = &self.tps;
810 if let Agent::Server(ref mut s) = self.crypto.tls_mut() {
811 let mut enc = Encoder::default();
812 enc.encode_vvec_with(|enc_inner| {
813 tps.borrow().local().encode(enc_inner);
814 });
815 enc.encode(extra);
816 let records = s.send_ticket(now, enc.as_ref())?;
817 qdebug!("[{self}] send session ticket {}", hex(&enc));
818 self.crypto.buffer_records(records)?;
819 } else {
820 unreachable!();
821 }
822
823 // If we are able, also send a NEW_TOKEN frame.
824 // This should be recording all remote addresses that are valid,
825 // but there are just 0 or 1 in the current implementation.
826 if let Some(path) = self.paths.primary() {
827 if let Some(token) = self
828 .address_validation
829 .generate_new_token(path.borrow().remote_address(), now)
830 {
831 self.new_token.send_new_token(token);
832 }
833 Ok(())
834 } else {
835 Err(Error::NotConnected)
836 }
837 }
838
839 #[must_use]
840 pub fn tls_info(&self) -> Option<&SecretAgentInfo> {
841 self.crypto.tls().info()
842 }
843
844 /// # Errors
845 /// When there is no information to obtain.
846 pub fn tls_preinfo(&self) -> Res<SecretAgentPreInfo> {
847 Ok(self.crypto.tls().preinfo()?)
848 }
849
850 /// Get the peer's certificate chain and other info.
851 #[must_use]
852 pub fn peer_certificate(&self) -> Option<CertificateInfo> {
853 self.crypto.tls().peer_certificate()
854 }
855
856 /// Call by application when the peer cert has been verified.
857 ///
858 /// This panics if there is no active peer. It's OK to call this
859 /// when authentication isn't needed, that will likely only cause
860 /// the connection to fail. However, if no packets have been
861 /// exchanged, it's not OK.
862 pub fn authenticated(&mut self, status: AuthenticationStatus, now: Instant) {
863 qdebug!("[{self}] Authenticated {status:?}");
864 self.crypto.tls_mut().authenticated(status);
865 let res = self.handshake(now, self.version, PacketNumberSpace::Handshake, None);
866 self.absorb_error(now, res);
867 self.process_saved(now);
868 }
869
870 /// Get the role of the connection.
871 #[must_use]
872 pub const fn role(&self) -> Role {
873 self.role
874 }
875
876 /// Get the state of the connection.
877 #[must_use]
878 pub const fn state(&self) -> &State {
879 &self.state
880 }
881
882 /// The QUIC version in use.
883 #[must_use]
884 pub const fn version(&self) -> Version {
885 self.version
886 }
887
888 /// Get the 0-RTT state of the connection.
889 #[must_use]
890 pub const fn zero_rtt_state(&self) -> ZeroRttState {
891 self.zero_rtt_state
892 }
893
894 /// Get a snapshot of collected statistics.
895 #[must_use]
896 pub fn stats(&self) -> Stats {
897 let mut v = self.stats.borrow().clone();
898 if let Some(p) = self.paths.primary() {
899 let p = p.borrow();
900 v.rtt = p.rtt().estimate();
901 v.rttvar = p.rtt().rttvar();
902 }
903 v
904 }
905
906 // This function wraps a call to another function and sets the connection state
907 // properly if that call fails.
908 fn capture_error<T>(
909 &mut self,
910 path: Option<PathRef>,
911 now: Instant,
912 frame_type: FrameType,
913 res: Res<T>,
914 ) -> Res<T> {
915 if let Err(v) = &res {
916 #[cfg(debug_assertions)]
917 let msg = format!("{v:?}");
918 #[cfg(not(debug_assertions))]
919 let msg = "";
920 let error = CloseReason::Transport(v.clone());
921 match &self.state {
922 State::Closing { error: err, .. }
923 | State::Draining { error: err, .. }
924 | State::Closed(err) => {
925 qwarn!("[{self}] Closing again after error {err:?}");
926 }
927 State::Init => {
928 // We have not even sent anything just close the connection without sending any
929 // error. This may happen when client_start fails.
930 self.set_state(State::Closed(error), now);
931 }
932 State::WaitInitial | State::WaitVersion => {
933 // We don't have any state yet, so don't bother with
934 // the closing state, just send one CONNECTION_CLOSE.
935 if let Some(path) = path.or_else(|| self.paths.primary()) {
936 self.state_signaling
937 .close(path, error.clone(), frame_type, msg);
938 }
939 self.set_state(State::Closed(error), now);
940 }
941 _ => {
942 if let Some(path) = path.or_else(|| self.paths.primary()) {
943 self.state_signaling
944 .close(path, error.clone(), frame_type, msg);
945 if matches!(v, Error::KeysExhausted) {
946 self.set_state(State::Closed(error), now);
947 } else {
948 self.set_state(
949 State::Closing {
950 error,
951 timeout: self.get_closing_period_time(now),
952 },
953 now,
954 );
955 }
956 } else {
957 self.set_state(State::Closed(error), now);
958 }
959 }
960 }
961 }
962 res
963 }
964
965 /// For use with `process_input()`. Errors there can be ignored, but this
966 /// needs to ensure that the state is updated.
967 fn absorb_error<T>(&mut self, now: Instant, res: Res<T>) -> Option<T> {
968 self.capture_error(None, now, FrameType::Padding, res).ok()
969 }
970
971 fn process_timer(&mut self, now: Instant) {
972 match &self.state {
973 // Only the client runs timers while waiting for Initial packets.
974 State::WaitInitial => debug_assert_eq!(self.role, Role::Client),
975 // If Closing or Draining, check if it is time to move to Closed.
976 State::Closing { error, timeout } | State::Draining { error, timeout } => {
977 if *timeout <= now {
978 let st = State::Closed(error.clone());
979 self.set_state(st, now);
980 qinfo!("Closing timer expired");
981 return;
982 }
983 }
984 State::Closed(_) => {
985 qdebug!("Timer fired while closed");
986 return;
987 }
988 _ => (),
989 }
990
991 let pto = self.pto();
992 if self.idle_timeout.expired(now, pto) {
993 qinfo!("[{self}] idle timeout expired");
994 self.set_state(
995 State::Closed(CloseReason::Transport(Error::IdleTimeout)),
996 now,
997 );
998 return;
999 }
1000
1001 if self.state.closing() {
1002 qtrace!("[{self}] Closing, not processing other timers");
1003 return;
1004 }
1005
1006 self.streams.cleanup_closed_streams();
1007
1008 let res = self.crypto.states_mut().check_key_update(now);
1009 self.absorb_error(now, res);
1010
1011 if let Some(path) = self.paths.primary() {
1012 let lost = self.loss_recovery.timeout(&path, now);
1013 self.handle_lost_packets(&lost);
1014 qlog::packets_lost(&self.qlog, &lost, now);
1015 }
1016
1017 if self.release_resumption_token_timer.is_some() {
1018 self.create_resumption_token(now);
1019 }
1020
1021 if !self
1022 .paths
1023 .process_timeout(now, pto, &mut self.stats.borrow_mut())
1024 {
1025 qinfo!("[{self}] last available path failed");
1026 self.absorb_error::<Error>(now, Err(Error::NoAvailablePath));
1027 }
1028 }
1029
1030 /// Whether the given [`ConnectionIdRef`] is a valid local [`ConnectionId`].
1031 #[must_use]
1032 pub fn is_valid_local_cid(&self, cid: ConnectionIdRef) -> bool {
1033 self.cid_manager.is_valid(cid)
1034 }
1035
1036 /// Process new input datagrams on the connection.
1037 pub fn process_input(&mut self, d: Datagram<impl AsRef<[u8]> + AsMut<[u8]>>, now: Instant) {
1038 self.process_multiple_input(iter::once(d), now);
1039 }
1040
1041 /// Process new input datagrams on the connection.
1042 pub fn process_multiple_input(
1043 &mut self,
1044 dgrams: impl IntoIterator<Item = Datagram<impl AsRef<[u8]> + AsMut<[u8]>>>,
1045 now: Instant,
1046 ) {
1047 let mut dgrams = dgrams.into_iter().peekable();
1048 if dgrams.peek().is_none() {
1049 return;
1050 }
1051
1052 for d in dgrams {
1053 self.input(d, now, now);
1054 }
1055 self.process_saved(now);
1056 self.streams.cleanup_closed_streams();
1057 }
1058
1059 /// Get the time that we next need to be called back, relative to `now`.
1060 fn next_delay(&mut self, now: Instant, paced: bool) -> Duration {
1061 qtrace!("[{self}] Get callback delay {now:?}");
1062
1063 // Only one timer matters when closing...
1064 if let State::Closing { timeout, .. } | State::Draining { timeout, .. } = self.state {
1065 self.hrtime.update(Self::LOOSE_TIMER_RESOLUTION);
1066 return timeout.duration_since(now);
1067 }
1068
1069 let mut delays = SmallVec::<[_; 7]>::new();
1070 if let Some(ack_time) = self.acks.ack_time(now) {
1071 qtrace!("[{self}] Delayed ACK timer {ack_time:?}");
1072 delays.push(ack_time);
1073 }
1074
1075 if let Some(p) = self.paths.primary() {
1076 let path = p.borrow();
1077 let rtt = path.rtt();
1078 let pto = rtt.pto(self.confirmed());
1079
1080 let idle_time = self.idle_timeout.expiry(now, pto);
1081 qtrace!("[{self}] Idle timer {idle_time:?}");
1082 delays.push(idle_time);
1083
1084 if self.streams.need_keep_alive() {
1085 if let Some(keep_alive_time) = self.idle_timeout.next_keep_alive(now, pto) {
1086 qtrace!("[{self}] Keep alive timer {keep_alive_time:?}");
1087 delays.push(keep_alive_time);
1088 }
1089 }
1090
1091 if let Some(lr_time) = self.loss_recovery.next_timeout(&path) {
1092 qtrace!("[{self}] Loss recovery timer {lr_time:?}");
1093 delays.push(lr_time);
1094 }
1095
1096 if paced {
1097 if let Some(pace_time) = path.sender().next_paced(rtt.estimate()) {
1098 qtrace!("[{self}] Pacing timer {pace_time:?}");
1099 delays.push(pace_time);
1100 }
1101 }
1102
1103 if let Some(path_time) = self.paths.next_timeout(pto) {
1104 qtrace!("[{self}] Path probe timer {path_time:?}");
1105 delays.push(path_time);
1106 }
1107 }
1108
1109 if let Some(key_update_time) = self.crypto.states().update_time() {
1110 qtrace!("[{self}] Key update timer {key_update_time:?}");
1111 delays.push(key_update_time);
1112 }
1113
1114 // `release_resumption_token_timer` is not considered here, because
1115 // it is not important enough to force the application to set a
1116 // timeout for it It is expected that other activities will
1117 // drive it.
1118
1119 let earliest = delays.into_iter().min().expect("at least one delay");
1120 // TODO(agrover, mt) - need to analyze and fix #47
1121 // rather than just clamping to zero here.
1122 debug_assert!(earliest > now);
1123 let delay = earliest.saturating_duration_since(now);
1124 qdebug!("[{self}] delay duration {delay:?}");
1125 self.hrtime.update(delay / 4);
1126 delay
1127 }
1128
1129 /// Get output packets, as a result of receiving packets, or actions taken
1130 /// by the application.
1131 /// Returns datagrams to send, and how long to wait before calling again
1132 /// even if no incoming packets.
1133 #[must_use = "Output of the process_output function must be handled"]
1134 pub fn process_output(&mut self, now: Instant) -> Output {
1135 qtrace!("[{self}] process_output {:?} {now:?}", self.state);
1136
1137 match (&self.state, self.role) {
1138 (State::Init, Role::Client) => {
1139 let res = self.client_start(now);
1140 self.absorb_error(now, res);
1141 }
1142 (State::Init | State::WaitInitial, Role::Server) => {
1143 return Output::None;
1144 }
1145 _ => {
1146 self.process_timer(now);
1147 }
1148 }
1149
1150 match self.output(now) {
1151 SendOption::Yes(dgram) => Output::Datagram(dgram),
1152 SendOption::No(paced) => match self.state {
1153 State::Init | State::Closed(_) => Output::None,
1154 State::Closing { timeout, .. } | State::Draining { timeout, .. } => {
1155 Output::Callback(timeout.duration_since(now))
1156 }
1157 _ => Output::Callback(self.next_delay(now, paced)),
1158 },
1159 }
1160 }
1161
1162 /// A test-only output function that uses the provided writer to
1163 /// pack something extra into the output.
1164 #[cfg(test)]
1165 pub fn test_write_frames<W>(&mut self, writer: W, now: Instant) -> Output
1166 where
1167 W: test_internal::FrameWriter + 'static,
1168 {
1169 self.test_frame_writer = Some(Box::new(writer));
1170 let res = self.process_output(now);
1171 self.test_frame_writer = None;
1172 res
1173 }
1174
1175 /// Process input and generate output.
1176 #[must_use = "Output of the process function must be handled"]
1177 pub fn process(
1178 &mut self,
1179 dgram: Option<Datagram<impl AsRef<[u8]> + AsMut<[u8]>>>,
1180 now: Instant,
1181 ) -> Output {
1182 if let Some(d) = dgram {
1183 self.input(d, now, now);
1184 self.process_saved(now);
1185 }
1186 let output = self.process_output(now);
1187 #[cfg(all(feature = "build-fuzzing-corpus", test))]
1188 if self.test_frame_writer.is_none() {
1189 if let Some(d) = output.clone().dgram() {
1190 neqo_common::write_item_to_fuzzing_corpus("packet", &d);
1191 }
1192 }
1193 output
1194 }
1195
1196 fn handle_retry(&mut self, packet: &PublicPacket, now: Instant) -> Res<()> {
1197 qinfo!("[{self}] received Retry");
1198 if matches!(self.address_validation, AddressValidationInfo::Retry { .. }) {
1199 self.stats.borrow_mut().pkt_dropped("Extra Retry");
1200 return Ok(());
1201 }
1202 if packet.token().is_empty() {
1203 self.stats.borrow_mut().pkt_dropped("Retry without a token");
1204 return Ok(());
1205 }
1206 if !packet.is_valid_retry(
1207 self.original_destination_cid
1208 .as_ref()
1209 .ok_or(Error::InvalidRetry)?,
1210 ) {
1211 self.stats
1212 .borrow_mut()
1213 .pkt_dropped("Retry with bad integrity tag");
1214 return Ok(());
1215 }
1216 // At this point, we should only have the connection ID that we generated.
1217 // Update to the one that the server prefers.
1218 let Some(path) = self.paths.primary() else {
1219 self.stats
1220 .borrow_mut()
1221 .pkt_dropped("Retry without an existing path");
1222 return Ok(());
1223 };
1224
1225 path.borrow_mut().set_remote_cid(packet.scid());
1226
1227 let retry_scid = ConnectionId::from(packet.scid());
1228 qinfo!(
1229 "[{self}] Valid Retry received, token={} scid={retry_scid}",
1230 hex(packet.token())
1231 );
1232
1233 let lost_packets = self.loss_recovery.retry(&path, now);
1234 self.handle_lost_packets(&lost_packets);
1235
1236 self.crypto.states_mut().init(
1237 self.conn_params.get_versions().compatible(),
1238 self.role,
1239 &retry_scid,
1240 )?;
1241 self.address_validation = AddressValidationInfo::Retry {
1242 token: packet.token().to_vec(),
1243 retry_source_cid: retry_scid,
1244 };
1245 Ok(())
1246 }
1247
1248 fn discard_keys(&mut self, space: PacketNumberSpace, now: Instant) {
1249 if self.crypto.discard(space) {
1250 qdebug!("[{self}] Drop packet number space {space}");
1251 if let Some(path) = self.paths.primary() {
1252 self.loss_recovery.discard(&path, space, now);
1253 }
1254 self.acks.drop_space(space);
1255 }
1256 }
1257
1258 fn is_stateless_reset(&self, path: &PathRef, d: &[u8]) -> bool {
1259 // If the datagram is too small, don't try.
1260 // If the connection is connected, then the reset token will be invalid.
1261 if d.len() < 16 || !self.state.connected() {
1262 return false;
1263 }
1264 <&[u8; 16]>::try_from(&d[d.len() - 16..])
1265 .is_ok_and(|token| path.borrow().is_stateless_reset(token))
1266 }
1267
1268 fn check_stateless_reset(
1269 &mut self,
1270 path: &PathRef,
1271 d: &[u8],
1272 first: bool,
1273 now: Instant,
1274 ) -> Res<()> {
1275 if first && self.is_stateless_reset(path, d) {
1276 // Failing to process a packet in a datagram might
1277 // indicate that there is a stateless reset present.
1278 qdebug!("[{self}] Stateless reset: {}", hex(&d[d.len() - 16..]));
1279 self.state_signaling.reset();
1280 self.set_state(
1281 State::Draining {
1282 error: CloseReason::Transport(Error::StatelessReset),
1283 timeout: self.get_closing_period_time(now),
1284 },
1285 now,
1286 );
1287 Err(Error::StatelessReset)
1288 } else {
1289 Ok(())
1290 }
1291 }
1292
1293 /// Process any saved datagrams that might be available for processing.
1294 fn process_saved(&mut self, now: Instant) {
1295 while let Some(epoch) = self.saved_datagrams.available() {
1296 qdebug!("[{self}] process saved for epoch {epoch:?}");
1297 debug_assert!(self
1298 .crypto
1299 .states_mut()
1300 .rx_hp(self.version, epoch)
1301 .is_some());
1302 for saved in self.saved_datagrams.take_saved() {
1303 qtrace!("[{self}] input saved @{:?}: {:?}", saved.t, saved.d);
1304 self.input(saved.d, saved.t, now);
1305 }
1306 }
1307 }
1308
1309 /// In case a datagram arrives that we can only partially process, save any
1310 /// part that we don't have keys for.
1311 #[expect(
1312 clippy::needless_pass_by_value,
1313 reason = "To consume an owned datagram below."
1314 )]
1315 fn save_datagram(
1316 &mut self,
1317 epoch: Epoch,
1318 d: Datagram<impl AsRef<[u8]>>,
1319 remaining: usize,
1320 now: Instant,
1321 ) {
1322 let d = Datagram::new(
1323 d.source(),
1324 d.destination(),
1325 d.tos(),
1326 d[d.len() - remaining..].to_vec(),
1327 );
1328 self.saved_datagrams.save(epoch, d, now);
1329 self.stats.borrow_mut().saved_datagrams += 1;
1330 // We already counted the datagram as received in [`input_path`]. We
1331 // will do so again when we (re-)process it, so reduce the count now.
1332 self.stats.borrow_mut().packets_rx -= 1;
1333 }
1334
1335 /// Perform version negotiation.
1336 fn version_negotiation(&mut self, supported: &[WireVersion], now: Instant) -> Res<()> {
1337 debug_assert_eq!(self.role, Role::Client);
1338
1339 if let Some(version) = self.conn_params.get_versions().preferred(supported) {
1340 assert_ne!(self.version, version);
1341
1342 qinfo!("[{self}] Version negotiation: trying {version:?}");
1343 let path = self.paths.primary().ok_or(Error::NoAvailablePath)?;
1344 let local_addr = path.borrow().local_address();
1345 let remote_addr = path.borrow().remote_address();
1346 let conn_params = self
1347 .conn_params
1348 .clone()
1349 .versions(version, self.conn_params.get_versions().all().to_vec());
1350 let mut c = Self::new_client(
1351 self.crypto.server_name().ok_or(Error::VersionNegotiation)?,
1352 self.crypto.protocols(),
1353 self.cid_manager.generator(),
1354 local_addr,
1355 remote_addr,
1356 conn_params,
1357 now,
1358 )?;
1359 c.conn_params
1360 .get_versions_mut()
1361 .set_initial(self.conn_params.get_versions().initial());
1362 mem::swap(self, &mut c);
1363 qlog::client_version_information_negotiated(
1364 &self.qlog,
1365 self.conn_params.get_versions().all(),
1366 supported,
1367 version,
1368 now,
1369 );
1370 Ok(())
1371 } else {
1372 qinfo!("[{self}] Version negotiation: failed with {supported:?}");
1373 // This error goes straight to closed.
1374 self.set_state(
1375 State::Closed(CloseReason::Transport(Error::VersionNegotiation)),
1376 now,
1377 );
1378 Err(Error::VersionNegotiation)
1379 }
1380 }
1381
1382 /// Perform any processing that we might have to do on packets prior to
1383 /// attempting to remove protection.
1384 #[expect(clippy::too_many_lines, reason = "Yeah, it's a work in progress.")]
1385 fn preprocess_packet(
1386 &mut self,
1387 packet: &PublicPacket,
1388 path: &PathRef,
1389 dcid: Option<&ConnectionId>,
1390 now: Instant,
1391 ) -> Res<PreprocessResult> {
1392 if dcid.is_some_and(|d| d != &packet.dcid()) {
1393 self.stats
1394 .borrow_mut()
1395 .pkt_dropped("Coalesced packet has different DCID");
1396 return Ok(PreprocessResult::Next);
1397 }
1398
1399 if (packet.packet_type() == PacketType::Initial
1400 || packet.packet_type() == PacketType::Handshake)
1401 && self.role == Role::Client
1402 && !path.borrow().is_primary()
1403 {
1404 // If we have received a packet from a different address than we have sent to
1405 // we should ignore the packet. In such a case a path will be a newly created
1406 // temporary path, not the primary path.
1407 return Ok(PreprocessResult::Next);
1408 }
1409
1410 match (packet.packet_type(), &self.state, &self.role) {
1411 (PacketType::Initial, State::Init, Role::Server) => {
1412 let version = packet.version().ok_or(Error::ProtocolViolation)?;
1413 if !packet.is_valid_initial()
1414 || !self.conn_params.get_versions().all().contains(&version)
1415 {
1416 self.stats.borrow_mut().pkt_dropped("Invalid Initial");
1417 return Ok(PreprocessResult::Next);
1418 }
1419 qinfo!(
1420 "[{self}] Received valid Initial packet with scid {:?} dcid {:?}",
1421 packet.scid(),
1422 packet.dcid()
1423 );
1424 // Record the client's selected CID so that it can be accepted until
1425 // the client starts using a real connection ID.
1426 let dcid = ConnectionId::from(packet.dcid());
1427 self.crypto.states_mut().init_server(version, &dcid)?;
1428 self.original_destination_cid = Some(dcid);
1429 self.set_state(State::WaitInitial, now);
1430
1431 // We need to make sure that we set this transport parameter.
1432 // This has to happen prior to processing the packet so that
1433 // the TLS handshake has all it needs.
1434 if !self.retry_sent() {
1435 self.tps
1436 .borrow_mut()
1437 .local_mut()
1438 .set_bytes(OriginalDestinationConnectionId, packet.dcid().to_vec());
1439 }
1440 }
1441 (PacketType::VersionNegotiation, State::WaitInitial, Role::Client) => {
1442 if let Ok(versions) = packet.supported_versions() {
1443 if versions.is_empty()
1444 || versions.contains(&self.version().wire_version())
1445 || versions.contains(&0)
1446 || &packet.scid() != self.odcid().ok_or(Error::InternalError)?
1447 || matches!(self.address_validation, AddressValidationInfo::Retry { .. })
1448 {
1449 // Ignore VersionNegotiation packets that contain the current version.
1450 // Or don't have the right connection ID.
1451 // Or are received after a Retry.
1452 self.stats.borrow_mut().pkt_dropped("Invalid VN");
1453 } else {
1454 self.version_negotiation(&versions, now)?;
1455 }
1456 } else {
1457 self.stats.borrow_mut().pkt_dropped("VN with no versions");
1458 }
1459 return Ok(PreprocessResult::End);
1460 }
1461 (PacketType::Retry, State::WaitInitial, Role::Client) => {
1462 self.handle_retry(packet, now)?;
1463 return Ok(PreprocessResult::Next);
1464 }
1465 (PacketType::Handshake | PacketType::Short, State::WaitInitial, Role::Client) => {
1466 // This packet can't be processed now, but it could be a sign
1467 // that Initial packets were lost.
1468 // Resend Initial CRYPTO frames immediately a few times just
1469 // in case. As we don't have an RTT estimate yet, this helps
1470 // when there is a short RTT and losses. Also mark all 0-RTT
1471 // data as lost.
1472 if dcid.is_none()
1473 && self.cid_manager.is_valid(packet.dcid())
1474 && self.stats.borrow().saved_datagrams <= EXTRA_INITIALS
1475 {
1476 self.crypto.resend_unacked(PacketNumberSpace::Initial);
1477 self.resend_0rtt(now);
1478 }
1479 }
1480 (PacketType::VersionNegotiation | PacketType::Retry | PacketType::OtherVersion, ..) => {
1481 self.stats
1482 .borrow_mut()
1483 .pkt_dropped(format!("{:?}", packet.packet_type()));
1484 return Ok(PreprocessResult::Next);
1485 }
1486 _ => {}
1487 }
1488
1489 let res = match self.state {
1490 State::Init => {
1491 self.stats
1492 .borrow_mut()
1493 .pkt_dropped("Received while in Init state");
1494 PreprocessResult::Next
1495 }
1496 State::WaitInitial => PreprocessResult::Continue,
1497 State::WaitVersion | State::Handshaking | State::Connected | State::Confirmed => {
1498 if self.cid_manager.is_valid(packet.dcid()) {
1499 if self.role == Role::Server && packet.packet_type() == PacketType::Handshake {
1500 // Server has received a Handshake packet -> discard Initial keys and states
1501 self.discard_keys(PacketNumberSpace::Initial, now);
1502 }
1503 PreprocessResult::Continue
1504 } else {
1505 self.stats
1506 .borrow_mut()
1507 .pkt_dropped(format!("Invalid DCID {:?}", packet.dcid()));
1508 PreprocessResult::Next
1509 }
1510 }
1511 State::Closing { .. } => {
1512 // Don't bother processing the packet. Instead ask to get a
1513 // new close frame.
1514 self.state_signaling.send_close();
1515 PreprocessResult::Next
1516 }
1517 State::Draining { .. } | State::Closed(..) => {
1518 // Do nothing.
1519 self.stats
1520 .borrow_mut()
1521 .pkt_dropped(format!("State {:?}", self.state));
1522 PreprocessResult::Next
1523 }
1524 };
1525 Ok(res)
1526 }
1527
1528 /// After a Initial, Handshake, `ZeroRtt`, or Short packet is successfully processed.
1529 #[expect(clippy::too_many_arguments, reason = "Yes, but they're needed.")]
1530 fn postprocess_packet(
1531 &mut self,
1532 path: &PathRef,
1533 tos: IpTos,
1534 remote: SocketAddr,
1535 packet: &PublicPacket,
1536 packet_number: PacketNumber,
1537 migrate: bool,
1538 now: Instant,
1539 ) {
1540 let ecn_mark = IpTosEcn::from(tos);
1541 let mut stats = self.stats.borrow_mut();
1542 stats.ecn_rx[packet.packet_type()] += ecn_mark;
1543 if let Some(last_ecn_mark) = stats.ecn_last_mark.filter(|&last_ecn_mark| {
1544 last_ecn_mark != ecn_mark && stats.ecn_rx_transition[last_ecn_mark][ecn_mark].is_none()
1545 }) {
1546 stats.ecn_rx_transition[last_ecn_mark][ecn_mark] =
1547 Some((packet.packet_type(), packet_number));
1548 }
1549
1550 stats.ecn_last_mark = Some(ecn_mark);
1551 drop(stats);
1552 let space = PacketNumberSpace::from(packet.packet_type());
1553 if let Some(space) = self.acks.get_mut(space) {
1554 *space.ecn_marks() += ecn_mark;
1555 } else {
1556 qtrace!("Not tracking ECN for dropped packet number space");
1557 }
1558
1559 if self.state == State::WaitInitial {
1560 self.start_handshake(path, packet, now);
1561 }
1562
1563 if matches!(self.state, State::WaitInitial | State::WaitVersion) {
1564 let new_state = if self.has_version() {
1565 State::Handshaking
1566 } else {
1567 State::WaitVersion
1568 };
1569 self.set_state(new_state, now);
1570 if self.role == Role::Server && self.state == State::Handshaking {
1571 self.zero_rtt_state =
1572 if self.crypto.enable_0rtt(self.version, self.role) == Ok(true) {
1573 qdebug!("[{self}] Accepted 0-RTT");
1574 ZeroRttState::AcceptedServer
1575 } else {
1576 ZeroRttState::Rejected
1577 };
1578 }
1579 }
1580
1581 if self.state.connected() {
1582 self.handle_migration(path, remote, migrate, now);
1583 } else if self.role != Role::Client
1584 && (packet.packet_type() == PacketType::Handshake
1585 || (packet.dcid().len() >= 8 && packet.dcid() == self.local_initial_source_cid))
1586 {
1587 // We only allow one path during setup, so apply handshake
1588 // path validation to this path.
1589 path.borrow_mut().set_valid(now);
1590 }
1591 }
1592
1593 /// Take a datagram as input. This reports an error if the packet was bad.
1594 /// This takes two times: when the datagram was received, and the current time.
1595 fn input(
1596 &mut self,
1597 d: Datagram<impl AsRef<[u8]> + AsMut<[u8]>>,
1598 received: Instant,
1599 now: Instant,
1600 ) {
1601 // First determine the path.
1602 let path = self.paths.find_path(
1603 d.destination(),
1604 d.source(),
1605 &self.conn_params,
1606 now,
1607 &mut self.stats.borrow_mut(),
1608 );
1609 path.borrow_mut().add_received(d.len());
1610 let res = self.input_path(&path, d, received);
1611 _ = self.capture_error(Some(path), now, FrameType::Padding, res);
1612 }
1613
1614 fn input_path(
1615 &mut self,
1616 path: &PathRef,
1617 mut d: Datagram<impl AsRef<[u8]> + AsMut<[u8]>>,
1618 now: Instant,
1619 ) -> Res<()> {
1620 qtrace!("[{self}] {} input {}", path.borrow(), hex(&d));
1621 let tos = d.tos();
1622 let remote = d.source();
1623 let mut slc = d.as_mut();
1624 let mut dcid = None;
1625 let pto = path.borrow().rtt().pto(self.confirmed());
1626
1627 // Handle each packet in the datagram.
1628 while !slc.is_empty() {
1629 self.stats.borrow_mut().packets_rx += 1;
1630 let slc_len = slc.len();
1631 let (mut packet, remainder) =
1632 match PublicPacket::decode(slc, self.cid_manager.decoder().as_ref()) {
1633 Ok((packet, remainder)) => (packet, remainder),
1634 Err(e) => {
1635 qinfo!("[{self}] Garbage packet: {e}");
1636 self.stats.borrow_mut().pkt_dropped("Garbage packet");
1637 break;
1638 }
1639 };
1640 self.stats.borrow_mut().dscp_rx[tos.into()] += 1;
1641 match self.preprocess_packet(&packet, path, dcid.as_ref(), now)? {
1642 PreprocessResult::Continue => (),
1643 PreprocessResult::Next => break,
1644 PreprocessResult::End => return Ok(()),
1645 }
1646
1647 qtrace!("[{self}] Received unverified packet {packet:?}");
1648
1649 let packet_len = packet.len();
1650 match packet.decrypt(self.crypto.states_mut(), now + pto) {
1651 Ok(payload) => {
1652 // OK, we have a valid packet.
1653 let pn = payload.pn();
1654 self.idle_timeout.on_packet_received(now);
1655 self.log_packet(
1656 packet::MetaData::new_in(path, tos, packet_len, &payload),
1657 now,
1658 );
1659
1660 #[cfg(feature = "build-fuzzing-corpus")]
1661 if payload.packet_type() == PacketType::Initial {
1662 let target = if self.role == Role::Client {
1663 "server_initial"
1664 } else {
1665 "client_initial"
1666 };
1667 neqo_common::write_item_to_fuzzing_corpus(target, &payload[..]);
1668 }
1669
1670 let space = PacketNumberSpace::from(payload.packet_type());
1671 if let Some(space) = self.acks.get_mut(space) {
1672 if space.is_duplicate(pn) {
1673 qdebug!("Duplicate packet {space}-{}", pn);
1674 self.stats.borrow_mut().dups_rx += 1;
1675 } else {
1676 match self.process_packet(path, &payload, now) {
1677 Ok(migrate) => {
1678 self.postprocess_packet(
1679 path, tos, remote, &packet, pn, migrate, now,
1680 );
1681 }
1682 Err(e) => {
1683 self.ensure_error_path(path, &packet, now);
1684 return Err(e);
1685 }
1686 }
1687 }
1688 } else {
1689 qdebug!(
1690 "[{self}] Received packet {space} for untracked space {}",
1691 payload.pn()
1692 );
1693 return Err(Error::ProtocolViolation);
1694 }
1695 }
1696 Err(e) => {
1697 match e {
1698 Error::KeysPending(epoch) => {
1699 // This packet can't be decrypted because we don't have the keys yet.
1700 // Don't check this packet for a stateless reset, just return.
1701 let remaining = slc_len;
1702 self.save_datagram(epoch, d, remaining, now);
1703 return Ok(());
1704 }
1705 Error::KeysExhausted => {
1706 // Exhausting read keys is fatal.
1707 return Err(e);
1708 }
1709 Error::KeysDiscarded(epoch) => {
1710 // This was a valid-appearing Initial packet: maybe probe with
1711 // a Handshake packet to keep the handshake moving.
1712 self.received_untracked |=
1713 self.role == Role::Client && epoch == Epoch::Initial;
1714 }
1715 _ => (),
1716 }
1717 // Decryption failure, or not having keys is not fatal.
1718 // If the state isn't available, or we can't decrypt the packet, drop
1719 // the rest of the datagram on the floor, but don't generate an error.
1720 self.check_stateless_reset(path, packet.data(), dcid.is_none(), now)?;
1721 self.stats.borrow_mut().pkt_dropped("Decryption failure");
1722 qlog::packet_dropped(&self.qlog, &packet, now);
1723 }
1724 }
1725 slc = remainder;
1726 dcid = Some(ConnectionId::from(packet.dcid()));
1727 }
1728 self.check_stateless_reset(path, &d, dcid.is_none(), now)?;
1729 Ok(())
1730 }
1731
1732 /// Process a packet. Returns true if the packet might initiate migration.
1733 fn process_packet(
1734 &mut self,
1735 path: &PathRef,
1736 packet: &DecryptedPacket,
1737 now: Instant,
1738 ) -> Res<bool> {
1739 (!packet.is_empty())
1740 .then_some(())
1741 .ok_or(Error::ProtocolViolation)?;
1742
1743 // TODO([email protected]): Have the server blow away the initial
1744 // crypto state if this fails? Otherwise, we will get a panic
1745 // on the assert for doesn't exist.
1746 // OK, we have a valid packet.
1747
1748 // Get the next packet number we'll send, for ACK verification.
1749 // TODO: Once PR #2118 lands, this can move to `input_frame`. For now, it needs to be here,
1750 // because we can drop packet number spaces as we parse through the packet, and if an ACK
1751 // frame follows a CRYPTO frame that makes us drop a space, we need to know this
1752 // packet number to verify the ACK against.
1753 let next_pn = self
1754 .crypto
1755 .states()
1756 .select_tx(self.version, PacketNumberSpace::from(packet.packet_type()))
1757 .map_or(0, |(_, tx)| tx.next_pn());
1758
1759 let mut ack_eliciting = false;
1760 let mut probing = true;
1761 let mut d = Decoder::from(&packet[..]);
1762 while d.remaining() > 0 {
1763 #[cfg(feature = "build-fuzzing-corpus")]
1764 let pos = d.offset();
1765 let f = Frame::decode(&mut d)?;
1766 #[cfg(feature = "build-fuzzing-corpus")]
1767 neqo_common::write_item_to_fuzzing_corpus("frame", &packet[pos..d.offset()]);
1768 ack_eliciting |= f.ack_eliciting();
1769 probing &= f.path_probing();
1770 let t = f.get_type();
1771 if let Err(e) = self.input_frame(
1772 path,
1773 packet.version(),
1774 packet.packet_type(),
1775 f,
1776 next_pn,
1777 now,
1778 ) {
1779 self.capture_error(Some(Rc::clone(path)), now, t, Err(e))?;
1780 }
1781 }
1782
1783 let largest_received = if let Some(space) = self
1784 .acks
1785 .get_mut(PacketNumberSpace::from(packet.packet_type()))
1786 {
1787 space.set_received(now, packet.pn(), ack_eliciting)?
1788 } else {
1789 qdebug!(
1790 "[{self}] processed a {:?} packet without tracking it",
1791 packet.packet_type(),
1792 );
1793 // This was a valid packet that caused the same packet number to be
1794 // discarded. This happens when the client discards the Initial packet
1795 // number space after receiving the ServerHello. Remember this so
1796 // that we guarantee that we send a Handshake packet.
1797 self.received_untracked = true;
1798 // We don't migrate during the handshake, so return false.
1799 false
1800 };
1801
1802 Ok(largest_received && !probing)
1803 }
1804
1805 /// During connection setup, the first path needs to be setup.
1806 /// This uses the connection IDs that were provided during the handshake
1807 /// to setup that path.
1808 fn setup_handshake_path(&mut self, path: &PathRef, now: Instant) {
1809 self.paths.make_permanent(
1810 path,
1811 Some(self.local_initial_source_cid.clone()),
1812 // Ideally we know what the peer wants us to use for the remote CID.
1813 // But we will use our own guess if necessary.
1814 ConnectionIdEntry::initial_remote(
1815 self.remote_initial_source_cid
1816 .as_ref()
1817 .or(self.original_destination_cid.as_ref())
1818 .expect("have either remote_initial_source_cid or original_destination_cid")
1819 .clone(),
1820 ),
1821 now,
1822 );
1823 if self.role == Role::Client {
1824 path.borrow_mut().set_valid(now);
1825 }
1826 }
1827
1828 /// If the path isn't permanent, assign it a connection ID to make it so.
1829 fn ensure_permanent(&mut self, path: &PathRef, now: Instant) -> Res<()> {
1830 if self.paths.is_temporary(path) {
1831 // If there isn't a connection ID to use for this path, the packet
1832 // will be processed, but it won't be attributed to a path. That means
1833 // no path probes or PATH_RESPONSE. But it's not fatal.
1834 if let Some(cid) = self.cids.next() {
1835 self.paths.make_permanent(path, None, cid, now);
1836 Ok(())
1837 } else if let Some(primary) = self.paths.primary() {
1838 if primary.borrow().remote_cid().is_none_or(|id| id.is_empty()) {
1839 self.paths
1840 .make_permanent(path, None, ConnectionIdEntry::empty_remote(), now);
1841 Ok(())
1842 } else {
1843 qtrace!("[{self}] Unable to make path permanent: {}", path.borrow());
1844 Err(Error::InvalidMigration)
1845 }
1846 } else {
1847 qtrace!("[{self}] Unable to make path permanent: {}", path.borrow());
1848 Err(Error::InvalidMigration)
1849 }
1850 } else {
1851 Ok(())
1852 }
1853 }
1854
1855 /// After an error, a permanent path is needed to send the `CONNECTION_CLOSE`.
1856 /// This attempts to ensure that this exists. As the connection is now
1857 /// temporary, there is no reason to do anything special here.
1858 fn ensure_error_path(&mut self, path: &PathRef, packet: &PublicPacket, now: Instant) {
1859 path.borrow_mut().set_valid(now);
1860 if self.paths.is_temporary(path) {
1861 // First try to fill in handshake details.
1862 if packet.packet_type() == PacketType::Initial {
1863 self.remote_initial_source_cid = Some(ConnectionId::from(packet.scid()));
1864 self.setup_handshake_path(path, now);
1865 } else {
1866 // Otherwise try to get a usable connection ID.
1867 drop(self.ensure_permanent(path, now));
1868 }
1869 }
1870 }
1871
1872 fn start_handshake(&mut self, path: &PathRef, packet: &PublicPacket, now: Instant) {
1873 qtrace!("[{self}] starting handshake");
1874 debug_assert_eq!(packet.packet_type(), PacketType::Initial);
1875 self.remote_initial_source_cid = Some(ConnectionId::from(packet.scid()));
1876
1877 if self.role == Role::Server {
1878 let Some(original_destination_cid) = self.original_destination_cid.as_ref() else {
1879 qdebug!("[{self}] No original destination DCID");
1880 return;
1881 };
1882 self.cid_manager.add_odcid(original_destination_cid.clone());
1883 // Make a path on which to run the handshake.
1884 self.setup_handshake_path(path, now);
1885 } else {
1886 qdebug!("[{self}] Changing to use Server CID={}", packet.scid());
1887 debug_assert!(path.borrow().is_primary());
1888 path.borrow_mut().set_remote_cid(packet.scid());
1889 }
1890 }
1891
1892 fn has_version(&self) -> bool {
1893 if self.role == Role::Server {
1894 // The server knows the final version if it has remote transport parameters.
1895 self.tps.borrow().remote_handshake().is_some()
1896 } else {
1897 // The client knows the final version if it processed a CRYPTO frame.
1898 self.stats.borrow().frame_rx.crypto > 0
1899 }
1900 }
1901
1902 /// Migrate to the provided path.
1903 /// Either local or remote address (but not both) may be provided as `None` to have
1904 /// the address from the current primary path used.
1905 /// If `force` is true, then migration is immediate.
1906 /// Otherwise, migration occurs after the path is probed successfully.
1907 /// Either way, the path is probed and will be abandoned if the probe fails.
1908 ///
1909 /// # Errors
1910 ///
1911 /// Fails if this is not a client, not confirmed, the peer disabled connection migration, or
1912 /// there are not enough connection IDs available to use.
1913 pub fn migrate(
1914 &mut self,
1915 local: Option<SocketAddr>,
1916 remote: Option<SocketAddr>,
1917 force: bool,
1918 now: Instant,
1919 ) -> Res<()> {
1920 if self.role != Role::Client {
1921 return Err(Error::InvalidMigration);
1922 }
1923 if !matches!(self.state(), State::Confirmed) {
1924 return Err(Error::InvalidMigration);
1925 }
1926 if self.tps.borrow().remote().get_empty(DisableMigration) {
1927 return Err(Error::InvalidMigration);
1928 }
1929
1930 // Fill in the blanks, using the current primary path.
1931 if local.is_none() && remote.is_none() {
1932 // Pointless migration is pointless.
1933 return Err(Error::InvalidMigration);
1934 }
1935
1936 let path = self.paths.primary().ok_or(Error::InvalidMigration)?;
1937 let local = local.unwrap_or_else(|| path.borrow().local_address());
1938 let remote = remote.unwrap_or_else(|| path.borrow().remote_address());
1939
1940 if mem::discriminant(&local.ip()) != mem::discriminant(&remote.ip()) {
1941 // Can't mix address families.
1942 return Err(Error::InvalidMigration);
1943 }
1944 if local.port() == 0 || remote.ip().is_unspecified() || remote.port() == 0 {
1945 // All but the local address need to be specified.
1946 return Err(Error::InvalidMigration);
1947 }
1948 if (local.ip().is_loopback() ^ remote.ip().is_loopback()) && !local.ip().is_unspecified() {
1949 // Block attempts to migrate to a path with loopback on only one end, unless the local
1950 // address is unspecified.
1951 return Err(Error::InvalidMigration);
1952 }
1953
1954 let path = self.paths.find_path(
1955 local,
1956 remote,
1957 &self.conn_params,
1958 now,
1959 &mut self.stats.borrow_mut(),
1960 );
1961 self.ensure_permanent(&path, now)?;
1962 qinfo!(
1963 "[{self}] Migrate to {} probe {}",
1964 path.borrow(),
1965 if force { "now" } else { "after" }
1966 );
1967 if self
1968 .paths
1969 .migrate(&path, force, now, &mut self.stats.borrow_mut())
1970 {
1971 self.loss_recovery.migrate();
1972 }
1973 Ok(())
1974 }
1975
1976 fn migrate_to_preferred_address(&mut self, now: Instant) -> Res<()> {
1977 let spa: Option<(tparams::PreferredAddress, ConnectionIdEntry<[u8; 16]>)> = if matches!(
1978 self.conn_params.get_preferred_address(),
1979 PreferredAddressConfig::Disabled
1980 ) {
1981 qdebug!("[{self}] Preferred address is disabled");
1982 None
1983 } else {
1984 self.tps.borrow_mut().remote().get_preferred_address()
1985 };
1986 if let Some((addr, cid)) = spa {
1987 // The connection ID isn't special, so just save it.
1988 self.cids.add_remote(cid)?;
1989
1990 // The preferred address doesn't dictate what the local address is, so this
1991 // has to use the existing address. So only pay attention to a preferred
1992 // address from the same family as is currently in use. More thought will
1993 // be needed to work out how to get addresses from a different family.
1994 let prev = self
1995 .paths
1996 .primary()
1997 .ok_or(Error::NoAvailablePath)?
1998 .borrow()
1999 .remote_address();
2000 let remote = match prev.ip() {
2001 IpAddr::V4(_) => addr.ipv4().map(SocketAddr::V4),
2002 IpAddr::V6(_) => addr.ipv6().map(SocketAddr::V6),
2003 };
2004
2005 if let Some(remote) = remote {
2006 // Ignore preferred address that move to loopback from non-loopback.
2007 // `migrate` doesn't enforce this rule.
2008 if !prev.ip().is_loopback() && remote.ip().is_loopback() {
2009 qwarn!("[{self}] Ignoring a move to a loopback address: {remote}");
2010 return Ok(());
2011 }
2012
2013 if self.migrate(None, Some(remote), false, now).is_err() {
2014 qwarn!("[{self}] Ignoring bad preferred address: {remote}");
2015 }
2016 } else {
2017 qwarn!("[{self}] Unable to migrate to a different address family");
2018 }
2019 } else {
2020 qdebug!("[{self}] No preferred address to migrate to");
2021 }
2022 Ok(())
2023 }
2024
2025 fn handle_migration(
2026 &mut self,
2027 path: &PathRef,
2028 remote: SocketAddr,
2029 migrate: bool,
2030 now: Instant,
2031 ) {
2032 if !migrate {
2033 return;
2034 }
2035 if self.role == Role::Client {
2036 return;
2037 }
2038
2039 if self.ensure_permanent(path, now).is_ok() {
2040 self.paths
2041 .handle_migration(path, remote, now, &mut self.stats.borrow_mut());
2042 } else {
2043 qinfo!(
2044 "[{self}] {} Peer migrated, but no connection ID available",
2045 path.borrow()
2046 );
2047 }
2048 }
2049
2050 fn output(&mut self, now: Instant) -> SendOption {
2051 qtrace!("[{self}] output {now:?}");
2052 let res = match &self.state {
2053 State::Init
2054 | State::WaitInitial
2055 | State::WaitVersion
2056 | State::Handshaking
2057 | State::Connected
2058 | State::Confirmed => self.paths.select_path().map_or_else(
2059 || Ok(SendOption::default()),
2060 |path| {
2061 let res = self.output_path(&path, now, None);
2062 self.capture_error(Some(path), now, FrameType::Padding, res)
2063 },
2064 ),
2065 State::Closing { .. } | State::Draining { .. } | State::Closed(_) => {
2066 self.state_signaling.close_frame().map_or_else(
2067 || Ok(SendOption::default()),
2068 |details| {
2069 let path = Rc::clone(details.path());
2070 // In some error cases, we will not be able to make a new, permanent path.
2071 // For example, if we run out of connection IDs and the error results from
2072 // a packet on a new path, we avoid sending (and the privacy risk) rather
2073 // than reuse a connection ID.
2074 let res = if path.borrow().is_temporary() {
2075 qerror!("[{self}] Attempting to close with a temporary path");
2076 Err(Error::InternalError)
2077 } else {
2078 self.output_path(&path, now, Some(&details))
2079 };
2080 self.capture_error(Some(path), now, FrameType::Padding, res)
2081 },
2082 )
2083 }
2084 };
2085 res.unwrap_or_default()
2086 }
2087
2088 fn build_packet_header(
2089 path: &Path,
2090 epoch: Epoch,
2091 encoder: Encoder,
2092 tx: &CryptoDxState,
2093 address_validation: &AddressValidationInfo,
2094 version: Version,
2095 grease_quic_bit: bool,
2096 ) -> (PacketType, PacketBuilder) {
2097 let pt = PacketType::from(epoch);
2098 let mut builder = if pt == PacketType::Short {
2099 qdebug!("Building Short dcid {:?}", path.remote_cid());
2100 PacketBuilder::short(encoder, tx.key_phase(), path.remote_cid())
2101 } else {
2102 qdebug!(
2103 "Building {pt:?} dcid {:?} scid {:?}",
2104 path.remote_cid(),
2105 path.local_cid(),
2106 );
2107 PacketBuilder::long(encoder, pt, version, path.remote_cid(), path.local_cid())
2108 };
2109 if builder.remaining() > 0 {
2110 builder.scramble(grease_quic_bit);
2111 if pt == PacketType::Initial {
2112 builder.initial_token(address_validation.token());
2113 }
2114 }
2115
2116 (pt, builder)
2117 }
2118
2119 #[must_use]
2120 fn add_packet_number(
2121 builder: &mut PacketBuilder,
2122 tx: &CryptoDxState,
2123 largest_acknowledged: Option<PacketNumber>,
2124 ) -> PacketNumber {
2125 // Get the packet number and work out how long it is.
2126 let pn = tx.next_pn();
2127 let unacked_range = largest_acknowledged.map_or_else(|| pn + 1, |la| (pn - la) << 1);
2128 // Count how many bytes in this range are non-zero.
2129 let pn_len = size_of::<PacketNumber>()
2130 - usize::try_from(unacked_range.leading_zeros() / 8).expect("u32 fits in usize");
2131 assert!(
2132 pn_len > 0,
2133 "pn_len can't be zero as unacked_range should be > 0, pn {pn}, largest_acknowledged {largest_acknowledged:?}, tx {tx}"
2134 );
2135 // TODO(mt) also use `4*path CWND/path MTU` to set a minimum length.
2136 builder.pn(pn, pn_len);
2137 pn
2138 }
2139
2140 fn can_grease_quic_bit(&self) -> bool {
2141 let tph = self.tps.borrow();
2142 tph.remote_handshake().as_ref().map_or_else(
2143 || {
2144 tph.remote_0rtt()
2145 .is_some_and(|r| r.get_empty(GreaseQuicBit))
2146 },
2147 |r| r.get_empty(GreaseQuicBit),
2148 )
2149 }
2150
2151 /// Write the frames that are exchanged in the application data space.
2152 /// The order of calls here determines the relative priority of frames.
2153 fn write_appdata_frames(
2154 &mut self,
2155 builder: &mut PacketBuilder,
2156 tokens: &mut Vec<RecoveryToken>,
2157 now: Instant,
2158 ) {
2159 let rtt = self.paths.primary().map_or_else(
2160 || RttEstimate::default().estimate(),
2161 |p| p.borrow().rtt().estimate(),
2162 );
2163
2164 let stats = &mut self.stats.borrow_mut();
2165 let frame_stats = &mut stats.frame_tx;
2166 if self.role == Role::Server {
2167 if let Some(t) = self.state_signaling.write_done(builder) {
2168 tokens.push(t);
2169 frame_stats.handshake_done += 1;
2170 }
2171 }
2172
2173 self.streams
2174 .write_frames(TransmissionPriority::Critical, builder, tokens, frame_stats);
2175 if builder.is_full() {
2176 return;
2177 }
2178
2179 self.streams
2180 .write_maintenance_frames(builder, tokens, frame_stats, now, rtt);
2181 if builder.is_full() {
2182 return;
2183 }
2184
2185 self.streams.write_frames(
2186 TransmissionPriority::Important,
2187 builder,
2188 tokens,
2189 frame_stats,
2190 );
2191 if builder.is_full() {
2192 return;
2193 }
2194
2195 // NEW_CONNECTION_ID, RETIRE_CONNECTION_ID, and ACK_FREQUENCY.
2196 self.cid_manager.write_frames(builder, tokens, frame_stats);
2197 if builder.is_full() {
2198 return;
2199 }
2200
2201 self.paths.write_frames(builder, tokens, frame_stats);
2202 if builder.is_full() {
2203 return;
2204 }
2205
2206 for prio in [TransmissionPriority::High, TransmissionPriority::Normal] {
2207 self.streams
2208 .write_frames(prio, builder, tokens, &mut stats.frame_tx);
2209 if builder.is_full() {
2210 return;
2211 }
2212 }
2213
2214 // Datagrams are best-effort and unreliable. Let streams starve them for now.
2215 self.quic_datagrams.write_frames(builder, tokens, stats);
2216 if builder.is_full() {
2217 return;
2218 }
2219
2220 // CRYPTO here only includes NewSessionTicket, plus NEW_TOKEN.
2221 // Both of these are only used for resumption and so can be relatively low priority.
2222 let frame_stats = &mut stats.frame_tx;
2223 self.crypto.write_frame(
2224 PacketNumberSpace::ApplicationData,
2225 self.conn_params.sni_slicing_enabled(),
2226 builder,
2227 tokens,
2228 frame_stats,
2229 );
2230 if builder.is_full() {
2231 return;
2232 }
2233
2234 self.new_token.write_frames(builder, tokens, frame_stats);
2235 if builder.is_full() {
2236 return;
2237 }
2238
2239 self.streams
2240 .write_frames(TransmissionPriority::Low, builder, tokens, frame_stats);
2241
2242 #[cfg(test)]
2243 if let Some(w) = &mut self.test_frame_writer {
2244 w.write_frames(builder);
2245 }
2246 }
2247
2248 // Maybe send a probe. Return true if the packet was ack-eliciting.
2249 fn maybe_probe(
2250 &mut self,
2251 path: &PathRef,
2252 force_probe: bool,
2253 builder: &mut PacketBuilder,
2254 ack_end: usize,
2255 tokens: &mut Vec<RecoveryToken>,
2256 now: Instant,
2257 ) -> bool {
2258 let untracked = self.received_untracked && !self.state.connected();
2259 self.received_untracked = false;
2260
2261 // Anything written after an ACK already elicits acknowledgment.
2262 // If we need to probe and nothing has been written, send a PING.
2263 if builder.len() > ack_end {
2264 return true;
2265 }
2266
2267 let pto = path.borrow().rtt().pto(self.confirmed());
2268 let mut probe = if untracked && builder.packet_empty() || force_probe {
2269 // If we received an untracked packet and we aren't probing already
2270 // or the PTO timer fired: probe.
2271 true
2272 } else if !builder.packet_empty() {
2273 // The packet only contains an ACK. Check whether we want to
2274 // force an ACK with a PING so we can stop tracking packets.
2275 self.loss_recovery.should_probe(pto, now)
2276 } else {
2277 false
2278 };
2279
2280 if self.streams.need_keep_alive() {
2281 // We need to keep the connection alive, including sending a PING
2282 // again. If a PING is already scheduled (i.e. `probe` is `true`)
2283 // piggy back on it. If not, schedule one.
2284 probe |= self.idle_timeout.send_keep_alive(now, pto, tokens);
2285 }
2286
2287 if probe {
2288 // Nothing ack-eliciting and we need to probe; send PING.
2289 debug_assert_ne!(builder.remaining(), 0);
2290 builder.encode_varint(FrameType::Ping);
2291 let stats = &mut self.stats.borrow_mut().frame_tx;
2292 stats.ping += 1;
2293 }
2294 probe
2295 }
2296
2297 /// Write frames to the provided builder. Returns a list of tokens used for
2298 /// tracking loss or acknowledgment, whether any frame was ACK eliciting, and
2299 /// whether the packet was padded.
2300 fn write_frames(
2301 &mut self,
2302 path: &PathRef,
2303 space: PacketNumberSpace,
2304 profile: &SendProfile,
2305 builder: &mut PacketBuilder,
2306 coalesced: bool, // Whether this packet is coalesced behind another one.
2307 now: Instant,
2308 ) -> (Vec<RecoveryToken>, bool, bool) {
2309 let mut tokens = Vec::new();
2310 let primary = path.borrow().is_primary();
2311 let mut ack_eliciting = false;
2312
2313 if primary {
2314 let stats = &mut self.stats.borrow_mut().frame_tx;
2315 self.acks.write_frame(
2316 space,
2317 now,
2318 path.borrow().rtt().estimate(),
2319 builder,
2320 &mut tokens,
2321 stats,
2322 );
2323 }
2324 let ack_end = builder.len();
2325
2326 // Avoid sending path validation probes until the handshake completes,
2327 // but send them even when we don't have space.
2328 let full_mtu = profile.limit() == path.borrow().plpmtu();
2329 if space == PacketNumberSpace::ApplicationData && self.state.connected() {
2330 // Path validation probes should only be padded if the full MTU is available.
2331 // The probing code needs to know so it can track that.
2332 if path.borrow_mut().write_frames(
2333 builder,
2334 &mut self.stats.borrow_mut().frame_tx,
2335 full_mtu,
2336 now,
2337 ) {
2338 builder.enable_padding(true);
2339 }
2340 }
2341
2342 if profile.ack_only(space) {
2343 // If we are CC limited we can only send ACKs!
2344 return (tokens, false, false);
2345 }
2346
2347 if primary {
2348 if space == PacketNumberSpace::ApplicationData {
2349 if self.state.connected()
2350 && path.borrow().pmtud().needs_probe()
2351 && !coalesced // Only send PMTUD probes using non-coalesced packets.
2352 && full_mtu
2353 {
2354 path.borrow_mut()
2355 .pmtud_mut()
2356 .send_probe(builder, &mut self.stats.borrow_mut());
2357 ack_eliciting = true;
2358 }
2359 self.write_appdata_frames(builder, &mut tokens, now);
2360 } else {
2361 let stats = &mut self.stats.borrow_mut().frame_tx;
2362 self.crypto.write_frame(
2363 space,
2364 self.conn_params.sni_slicing_enabled(),
2365 builder,
2366 &mut tokens,
2367 stats,
2368 );
2369 }
2370 }
2371
2372 // Maybe send a probe now, either to probe for losses or to keep the connection live.
2373 let force_probe = profile.should_probe(space);
2374 ack_eliciting |= self.maybe_probe(path, force_probe, builder, ack_end, &mut tokens, now);
2375 // If this is not the primary path, this should be ack-eliciting.
2376 debug_assert!(primary || ack_eliciting);
2377
2378 // Add padding. Only pad 1-RTT packets so that we don't prevent coalescing.
2379 // And avoid padding packets that otherwise only contain ACK because adding PADDING
2380 // causes those packets to consume congestion window, which is not tracked (yet).
2381 // And avoid padding if we don't have a full MTU available.
2382 let stats = &mut self.stats.borrow_mut().frame_tx;
2383 let padded = if ack_eliciting && full_mtu && builder.pad() {
2384 stats.padding += 1;
2385 true
2386 } else {
2387 false
2388 };
2389
2390 (tokens, ack_eliciting, padded)
2391 }
2392
2393 fn write_closing_frames(
2394 &mut self,
2395 close: &ClosingFrame,
2396 builder: &mut PacketBuilder,
2397 space: PacketNumberSpace,
2398 now: Instant,
2399 path: &PathRef,
2400 tokens: &mut Vec<RecoveryToken>,
2401 ) {
2402 if builder.remaining() > ClosingFrame::MIN_LENGTH + RecvdPackets::USEFUL_ACK_LEN {
2403 // Include an ACK frame with the CONNECTION_CLOSE.
2404 let limit = builder.limit();
2405 builder.set_limit(limit - ClosingFrame::MIN_LENGTH);
2406 self.acks.immediate_ack(space, now);
2407 self.acks.write_frame(
2408 space,
2409 now,
2410 path.borrow().rtt().estimate(),
2411 builder,
2412 tokens,
2413 &mut self.stats.borrow_mut().frame_tx,
2414 );
2415 builder.set_limit(limit);
2416 }
2417 // CloseReason::Application is only allowed at 1RTT.
2418 let sanitized = if space == PacketNumberSpace::ApplicationData {
2419 None
2420 } else {
2421 close.sanitize()
2422 };
2423 sanitized.as_ref().unwrap_or(close).write_frame(builder);
2424 self.stats.borrow_mut().frame_tx.connection_close += 1;
2425 }
2426
2427 /// Build a datagram, possibly from multiple packets (for different PN
2428 /// spaces) and each containing 1+ frames.
2429 #[expect(clippy::too_many_lines, reason = "Yeah, that's just the way it is.")]
2430 fn output_path(
2431 &mut self,
2432 path: &PathRef,
2433 now: Instant,
2434 closing_frame: Option<&ClosingFrame>,
2435 ) -> Res<SendOption> {
2436 let mut initial_sent = None;
2437 let mut packet_tos = None;
2438 let mut needs_padding = false;
2439 let grease_quic_bit = self.can_grease_quic_bit();
2440 let version = self.version();
2441
2442 // Determine how we are sending packets (PTO, etc..).
2443 let profile = self.loss_recovery.send_profile(&path.borrow(), now);
2444 qdebug!("[{self}] output_path send_profile {profile:?}");
2445
2446 // Frames for different epochs must go in different packets, but then these
2447 // packets can go in a single datagram
2448 let mut encoder = Encoder::with_capacity(profile.limit());
2449 for space in PacketNumberSpace::iter() {
2450 // Ensure we have tx crypto state for this epoch, or skip it.
2451 let Some((epoch, tx)) = self.crypto.states_mut().select_tx_mut(self.version, space)
2452 else {
2453 continue;
2454 };
2455
2456 let header_start = encoder.len();
2457 let (pt, mut builder) = Self::build_packet_header(
2458 &path.borrow(),
2459 epoch,
2460 encoder,
2461 tx,
2462 &self.address_validation,
2463 version,
2464 grease_quic_bit,
2465 );
2466 let pn = Self::add_packet_number(
2467 &mut builder,
2468 tx,
2469 self.loss_recovery.largest_acknowledged_pn(space),
2470 );
2471 // The builder will set the limit to 0 if there isn't enough space for the header.
2472 if builder.is_full() {
2473 encoder = builder.abort();
2474 break;
2475 }
2476
2477 // Configure the limits and padding for this packet.
2478 let aead_expansion = tx.expansion();
2479 needs_padding |= builder.set_initial_limit(
2480 &profile,
2481 aead_expansion,
2482 self.paths
2483 .primary()
2484 .ok_or(Error::InternalError)?
2485 .borrow()
2486 .pmtud(),
2487 );
2488 builder.enable_padding(needs_padding);
2489 if builder.is_full() {
2490 encoder = builder.abort();
2491 break;
2492 }
2493
2494 // Add frames to the packet.
2495 let payload_start = builder.len();
2496 let (mut tokens, mut ack_eliciting, mut padded) = (Vec::new(), false, false);
2497 if let Some(close) = closing_frame {
2498 self.write_closing_frames(close, &mut builder, space, now, path, &mut tokens);
2499 } else {
2500 (tokens, ack_eliciting, padded) =
2501 self.write_frames(path, space, &profile, &mut builder, header_start != 0, now);
2502 }
2503 if builder.packet_empty() {
2504 // Nothing to include in this packet.
2505 encoder = builder.abort();
2506 continue;
2507 }
2508
2509 // If we don't have a TOS for this UDP datagram yet (i.e. `tos` is `None`), get it,
2510 // adding a `RecoveryToken::EcnEct0` to `tokens` in case of loss.
2511 let tos = packet_tos.get_or_insert_with(|| path.borrow().tos(&mut tokens));
2512 self.log_packet(
2513 packet::MetaData::new_out(
2514 path,
2515 pt,
2516 pn,
2517 builder.len() + aead_expansion,
2518 &builder.as_ref()[payload_start..],
2519 *tos,
2520 ),
2521 now,
2522 );
2523
2524 self.stats.borrow_mut().packets_tx += 1;
2525 let tx = self
2526 .crypto
2527 .states_mut()
2528 .tx_mut(self.version, epoch)
2529 .ok_or(Error::InternalError)?;
2530 encoder = builder.build(tx)?;
2531 self.crypto.states_mut().auto_update()?;
2532
2533 if ack_eliciting {
2534 self.idle_timeout.on_packet_sent(now);
2535 }
2536 let sent = SentPacket::new(
2537 pt,
2538 pn,
2539 now,
2540 ack_eliciting,
2541 tokens,
2542 encoder.len() - header_start,
2543 );
2544 if padded {
2545 needs_padding = false;
2546 self.loss_recovery.on_packet_sent(path, sent, now);
2547 } else if pt == PacketType::Initial && (self.role == Role::Client || ack_eliciting) {
2548 // Packets containing Initial packets might need padding, and we want to
2549 // track that padding along with the Initial packet. So defer tracking.
2550 initial_sent = Some(sent);
2551 needs_padding = true;
2552 } else {
2553 if pt == PacketType::Handshake && self.role == Role::Client {
2554 needs_padding = false;
2555 }
2556 self.loss_recovery.on_packet_sent(path, sent, now);
2557 }
2558
2559 // Track which packet types are sent with which ECN codepoints. For
2560 // coalesced packets, this increases the counts for each packet type
2561 // contained in the coalesced packet. This is per Section 13.4.1 of
2562 // RFC 9000.
2563 self.stats.borrow_mut().ecn_tx[pt] += IpTosEcn::from(*tos);
2564 if space == PacketNumberSpace::Handshake {
2565 if self.role == Role::Client {
2566 // We're sending a Handshake packet, so we can discard Initial keys.
2567 self.discard_keys(PacketNumberSpace::Initial, now);
2568 } else if self.role == Role::Server && self.state == State::Confirmed {
2569 // We could discard handshake keys in set_state,
2570 // but wait until after sending an ACK.
2571 self.discard_keys(PacketNumberSpace::Handshake, now);
2572 }
2573 }
2574
2575 // If the client has more CRYPTO data queued up, do not coalesce if
2576 // this packet is an Initial. Without this, 0-RTT packets could be
2577 // coalesced with the first Initial, which some server (e.g., ours)
2578 // do not support, because they may not save packets they can't
2579 // decrypt yet.
2580 if self.role == Role::Client
2581 && space == PacketNumberSpace::Initial
2582 && !self.crypto.streams_mut().is_empty(space)
2583 {
2584 break;
2585 }
2586 }
2587
2588 if encoder.is_empty() {
2589 qdebug!("TX blocked, profile={profile:?}");
2590 Ok(SendOption::No(profile.paced()))
2591 } else {
2592 // Perform additional padding for Initial packets as necessary.
2593 let mut packets: Vec<u8> = encoder.into();
2594 if let Some(mut initial) = initial_sent.take() {
2595 if needs_padding && packets.len() < profile.limit() {
2596 qdebug!(
2597 "[{self}] pad Initial from {} to PLPMTU {}",
2598 packets.len(),
2599 profile.limit()
2600 );
2601 initial.track_padding(profile.limit() - packets.len());
2602 // These zeros aren't padding frames, they are an invalid all-zero coalesced
2603 // packet, which is why we don't increase `frame_tx.padding` count here.
2604 packets.resize(profile.limit(), 0);
2605 }
2606 self.loss_recovery.on_packet_sent(path, initial, now);
2607 }
2608 path.borrow_mut().add_sent(packets.len());
2609 Ok(SendOption::Yes(path.borrow_mut().datagram(
2610 packets,
2611 packet_tos.unwrap_or_default(),
2612 &mut self.stats.borrow_mut(),
2613 )))
2614 }
2615 }
2616
2617 /// # Errors
2618 /// When connection state is not valid.
2619 pub fn initiate_key_update(&mut self) -> Res<()> {
2620 if self.state == State::Confirmed {
2621 let la = self
2622 .loss_recovery
2623 .largest_acknowledged_pn(PacketNumberSpace::ApplicationData);
2624 qinfo!("[{self}] Initiating key update");
2625 self.crypto.states_mut().initiate_key_update(la)
2626 } else {
2627 Err(Error::KeyUpdateBlocked)
2628 }
2629 }
2630
2631 #[cfg(test)]
2632 #[must_use]
2633 pub fn get_epochs(&self) -> (Option<usize>, Option<usize>) {
2634 self.crypto.states().get_epochs()
2635 }
2636
2637 fn client_start(&mut self, now: Instant) -> Res<()> {
2638 qdebug!("[{self}] client_start");
2639 debug_assert_eq!(self.role, Role::Client);
2640 if let Some(path) = self.paths.primary() {
2641 qlog::client_connection_started(&self.qlog, &path, now);
2642 }
2643 qlog::client_version_information_initiated(
2644 &self.qlog,
2645 self.conn_params.get_versions(),
2646 now,
2647 );
2648
2649 self.handshake(now, self.version, PacketNumberSpace::Initial, None)?;
2650 self.set_state(State::WaitInitial, now);
2651 self.zero_rtt_state = if self.crypto.enable_0rtt(self.version, self.role)? {
2652 qdebug!("[{self}] Enabled 0-RTT");
2653 ZeroRttState::Sending
2654 } else {
2655 ZeroRttState::Init
2656 };
2657 Ok(())
2658 }
2659
2660 fn get_closing_period_time(&self, now: Instant) -> Instant {
2661 // Spec says close time should be at least PTO times 3.
2662 now + (self.pto() * 3)
2663 }
2664
2665 /// Close the connection.
2666 pub fn close(&mut self, now: Instant, app_error: AppError, msg: impl AsRef<str>) {
2667 let error = CloseReason::Application(app_error);
2668 let timeout = self.get_closing_period_time(now);
2669 if let Some(path) = self.paths.primary() {
2670 self.state_signaling
2671 .close(path, error.clone(), FrameType::Padding, msg);
2672 self.set_state(State::Closing { error, timeout }, now);
2673 } else {
2674 self.set_state(State::Closed(error), now);
2675 }
2676 }
2677
2678 fn set_initial_limits(&mut self) {
2679 self.streams.set_initial_limits();
2680 let peer_timeout = self
2681 .tps
2682 .borrow()
2683 .remote()
2684 .get_integer(TransportParameterId::IdleTimeout);
2685 if peer_timeout > 0 {
2686 self.idle_timeout
2687 .set_peer_timeout(Duration::from_millis(peer_timeout));
2688 }
2689
2690 self.quic_datagrams
2691 .set_remote_datagram_size(self.tps.borrow().remote().get_integer(MaxDatagramFrameSize));
2692 }
2693
2694 #[must_use]
2695 pub fn is_stream_id_allowed(&self, stream_id: StreamId) -> bool {
2696 self.streams.is_stream_id_allowed(stream_id)
2697 }
2698
2699 /// Process the final set of transport parameters.
2700 fn process_tps(&mut self, now: Instant) -> Res<()> {
2701 self.validate_cids()?;
2702 self.validate_versions()?;
2703 {
2704 let tps = self.tps.borrow();
2705 let remote = tps
2706 .remote_handshake()
2707 .ok_or(Error::TransportParameterError)?;
2708
2709 // If the peer provided a preferred address, then we have to be a client
2710 // and they have to be using a non-empty connection ID.
2711 if remote.get_preferred_address().is_some()
2712 && (self.role == Role::Server
2713 || self
2714 .remote_initial_source_cid
2715 .as_ref()
2716 .ok_or(Error::UnknownConnectionId)?
2717 .is_empty())
2718 {
2719 return Err(Error::TransportParameterError);
2720 }
2721
2722 let reset_token = remote.get_bytes(StatelessResetToken).map_or_else(
2723 || Ok(ConnectionIdEntry::random_srt()),
2724 |token| <[u8; 16]>::try_from(token).map_err(|_| Error::TransportParameterError),
2725 )?;
2726 let path = self.paths.primary().ok_or(Error::NoAvailablePath)?;
2727 path.borrow_mut().set_reset_token(reset_token);
2728
2729 let max_ad = Duration::from_millis(remote.get_integer(MaxAckDelay));
2730 let min_ad = if remote.has_value(MinAckDelay) {
2731 let min_ad = Duration::from_micros(remote.get_integer(MinAckDelay));
2732 if min_ad > max_ad {
2733 return Err(Error::TransportParameterError);
2734 }
2735 Some(min_ad)
2736 } else {
2737 None
2738 };
2739 path.borrow_mut()
2740 .set_ack_delay(max_ad, min_ad, self.conn_params.get_ack_ratio());
2741
2742 let max_active_cids = remote.get_integer(ActiveConnectionIdLimit);
2743 self.cid_manager.set_limit(max_active_cids);
2744 }
2745 self.set_initial_limits();
2746 qlog::connection_tparams_set(&self.qlog, &self.tps.borrow(), now);
2747 Ok(())
2748 }
2749
2750 fn validate_cids(&self) -> Res<()> {
2751 let tph = self.tps.borrow();
2752 let remote_tps = tph
2753 .remote_handshake()
2754 .ok_or(Error::TransportParameterError)?;
2755
2756 let tp = remote_tps.get_bytes(InitialSourceConnectionId);
2757 if self
2758 .remote_initial_source_cid
2759 .as_ref()
2760 .map(ConnectionId::as_cid_ref)
2761 != tp.map(ConnectionIdRef::from)
2762 {
2763 qwarn!(
2764 "[{self}] ISCID test failed: self cid {:?} != tp cid {:?}",
2765 self.remote_initial_source_cid,
2766 tp.map(hex),
2767 );
2768 return Err(Error::ProtocolViolation);
2769 }
2770
2771 if self.role == Role::Client {
2772 let tp = remote_tps.get_bytes(OriginalDestinationConnectionId);
2773 if self
2774 .original_destination_cid
2775 .as_ref()
2776 .map(ConnectionId::as_cid_ref)
2777 != tp.map(ConnectionIdRef::from)
2778 {
2779 qwarn!(
2780 "[{self}] ODCID test failed: self cid {:?} != tp cid {:?}",
2781 self.original_destination_cid,
2782 tp.map(hex),
2783 );
2784 return Err(Error::ProtocolViolation);
2785 }
2786
2787 let tp = remote_tps.get_bytes(RetrySourceConnectionId);
2788 let expected = if let AddressValidationInfo::Retry {
2789 retry_source_cid, ..
2790 } = &self.address_validation
2791 {
2792 Some(retry_source_cid.as_cid_ref())
2793 } else {
2794 None
2795 };
2796 if expected != tp.map(ConnectionIdRef::from) {
2797 qwarn!(
2798 "[{self}] RSCID test failed. self cid {expected:?} != tp cid {:?}",
2799 tp.map(hex),
2800 );
2801 return Err(Error::ProtocolViolation);
2802 }
2803 }
2804
2805 Ok(())
2806 }
2807
2808 /// Validate the `version_negotiation` transport parameter from the peer.
2809 fn validate_versions(&self) -> Res<()> {
2810 let tph = self.tps.borrow();
2811 let remote_tps = tph
2812 .remote_handshake()
2813 .ok_or(Error::TransportParameterError)?;
2814 // `current` and `other` are the value from the peer's transport parameters.
2815 // We're checking that these match our expectations.
2816 if let Some((current, other)) = remote_tps.get_versions() {
2817 qtrace!(
2818 "[{self}] validate_versions: current={:x} chosen={current:x} other={other:x?}",
2819 self.version.wire_version(),
2820 );
2821 if self.role == Role::Server {
2822 // 1. A server acts on transport parameters, with validation
2823 // of `current` happening in the transport parameter handler.
2824 // All we need to do is confirm that the transport parameter
2825 // was provided.
2826 Ok(())
2827 } else if self.version().wire_version() != current {
2828 qinfo!("[{self}] validate_versions: current version mismatch");
2829 Err(Error::VersionNegotiation)
2830 } else if self
2831 .conn_params
2832 .get_versions()
2833 .initial()
2834 .is_compatible(self.version)
2835 {
2836 // 2. The current version is compatible with what we attempted.
2837 // That's a compatible upgrade and that's OK.
2838 Ok(())
2839 } else {
2840 // 3. The initial version we attempted isn't compatible. Check that
2841 // the one we would have chosen is compatible with this one.
2842 let mut all_versions = other.to_owned();
2843 all_versions.push(current);
2844 if self
2845 .conn_params
2846 .get_versions()
2847 .preferred(&all_versions)
2848 .ok_or(Error::VersionNegotiation)?
2849 .is_compatible(self.version)
2850 {
2851 Ok(())
2852 } else {
2853 qinfo!("[{self}] validate_versions: failed");
2854 Err(Error::VersionNegotiation)
2855 }
2856 }
2857 } else if self.version != Version::Version1 && !self.version.is_draft() {
2858 qinfo!("[{self}] validate_versions: missing extension");
2859 Err(Error::VersionNegotiation)
2860 } else {
2861 Ok(())
2862 }
2863 }
2864
2865 fn confirm_version(&mut self, v: Version) -> Res<()> {
2866 if self.version != v {
2867 qdebug!("[{self}] Compatible upgrade {:?} ==> {v:?}", self.version);
2868 }
2869 self.crypto.confirm_version(v)?;
2870 self.version = v;
2871 Ok(())
2872 }
2873
2874 fn compatible_upgrade(&mut self, packet_version: Version) -> Res<()> {
2875 if !matches!(self.state, State::WaitInitial | State::WaitVersion) {
2876 return Ok(());
2877 }
2878
2879 if self.role == Role::Client {
2880 self.confirm_version(packet_version)?;
2881 } else if self.tps.borrow().remote_handshake().is_some() {
2882 let version = self.tps.borrow().version();
2883 let dcid = self
2884 .original_destination_cid
2885 .as_ref()
2886 .ok_or(Error::ProtocolViolation)?;
2887 self.crypto.states_mut().init_server(version, dcid)?;
2888 self.confirm_version(version)?;
2889 }
2890 Ok(())
2891 }
2892
2893 fn handshake(
2894 &mut self,
2895 now: Instant,
2896 packet_version: Version,
2897 space: PacketNumberSpace,
2898 data: Option<&[u8]>,
2899 ) -> Res<()> {
2900 qtrace!("[{self}] Handshake space={space} data={data:0x?}");
2901
2902 let was_authentication_pending =
2903 *self.crypto.tls().state() == HandshakeState::AuthenticationPending;
2904 let try_update = data.is_some();
2905 match self.crypto.handshake(now, space, data)? {
2906 HandshakeState::Authenticated(_) | HandshakeState::InProgress => (),
2907 HandshakeState::AuthenticationPending => {
2908 if !was_authentication_pending {
2909 self.events.authentication_needed();
2910 }
2911 }
2912 HandshakeState::EchFallbackAuthenticationPending(public_name) => self
2913 .events
2914 .ech_fallback_authentication_needed(public_name.clone()),
2915 HandshakeState::Complete(_) => {
2916 if !self.state.connected() {
2917 self.set_connected(now)?;
2918 }
2919 }
2920 _ => {
2921 qerror!("Crypto state should not be new or failed after successful handshake");
2922 return Err(Error::CryptoError(neqo_crypto::Error::InternalError));
2923 }
2924 }
2925
2926 // There is a chance that this could be called less often, but getting the
2927 // conditions right is a little tricky, so call whenever CRYPTO data is used.
2928 if try_update {
2929 self.compatible_upgrade(packet_version)?;
2930 // We have transport parameters, it's go time.
2931 if self.tps.borrow().remote_handshake().is_some() {
2932 self.set_initial_limits();
2933 }
2934 if self.crypto.install_keys(self.role)? {
2935 self.saved_datagrams.make_available(Epoch::Handshake);
2936 }
2937 }
2938
2939 Ok(())
2940 }
2941
2942 fn set_confirmed(&mut self, now: Instant) -> Res<()> {
2943 self.set_state(State::Confirmed, now);
2944 if self.conn_params.pmtud_enabled() {
2945 self.paths
2946 .primary()
2947 .ok_or(Error::InternalError)?
2948 .borrow_mut()
2949 .pmtud_mut()
2950 .start(now, &mut self.stats.borrow_mut());
2951 }
2952 Ok(())
2953 }
2954
2955 #[expect(clippy::too_many_lines, reason = "Yep, but it's a nice big match.")]
2956 fn input_frame(
2957 &mut self,
2958 path: &PathRef,
2959 packet_version: Version,
2960 packet_type: PacketType,
2961 frame: Frame,
2962 next_pn: PacketNumber,
2963 now: Instant,
2964 ) -> Res<()> {
2965 if !frame.is_allowed(packet_type) {
2966 qinfo!("frame not allowed: {frame:?} {packet_type:?}");
2967 return Err(Error::ProtocolViolation);
2968 }
2969 let space = PacketNumberSpace::from(packet_type);
2970 if frame.is_stream() {
2971 return self
2972 .streams
2973 .input_frame(&frame, &mut self.stats.borrow_mut().frame_rx);
2974 }
2975 match frame {
2976 Frame::Padding(length) => {
2977 self.stats.borrow_mut().frame_rx.padding += usize::from(length);
2978 }
2979 Frame::Ping => {
2980 // If we get a PING and there are outstanding CRYPTO frames,
2981 // prepare to resend them.
2982 self.stats.borrow_mut().frame_rx.ping += 1;
2983 self.crypto.resend_unacked(space);
2984 // Send an ACK immediately if we might not otherwise do so.
2985 self.acks.immediate_ack(space, now);
2986 }
2987 Frame::Ack {
2988 largest_acknowledged,
2989 ack_delay,
2990 first_ack_range,
2991 ack_ranges,
2992 ecn_count,
2993 } => {
2994 // Ensure that the largest acknowledged packet number was actually sent.
2995 // (If we ever start using non-contiguous packet numbers, we need to check all the
2996 // packet numbers in the ACKed ranges.)
2997 if largest_acknowledged >= next_pn {
2998 qwarn!("Largest ACKed {largest_acknowledged} was never sent");
2999 return Err(Error::AckedUnsentPacket);
3000 }
3001
3002 let ranges =
3003 Frame::decode_ack_frame(largest_acknowledged, first_ack_range, &ack_ranges)?;
3004 self.handle_ack(space, ranges, ecn_count, ack_delay, now)?;
3005 }
3006 Frame::Crypto { offset, data } => {
3007 qtrace!(
3008 "[{self}] Crypto frame on space={space} offset={offset}, data={:0x?}",
3009 &data
3010 );
3011 self.stats.borrow_mut().frame_rx.crypto += 1;
3012 self.crypto
3013 .streams_mut()
3014 .inbound_frame(space, offset, data)?;
3015 if self.crypto.streams().data_ready(space) {
3016 let mut buf = Vec::new();
3017 let read = self.crypto.streams_mut().read_to_end(space, &mut buf);
3018 qdebug!("Read {read:?} bytes");
3019 self.handshake(now, packet_version, space, Some(&buf))?;
3020 self.create_resumption_token(now);
3021 } else {
3022 // If we get a useless CRYPTO frame send outstanding CRYPTO frames and 0-RTT
3023 // data again.
3024 self.crypto.resend_unacked(space);
3025 if space == PacketNumberSpace::Initial {
3026 self.crypto.resend_unacked(PacketNumberSpace::Handshake);
3027 self.resend_0rtt(now);
3028 }
3029 }
3030 }
3031 Frame::NewToken { token } => {
3032 self.stats.borrow_mut().frame_rx.new_token += 1;
3033 self.new_token.save_token(token.to_vec());
3034 self.create_resumption_token(now);
3035 }
3036 Frame::NewConnectionId {
3037 sequence_number,
3038 connection_id,
3039 stateless_reset_token,
3040 retire_prior,
3041 } => {
3042 self.stats.borrow_mut().frame_rx.new_connection_id += 1;
3043 self.cids.add_remote(ConnectionIdEntry::new(
3044 sequence_number,
3045 ConnectionId::from(connection_id),
3046 stateless_reset_token.to_owned(),
3047 ))?;
3048 self.paths.retire_cids(retire_prior, &mut self.cids);
3049 if self.cids.len() >= LOCAL_ACTIVE_CID_LIMIT {
3050 qinfo!("[{self}] received too many connection IDs");
3051 return Err(Error::ConnectionIdLimitExceeded);
3052 }
3053 }
3054 Frame::RetireConnectionId { sequence_number } => {
3055 self.stats.borrow_mut().frame_rx.retire_connection_id += 1;
3056 self.cid_manager.retire(sequence_number);
3057 }
3058 Frame::PathChallenge { data } => {
3059 self.stats.borrow_mut().frame_rx.path_challenge += 1;
3060 // If we were challenged, try to make the path permanent.
3061 // Report an error if we don't have enough connection IDs.
3062 self.ensure_permanent(path, now)?;
3063 path.borrow_mut().challenged(data);
3064 }
3065 Frame::PathResponse { data } => {
3066 self.stats.borrow_mut().frame_rx.path_response += 1;
3067 if self
3068 .paths
3069 .path_response(data, now, &mut self.stats.borrow_mut())
3070 {
3071 // This PATH_RESPONSE enabled migration; tell loss recovery.
3072 self.loss_recovery.migrate();
3073 }
3074 }
3075 Frame::ConnectionClose {
3076 error_code,
3077 frame_type,
3078 reason_phrase,
3079 } => {
3080 self.stats.borrow_mut().frame_rx.connection_close += 1;
3081 qinfo!(
3082 "[{self}] ConnectionClose received. Error code: {error_code:?} frame type {frame_type:x} reason {reason_phrase}"
3083 );
3084 let (detail, frame_type) = if let CloseError::Application(_) = error_code {
3085 // Use a transport error here because we want to send
3086 // NO_ERROR in this case.
3087 (
3088 Error::PeerApplicationError(error_code.code()),
3089 FrameType::ConnectionCloseApplication,
3090 )
3091 } else {
3092 (
3093 Error::PeerError(error_code.code()),
3094 FrameType::ConnectionCloseTransport,
3095 )
3096 };
3097 let error = CloseReason::Transport(detail);
3098 self.state_signaling
3099 .drain(Rc::clone(path), error.clone(), frame_type, "");
3100 self.set_state(
3101 State::Draining {
3102 error,
3103 timeout: self.get_closing_period_time(now),
3104 },
3105 now,
3106 );
3107 }
3108 Frame::HandshakeDone => {
3109 self.stats.borrow_mut().frame_rx.handshake_done += 1;
3110 if self.role == Role::Server || !self.state.connected() {
3111 return Err(Error::ProtocolViolation);
3112 }
3113 self.set_confirmed(now)?;
3114 self.discard_keys(PacketNumberSpace::Handshake, now);
3115 self.migrate_to_preferred_address(now)?;
3116 }
3117 Frame::AckFrequency {
3118 seqno,
3119 tolerance,
3120 delay,
3121 ignore_order,
3122 } => {
3123 self.stats.borrow_mut().frame_rx.ack_frequency += 1;
3124 let delay = Duration::from_micros(delay);
3125 if delay < GRANULARITY {
3126 return Err(Error::ProtocolViolation);
3127 }
3128 self.acks
3129 .ack_freq(seqno, tolerance - 1, delay, ignore_order);
3130 }
3131 Frame::Datagram { data, .. } => {
3132 self.stats.borrow_mut().frame_rx.datagram += 1;
3133 self.quic_datagrams
3134 .handle_datagram(data, &mut self.stats.borrow_mut())?;
3135 }
3136 _ => unreachable!("All other frames are for streams"),
3137 }
3138
3139 Ok(())
3140 }
3141
3142 /// Given a set of `SentPacket` instances, ensure that the source of the packet
3143 /// is told that they are lost. This gives the frame generation code a chance
3144 /// to retransmit the frame as needed.
3145 fn handle_lost_packets(&mut self, lost_packets: &[SentPacket]) {
3146 for lost in lost_packets {
3147 for token in lost.tokens() {
3148 qdebug!("[{self}] Lost: {token:?}");
3149 match token {
3150 RecoveryToken::Ack(ack_token) => {
3151 // If we lost an ACK frame during the handshake, send another one.
3152 if ack_token.space() != PacketNumberSpace::ApplicationData {
3153 self.acks.immediate_ack(ack_token.space(), lost.time_sent());
3154 }
3155 }
3156 RecoveryToken::Crypto(ct) => self.crypto.lost(ct),
3157 RecoveryToken::HandshakeDone => self.state_signaling.handshake_done(),
3158 RecoveryToken::NewToken(seqno) => self.new_token.lost(*seqno),
3159 RecoveryToken::NewConnectionId(ncid) => self.cid_manager.lost(ncid),
3160 RecoveryToken::RetireConnectionId(seqno) => self.paths.lost_retire_cid(*seqno),
3161 RecoveryToken::AckFrequency(rate) => self.paths.lost_ack_frequency(rate),
3162 RecoveryToken::KeepAlive => self.idle_timeout.lost_keep_alive(),
3163 RecoveryToken::Stream(stream_token) => self.streams.lost(stream_token),
3164 RecoveryToken::Datagram(dgram_tracker) => {
3165 self.events
3166 .datagram_outcome(dgram_tracker, OutgoingDatagramOutcome::Lost);
3167 self.stats.borrow_mut().datagram_tx.lost += 1;
3168 }
3169 RecoveryToken::EcnEct0 => self
3170 .paths
3171 .lost_ecn(lost.packet_type(), &mut self.stats.borrow_mut()),
3172 }
3173 }
3174 }
3175 }
3176
3177 fn decode_ack_delay(&self, v: u64) -> Res<Duration> {
3178 // If we have remote transport parameters, use them.
3179 // Otherwise, ack delay should be zero (because it's the handshake).
3180 self.tps.borrow().remote_handshake().map_or_else(
3181 || Ok(Duration::default()),
3182 |r| {
3183 let exponent = u32::try_from(r.get_integer(AckDelayExponent))?;
3184 // ACK_DELAY_EXPONENT > 20 is invalid per RFC9000. We already checked that in
3185 // TransportParameter::decode.
3186 let corrected = if v.leading_zeros() >= exponent {
3187 v << exponent
3188 } else {
3189 u64::MAX
3190 };
3191 Ok(Duration::from_micros(corrected))
3192 },
3193 )
3194 }
3195
3196 fn handle_ack<R>(
3197 &mut self,
3198 space: PacketNumberSpace,
3199 ack_ranges: R,
3200 ack_ecn: Option<ecn::Count>,
3201 ack_delay: u64,
3202 now: Instant,
3203 ) -> Res<()>
3204 where
3205 R: IntoIterator<Item = RangeInclusive<PacketNumber>> + Debug,
3206 R::IntoIter: ExactSizeIterator,
3207 {
3208 qdebug!("[{self}] Rx ACK space={space}, ranges={ack_ranges:?}");
3209
3210 let Some(path) = self.paths.primary() else {
3211 return Ok(());
3212 };
3213 let (acked_packets, lost_packets) = self.loss_recovery.on_ack_received(
3214 &path,
3215 space,
3216 ack_ranges,
3217 ack_ecn,
3218 self.decode_ack_delay(ack_delay)?,
3219 now,
3220 );
3221 let largest_acknowledged = acked_packets.first().map(SentPacket::pn);
3222 for acked in acked_packets {
3223 for token in acked.tokens() {
3224 match token {
3225 RecoveryToken::Stream(stream_token) => self.streams.acked(stream_token),
3226 RecoveryToken::Ack(at) => self.acks.acked(at),
3227 RecoveryToken::Crypto(ct) => self.crypto.acked(ct),
3228 RecoveryToken::NewToken(seqno) => self.new_token.acked(*seqno),
3229 RecoveryToken::NewConnectionId(entry) => self.cid_manager.acked(entry),
3230 RecoveryToken::RetireConnectionId(seqno) => self.paths.acked_retire_cid(*seqno),
3231 RecoveryToken::AckFrequency(rate) => self.paths.acked_ack_frequency(rate),
3232 RecoveryToken::KeepAlive => self.idle_timeout.ack_keep_alive(),
3233 RecoveryToken::Datagram(dgram_tracker) => self
3234 .events
3235 .datagram_outcome(dgram_tracker, OutgoingDatagramOutcome::Acked),
3236 RecoveryToken::EcnEct0 => self.paths.acked_ecn(),
3237 // We only worry when these are lost
3238 RecoveryToken::HandshakeDone => (),
3239 }
3240 }
3241 }
3242 self.handle_lost_packets(&lost_packets);
3243 qlog::packets_lost(&self.qlog, &lost_packets, now);
3244 let stats = &mut self.stats.borrow_mut().frame_rx;
3245 stats.ack += 1;
3246 if let Some(largest_acknowledged) = largest_acknowledged {
3247 stats.largest_acknowledged = max(stats.largest_acknowledged, largest_acknowledged);
3248 }
3249 Ok(())
3250 }
3251
3252 /// Tell 0-RTT packets that they were "lost".
3253 fn resend_0rtt(&mut self, now: Instant) {
3254 if let Some(path) = self.paths.primary() {
3255 let dropped = self.loss_recovery.drop_0rtt(&path, now);
3256 self.handle_lost_packets(&dropped);
3257 }
3258 }
3259
3260 /// When the server rejects 0-RTT we need to drop a bunch of stuff.
3261 fn client_0rtt_rejected(&mut self, now: Instant) {
3262 if !matches!(self.zero_rtt_state, ZeroRttState::Sending) {
3263 return;
3264 }
3265 qdebug!("[{self}] 0-RTT rejected");
3266 self.resend_0rtt(now);
3267 self.streams.zero_rtt_rejected();
3268 self.crypto.states_mut().discard_0rtt_keys();
3269 self.events.client_0rtt_rejected();
3270 }
3271
3272 fn set_connected(&mut self, now: Instant) -> Res<()> {
3273 qdebug!("[{self}] TLS connection complete");
3274 if self
3275 .crypto
3276 .tls()
3277 .info()
3278 .map(SecretAgentInfo::alpn)
3279 .is_none()
3280 {
3281 qwarn!("[{self}] No ALPN, closing connection");
3282 // 120 = no_application_protocol
3283 return Err(Error::CryptoAlert(120));
3284 }
3285 if self.role == Role::Server {
3286 // Remove the randomized client CID from the list of acceptable CIDs.
3287 self.cid_manager.remove_odcid();
3288 // Mark the path as validated, if it isn't already.
3289 let path = self.paths.primary().ok_or(Error::NoAvailablePath)?;
3290 path.borrow_mut().set_valid(now);
3291 // Generate a qlog event that the server connection started.
3292 qlog::server_connection_started(&self.qlog, &path, now);
3293 } else {
3294 self.zero_rtt_state = if self
3295 .crypto
3296 .tls()
3297 .info()
3298 .ok_or(Error::InternalError)?
3299 .early_data_accepted()
3300 {
3301 ZeroRttState::AcceptedClient
3302 } else {
3303 self.client_0rtt_rejected(now);
3304 ZeroRttState::Rejected
3305 };
3306 }
3307
3308 // Setting application keys has to occur after 0-RTT rejection.
3309 let pto = self.pto();
3310 self.crypto
3311 .install_application_keys(self.version, now + pto)?;
3312 self.process_tps(now)?;
3313 self.set_state(State::Connected, now);
3314 self.create_resumption_token(now);
3315 self.saved_datagrams.make_available(Epoch::ApplicationData);
3316 self.stats.borrow_mut().resumed = self
3317 .crypto
3318 .tls()
3319 .info()
3320 .ok_or(Error::InternalError)?
3321 .resumed();
3322 if self.role == Role::Server {
3323 self.state_signaling.handshake_done();
3324 self.set_confirmed(now)?;
3325 }
3326 qinfo!("[{self}] Connection established");
3327 Ok(())
3328 }
3329
3330 fn set_state(&mut self, state: State, now: Instant) {
3331 if state > self.state {
3332 qdebug!("[{self}] State change from {:?} -> {state:?}", self.state);
3333 self.state = state.clone();
3334 if self.state.closed() {
3335 self.streams.clear_streams();
3336 }
3337 self.events.connection_state_change(state);
3338 qlog::connection_state_updated(&self.qlog, &self.state, now);
3339 } else if mem::discriminant(&state) != mem::discriminant(&self.state) {
3340 // Only tolerate a regression in state if the new state is closing
3341 // and the connection is already closed.
3342 debug_assert!(matches!(
3343 state,
3344 State::Closing { .. } | State::Draining { .. }
3345 ));
3346 debug_assert!(self.state.closed());
3347 }
3348 }
3349
3350 /// Create a stream.
3351 /// Returns new stream id
3352 ///
3353 /// # Errors
3354 ///
3355 /// `ConnectionState` if the connection stat does not allow to create streams.
3356 /// `StreamLimitError` if we are limited by server's stream concurrence.
3357 pub fn stream_create(&mut self, st: StreamType) -> Res<StreamId> {
3358 // Can't make streams while closing, otherwise rely on the stream limits.
3359 match self.state {
3360 State::Closing { .. } | State::Draining { .. } | State::Closed { .. } => {
3361 return Err(Error::ConnectionState);
3362 }
3363 State::WaitInitial | State::Handshaking => {
3364 if self.role == Role::Client && self.zero_rtt_state != ZeroRttState::Sending {
3365 return Err(Error::ConnectionState);
3366 }
3367 }
3368 // In all other states, trust that the stream limits are correct.
3369 _ => (),
3370 }
3371
3372 self.streams.stream_create(st)
3373 }
3374
3375 /// Set the priority of a stream.
3376 ///
3377 /// # Errors
3378 ///
3379 /// `InvalidStreamId` the stream does not exist.
3380 pub fn stream_priority(
3381 &mut self,
3382 stream_id: StreamId,
3383 transmission: TransmissionPriority,
3384 retransmission: RetransmissionPriority,
3385 ) -> Res<()> {
3386 self.streams
3387 .get_send_stream_mut(stream_id)?
3388 .set_priority(transmission, retransmission);
3389 Ok(())
3390 }
3391
3392 /// Set the `SendOrder` of a stream. Re-enqueues to keep the ordering correct
3393 ///
3394 /// # Errors
3395 /// When the stream does not exist.
3396 pub fn stream_sendorder(
3397 &mut self,
3398 stream_id: StreamId,
3399 sendorder: Option<SendOrder>,
3400 ) -> Res<()> {
3401 self.streams.set_sendorder(stream_id, sendorder)
3402 }
3403
3404 /// Set the Fairness of a stream
3405 ///
3406 /// # Errors
3407 /// When the stream does not exist.
3408 pub fn stream_fairness(&mut self, stream_id: StreamId, fairness: bool) -> Res<()> {
3409 self.streams.set_fairness(stream_id, fairness)
3410 }
3411
3412 /// # Errors
3413 /// When the stream does not exist.
3414 pub fn send_stream_stats(&self, stream_id: StreamId) -> Res<SendStreamStats> {
3415 self.streams
3416 .get_send_stream(stream_id)
3417 .map(SendStream::stats)
3418 }
3419
3420 /// # Errors
3421 /// When the stream does not exist.
3422 pub fn recv_stream_stats(&mut self, stream_id: StreamId) -> Res<RecvStreamStats> {
3423 let stream = self.streams.get_recv_stream_mut(stream_id)?;
3424
3425 Ok(stream.stats())
3426 }
3427
3428 /// Send data on a stream.
3429 /// Returns how many bytes were successfully sent. Could be less
3430 /// than total, based on receiver credit space available, etc.
3431 ///
3432 /// # Errors
3433 ///
3434 /// `InvalidStreamId` the stream does not exist,
3435 /// `InvalidInput` if length of `data` is zero,
3436 /// `FinalSizeError` if the stream has already been closed.
3437 pub fn stream_send(&mut self, stream_id: StreamId, data: &[u8]) -> Res<usize> {
3438 self.streams.get_send_stream_mut(stream_id)?.send(data)
3439 }
3440
3441 /// Send all data or nothing on a stream. May cause `DATA_BLOCKED` or
3442 /// `STREAM_DATA_BLOCKED` frames to be sent.
3443 /// Returns true if data was successfully sent, otherwise false.
3444 ///
3445 /// # Errors
3446 ///
3447 /// `InvalidStreamId` the stream does not exist,
3448 /// `InvalidInput` if length of `data` is zero,
3449 /// `FinalSizeError` if the stream has already been closed.
3450 pub fn stream_send_atomic(&mut self, stream_id: StreamId, data: &[u8]) -> Res<bool> {
3451 let val = self
3452 .streams
3453 .get_send_stream_mut(stream_id)?
3454 .send_atomic(data);
3455 if let Ok(val) = val {
3456 debug_assert!(
3457 val == 0 || val == data.len(),
3458 "Unexpected value {val} when trying to send {} bytes atomically",
3459 data.len()
3460 );
3461 }
3462 val.map(|v| v == data.len())
3463 }
3464
3465 /// Bytes that `stream_send()` is guaranteed to accept for sending.
3466 /// i.e. that will not be blocked by flow credits or send buffer max
3467 /// capacity.
3468 /// # Errors
3469 /// When the stream ID is invalid.
3470 pub fn stream_avail_send_space(&self, stream_id: StreamId) -> Res<usize> {
3471 Ok(self.streams.get_send_stream(stream_id)?.avail())
3472 }
3473
3474 /// Set low watermark for [`ConnectionEvent::SendStreamWritable`] event.
3475 ///
3476 /// Stream emits a [`crate::ConnectionEvent::SendStreamWritable`] event
3477 /// when:
3478 /// - the available sendable bytes increased to or above the watermark
3479 /// - and was previously below the watermark.
3480 ///
3481 /// Default value is `1`. In other words
3482 /// [`crate::ConnectionEvent::SendStreamWritable`] is emitted whenever the
3483 /// available sendable bytes was previously at `0` and now increased to `1`
3484 /// or more.
3485 ///
3486 /// Use this when your protocol needs at least `watermark` amount of available
3487 /// sendable bytes to make progress.
3488 ///
3489 /// # Errors
3490 /// When the stream ID is invalid.
3491 pub fn stream_set_writable_event_low_watermark(
3492 &mut self,
3493 stream_id: StreamId,
3494 watermark: NonZeroUsize,
3495 ) -> Res<()> {
3496 self.streams
3497 .get_send_stream_mut(stream_id)?
3498 .set_writable_event_low_watermark(watermark);
3499 Ok(())
3500 }
3501
3502 /// Close the stream. Enqueued data will be sent.
3503 /// # Errors
3504 /// When the stream ID is invalid.
3505 pub fn stream_close_send(&mut self, stream_id: StreamId) -> Res<()> {
3506 self.streams.get_send_stream_mut(stream_id)?.close();
3507 Ok(())
3508 }
3509
3510 /// Abandon transmission of in-flight and future stream data.
3511 /// # Errors
3512 /// When the stream ID is invalid.
3513 pub fn stream_reset_send(&mut self, stream_id: StreamId, err: AppError) -> Res<()> {
3514 self.streams.get_send_stream_mut(stream_id)?.reset(err);
3515 Ok(())
3516 }
3517
3518 /// Read buffered data from stream. bool says whether read bytes includes
3519 /// the final data on stream.
3520 ///
3521 /// # Errors
3522 ///
3523 /// `InvalidStreamId` if the stream does not exist.
3524 /// `NoMoreData` if data and fin bit were previously read by the application.
3525 pub fn stream_recv(&mut self, stream_id: StreamId, data: &mut [u8]) -> Res<(usize, bool)> {
3526 let stream = self.streams.get_recv_stream_mut(stream_id)?;
3527
3528 let rb = stream.read(data)?;
3529 Ok(rb)
3530 }
3531
3532 /// Application is no longer interested in this stream.
3533 /// # Errors
3534 /// When the stream ID is invalid.
3535 pub fn stream_stop_sending(&mut self, stream_id: StreamId, err: AppError) -> Res<()> {
3536 let stream = self.streams.get_recv_stream_mut(stream_id)?;
3537
3538 stream.stop_sending(err);
3539 Ok(())
3540 }
3541
3542 /// Increases `max_stream_data` for a `stream_id`.
3543 ///
3544 /// # Errors
3545 ///
3546 /// Returns `InvalidStreamId` if a stream does not exist or the receiving
3547 /// side is closed.
3548 pub fn set_stream_max_data(&mut self, stream_id: StreamId, max_data: u64) -> Res<()> {
3549 let stream = self.streams.get_recv_stream_mut(stream_id)?;
3550
3551 stream.set_stream_max_data(max_data);
3552 Ok(())
3553 }
3554
3555 /// Mark a receive stream as being important enough to keep the connection alive
3556 /// (if `keep` is `true`) or no longer important (if `keep` is `false`). If any
3557 /// stream is marked this way, PING frames will be used to keep the connection
3558 /// alive, even when there is no activity.
3559 ///
3560 /// # Errors
3561 ///
3562 /// Returns `InvalidStreamId` if a stream does not exist or the receiving
3563 /// side is closed.
3564 pub fn stream_keep_alive(&mut self, stream_id: StreamId, keep: bool) -> Res<()> {
3565 self.streams.keep_alive(stream_id, keep)
3566 }
3567
3568 #[must_use]
3569 pub const fn remote_datagram_size(&self) -> u64 {
3570 self.quic_datagrams.remote_datagram_size()
3571 }
3572
3573 /// Returns the current max size of a datagram that can fit into a packet.
3574 /// The value will change over time depending on the encoded size of the
3575 /// packet number, ack frames, etc.
3576 ///
3577 /// # Errors
3578 /// The function returns `NotAvailable` if datagrams are not enabled.
3579 /// # Panics
3580 /// Basically never, because that unwrap won't fail.
3581 pub fn max_datagram_size(&self) -> Res<u64> {
3582 let max_dgram_size = self.quic_datagrams.remote_datagram_size();
3583 if max_dgram_size == 0 {
3584 return Err(Error::NotAvailable);
3585 }
3586 let version = self.version();
3587 let Some((epoch, tx)) = self
3588 .crypto
3589 .states()
3590 .select_tx(self.version, PacketNumberSpace::ApplicationData)
3591 else {
3592 return Err(Error::NotAvailable);
3593 };
3594 let path = self.paths.primary().ok_or(Error::NotAvailable)?;
3595 let mtu = path.borrow().plpmtu();
3596 let encoder = Encoder::default();
3597
3598 let (_, mut builder) = Self::build_packet_header(
3599 &path.borrow(),
3600 epoch,
3601 encoder,
3602 tx,
3603 &self.address_validation,
3604 version,
3605 false,
3606 );
3607 _ = Self::add_packet_number(
3608 &mut builder,
3609 tx,
3610 self.loss_recovery
3611 .largest_acknowledged_pn(PacketNumberSpace::ApplicationData),
3612 );
3613
3614 let data_len_possible =
3615 u64::try_from(mtu.saturating_sub(tx.expansion() + builder.len() + 1))?;
3616 Ok(min(data_len_possible, max_dgram_size))
3617 }
3618
3619 /// Queue a datagram for sending.
3620 ///
3621 /// # Errors
3622 ///
3623 /// The function returns `TooMuchData` if the supply buffer is bigger than
3624 /// the allowed remote datagram size. The function does not check if the
3625 /// datagram can fit into a packet (i.e. MTU limit). This is checked during
3626 /// creation of an actual packet and the datagram will be dropped if it does
3627 /// not fit into the packet. The app is encourage to use `max_datagram_size`
3628 /// to check the estimated max datagram size and to use smaller datagrams.
3629 /// `max_datagram_size` is just a current estimate and will change over
3630 /// time depending on the encoded size of the packet number, ack frames, etc.
3631 pub fn send_datagram(&mut self, buf: Vec<u8>, id: impl Into<DatagramTracking>) -> Res<()> {
3632 self.quic_datagrams
3633 .add_datagram(buf, id.into(), &mut self.stats.borrow_mut())
3634 }
3635
3636 /// Return the PLMTU of the primary path.
3637 ///
3638 /// # Panics
3639 ///
3640 /// The function panics if there is no primary path. (Should be fine for test usage.)
3641 #[cfg(test)]
3642 #[must_use]
3643 pub fn plpmtu(&self) -> usize {
3644 self.paths.primary().unwrap().borrow().plpmtu()
3645 }
3646
3647 fn log_packet(&self, meta: packet::MetaData, now: Instant) {
3648 if log::log_enabled!(log::Level::Debug) {
3649 let mut s = String::new();
3650 let mut d = Decoder::from(meta.payload());
3651 while d.remaining() > 0 {
3652 let Ok(f) = Frame::decode(&mut d) else {
3653 s.push_str(" [broken]...");
3654 break;
3655 };
3656 let x = f.dump();
3657 if !x.is_empty() {
3658 _ = write!(&mut s, "\n {} {}", meta.direction(), &x);
3659 }
3660 }
3661 qdebug!("[{self}] {meta}{s}");
3662 }
3663
3664 qlog::packet_io(&self.qlog, meta, now);
3665 }
3666 }
3667
3668 impl EventProvider for Connection {
3669 type Event = ConnectionEvent;
3670
3671 /// Return true if there are outstanding events.
3672 fn has_events(&self) -> bool {
3673 self.events.has_events()
3674 }
3675
3676 /// Get events that indicate state changes on the connection. This method
3677 /// correctly handles cases where handling one event can obsolete
3678 /// previously-queued events, or cause new events to be generated.
3679 fn next_event(&mut self) -> Option<Self::Event> {
3680 self.events.next_event()
3681 }
3682 }
3683
3684 impl Display for Connection {
3685 fn fmt(&self, f: &mut Formatter) -> fmt::Result {
3686 write!(f, "{:?} ", self.role)?;
3687 if let Some(cid) = self.odcid() {
3688 Display::fmt(&cid, f)
3689 } else {
3690 write!(f, "...")
3691 }
3692 }
3693 }
3694
3695 #[cfg(test)]
3696 mod tests;