Debian Codegraph @

third_party/rust/neqo-transport/src/crypto.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 use std::{
8 cell::RefCell,
9 cmp::{max, min},
10 fmt::{self, Display, Formatter},
11 mem,
12 ops::{Index, IndexMut, Range},
13 rc::Rc,
14 time::Instant,
15 };
16
17 use enum_map::EnumMap;
18 use neqo_common::{hex, hex_snip_middle, qdebug, qinfo, qtrace, Encoder, Role};
19 pub use neqo_crypto::Epoch;
20 use neqo_crypto::{
21 hkdf, hp::HpKey, Aead, Agent, AntiReplay, Cipher, Error as CryptoError, HandshakeState,
22 PrivateKey, PublicKey, Record, RecordList, ResumptionToken, SymKey, ZeroRttChecker,
23 TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_CT_HANDSHAKE,
24 TLS_GRP_EC_SECP256R1, TLS_GRP_EC_SECP384R1, TLS_GRP_EC_SECP521R1, TLS_GRP_EC_X25519,
25 TLS_GRP_KEM_MLKEM768X25519, TLS_VERSION_1_3,
26 };
27
28 use crate::{
29 cid::ConnectionIdRef,
30 frame::FrameType,
31 packet::{PacketBuilder, PacketNumber},
32 recovery::RecoveryToken,
33 recv_stream::RxStreamOrderer,
34 send_stream::TxBuffer,
35 sni::find_sni,
36 stats::FrameStats,
37 tparams::{TpZeroRttChecker, TransportParameters, TransportParametersHandler},
38 tracking::PacketNumberSpace,
39 version::Version,
40 ConnectionParameters, Error, Res,
41 };
42
43 /// The number of invocations remaining on a write cipher before we try
44 /// to update keys. This has to be much smaller than the number returned
45 /// by `CryptoDxState::limit` or updates will happen too often. As we don't
46 /// need to ask permission to update, this can be quite small.
47 pub const UPDATE_WRITE_KEYS_AT: PacketNumber = 100;
48
49 // This is a testing kludge that allows for overwriting the number of
50 // invocations of the next cipher to operate. With this, it is possible
51 // to test what happens when the number of invocations reaches 0, or
52 // when it hits `UPDATE_WRITE_KEYS_AT` and an automatic update should occur.
53 // This is a little crude, but it saves a lot of plumbing.
54 #[cfg(test)]
55 thread_local!(pub static OVERWRITE_INVOCATIONS: RefCell<Option<PacketNumber>> = RefCell::default());
56
57 #[derive(Debug)]
58 pub struct Crypto {
59 version: Version,
60 protocols: Vec<String>,
61 tls: Agent,
62 streams: CryptoStreams,
63 states: CryptoStates,
64 }
65
66 type TpHandler = Rc<RefCell<TransportParametersHandler>>;
67
68 impl Crypto {
69 pub fn new(
70 version: Version,
71 conn_params: &ConnectionParameters,
72 mut agent: Agent,
73 protocols: Vec<String>,
74 tphandler: TpHandler,
75 ) -> Res<Self> {
76 agent.set_version_range(TLS_VERSION_1_3, TLS_VERSION_1_3)?;
77 agent.set_ciphers(&[
78 TLS_AES_128_GCM_SHA256,
79 TLS_AES_256_GCM_SHA384,
80 TLS_CHACHA20_POLY1305_SHA256,
81 ])?;
82 agent.set_groups(if conn_params.mlkem_enabled() {
83 &[
84 TLS_GRP_KEM_MLKEM768X25519,
85 TLS_GRP_EC_X25519,
86 TLS_GRP_EC_SECP256R1,
87 TLS_GRP_EC_SECP384R1,
88 TLS_GRP_EC_SECP521R1,
89 ]
90 } else {
91 &[
92 TLS_GRP_EC_X25519,
93 TLS_GRP_EC_SECP256R1,
94 TLS_GRP_EC_SECP384R1,
95 TLS_GRP_EC_SECP521R1,
96 ]
97 })?;
98 if let Agent::Client(c) = &mut agent {
99 // Configure clients to send additional key shares to reduce the rate of HRRs
100 // when enabling MLKEM.
101 c.send_additional_key_shares(usize::from(conn_params.mlkem_enabled()))?;
102
103 // Always enable 0-RTT on the client, but the server needs
104 // more configuration passed to server_enable_0rtt.
105 c.enable_0rtt()?;
106 }
107 agent.set_alpn(&protocols)?;
108 agent.disable_end_of_early_data()?;
109 let extension = match version {
110 Version::Version2 | Version::Version1 => 0x39,
111 #[cfg(feature = "draft-29")]
112 Version::Draft29 => 0xffa5,
113 };
114 agent.extension_handler(extension, tphandler)?;
115 Ok(Self {
116 version,
117 protocols,
118 tls: agent,
119 streams: CryptoStreams::default(),
120 states: CryptoStates::default(),
121 })
122 }
123
124 /// Get the name of the server. (Only works for the client currently).
125 pub fn server_name(&self) -> Option<&str> {
126 if let Agent::Client(c) = &self.tls {
127 Some(c.server_name())
128 } else {
129 None
130 }
131 }
132
133 /// Get the set of enabled protocols.
134 pub fn protocols(&self) -> &[String] {
135 &self.protocols
136 }
137
138 pub fn server_enable_0rtt(
139 &mut self,
140 tphandler: TpHandler,
141 anti_replay: &AntiReplay,
142 zero_rtt_checker: impl ZeroRttChecker + 'static,
143 ) -> Res<()> {
144 if let Agent::Server(s) = &mut self.tls {
145 Ok(s.enable_0rtt(
146 anti_replay,
147 0xffff_ffff,
148 TpZeroRttChecker::wrap(tphandler, zero_rtt_checker),
149 )?)
150 } else {
151 panic!("not a server");
152 }
153 }
154
155 pub fn server_enable_ech(
156 &mut self,
157 config: u8,
158 public_name: &str,
159 sk: &PrivateKey,
160 pk: &PublicKey,
161 ) -> Res<()> {
162 if let Agent::Server(s) = &mut self.tls {
163 s.enable_ech(config, public_name, sk, pk)?;
164 Ok(())
165 } else {
166 panic!("not a client");
167 }
168 }
169
170 pub fn client_enable_ech(&mut self, ech_config_list: impl AsRef<[u8]>) -> Res<()> {
171 if let Agent::Client(c) = &mut self.tls {
172 c.enable_ech(ech_config_list)?;
173 Ok(())
174 } else {
175 panic!("not a client");
176 }
177 }
178
179 /// Get the active ECH configuration, which is empty if ECH is disabled.
180 pub fn ech_config(&self) -> &[u8] {
181 self.tls.ech_config()
182 }
183
184 pub fn handshake(
185 &mut self,
186 now: Instant,
187 space: PacketNumberSpace,
188 data: Option<&[u8]>,
189 ) -> Res<&HandshakeState> {
190 let input = data.map(|d| {
191 qtrace!("Handshake record received {d:0x?} ");
192 Record {
193 ct: TLS_CT_HANDSHAKE,
194 epoch: space.into(),
195 data: d.to_vec(),
196 }
197 });
198
199 match self.tls.handshake_raw(now, input) {
200 Ok(output) => {
201 self.buffer_records(output)?;
202 Ok(self.tls.state())
203 }
204 Err(CryptoError::EchRetry(v)) => Err(Error::EchRetry(v)),
205 Err(e) => {
206 qinfo!("Handshake failed {e:?}");
207 Err(self
208 .tls
209 .alert()
210 .map_or(Error::CryptoError(e), |a| Error::CryptoAlert(*a)))
211 }
212 }
213 }
214
215 /// Enable 0-RTT and return `true` if it is enabled successfully.
216 pub fn enable_0rtt(&mut self, version: Version, role: Role) -> Res<bool> {
217 let info = self.tls.preinfo()?;
218 // `info.early_data()` returns false for a server,
219 // so use `early_data_cipher()` to tell if 0-RTT is enabled.
220 let cipher = info.early_data_cipher();
221 if cipher.is_none() {
222 return Ok(false);
223 }
224 let (dir, secret) = match role {
225 Role::Client => (
226 CryptoDxDirection::Write,
227 self.tls.write_secret(Epoch::ZeroRtt),
228 ),
229 Role::Server => (
230 CryptoDxDirection::Read,
231 self.tls.read_secret(Epoch::ZeroRtt),
232 ),
233 };
234 let secret = secret.ok_or(Error::InternalError)?;
235 self.states
236 .set_0rtt_keys(version, dir, &secret, cipher.ok_or(Error::InternalError)?)?;
237 Ok(true)
238 }
239
240 /// Lock in a compatible upgrade.
241 pub fn confirm_version(&mut self, confirmed: Version) -> Res<()> {
242 self.states.confirm_version(self.version, confirmed)?;
243 self.version = confirmed;
244 Ok(())
245 }
246
247 /// Returns true if new handshake keys were installed.
248 pub fn install_keys(&mut self, role: Role) -> Res<bool> {
249 if self.tls.state().is_final() {
250 Ok(false)
251 } else {
252 let installed_hs = self.install_handshake_keys()?;
253 if role == Role::Server {
254 self.maybe_install_application_write_key(self.version)?;
255 }
256 Ok(installed_hs)
257 }
258 }
259
260 fn install_handshake_keys(&mut self) -> Res<bool> {
261 qtrace!("[{self}] Attempt to install handshake keys");
262 let Some(write_secret) = self.tls.write_secret(Epoch::Handshake) else {
263 // No keys is fine.
264 return Ok(false);
265 };
266 let read_secret = self
267 .tls
268 .read_secret(Epoch::Handshake)
269 .ok_or(Error::InternalError)?;
270 let cipher = match self.tls.info() {
271 None => self.tls.preinfo()?.cipher_suite(),
272 Some(info) => Some(info.cipher_suite()),
273 }
274 .ok_or(Error::InternalError)?;
275 self.states
276 .set_handshake_keys(self.version, &write_secret, &read_secret, cipher)?;
277 qdebug!("[{self}] Handshake keys installed");
278 Ok(true)
279 }
280
281 fn maybe_install_application_write_key(&mut self, version: Version) -> Res<()> {
282 qtrace!("[{self}] Attempt to install application write key");
283 if let Some(secret) = self.tls.write_secret(Epoch::ApplicationData) {
284 self.states.set_application_write_key(version, &secret)?;
285 qdebug!("[{self}] Application write key installed");
286 }
287 Ok(())
288 }
289
290 pub fn install_application_keys(&mut self, version: Version, expire_0rtt: Instant) -> Res<()> {
291 self.maybe_install_application_write_key(version)?;
292 // The write key might have been installed earlier, but it should
293 // always be installed now.
294 debug_assert!(self.states.app_write.is_some());
295 let read_secret = self
296 .tls
297 .read_secret(Epoch::ApplicationData)
298 .ok_or(Error::InternalError)?;
299 self.states
300 .set_application_read_key(version, &read_secret, expire_0rtt)?;
301 qdebug!("[{self}] application read keys installed");
302 Ok(())
303 }
304
305 /// Buffer crypto records for sending.
306 pub fn buffer_records(&mut self, records: RecordList) -> Res<()> {
307 for r in records {
308 if r.ct != TLS_CT_HANDSHAKE {
309 return Err(Error::ProtocolViolation);
310 }
311 qtrace!("[{self}] Adding CRYPTO data {r:?}");
312 self.streams.send(r.epoch.into(), &r.data)?;
313 }
314 Ok(())
315 }
316
317 pub fn write_frame(
318 &mut self,
319 space: PacketNumberSpace,
320 sni_slicing: bool,
321 builder: &mut PacketBuilder,
322 tokens: &mut Vec<RecoveryToken>,
323 stats: &mut FrameStats,
324 ) {
325 self.streams
326 .write_frame(space, sni_slicing, builder, tokens, stats);
327 }
328
329 pub fn acked(&mut self, token: &CryptoRecoveryToken) {
330 qdebug!(
331 "Acked crypto frame space={} offset={} length={}",
332 token.space,
333 token.offset,
334 token.length
335 );
336 self.streams.acked(token);
337 }
338
339 pub fn lost(&mut self, token: &CryptoRecoveryToken) {
340 qinfo!(
341 "Lost crypto frame space={} offset={} length={}",
342 token.space,
343 token.offset,
344 token.length
345 );
346 self.streams.lost(token);
347 }
348
349 /// Mark any outstanding frames in the indicated space as "lost" so
350 /// that they can be sent again.
351 pub fn resend_unacked(&mut self, space: PacketNumberSpace) {
352 self.streams.resend_unacked(space);
353 }
354
355 /// Discard state for a packet number space and return true
356 /// if something was discarded.
357 pub fn discard(&mut self, space: PacketNumberSpace) -> bool {
358 self.streams.discard(space);
359 self.states.discard(space)
360 }
361
362 pub fn create_resumption_token(
363 &mut self,
364 new_token: Option<&[u8]>,
365 tps: &TransportParameters,
366 version: Version,
367 rtt: u64,
368 ) -> Option<ResumptionToken> {
369 if let Agent::Client(ref mut c) = self.tls {
370 c.resumption_token().as_ref().map(|t| {
371 qtrace!("TLS token {}", hex(t.as_ref()));
372 let mut enc = Encoder::default();
373 enc.encode_uint(4, version.wire_version());
374 enc.encode_varint(rtt);
375 enc.encode_vvec_with(|enc_inner| {
376 tps.encode(enc_inner);
377 });
378 enc.encode_vvec(new_token.unwrap_or(&[]));
379 enc.encode(t.as_ref());
380 qdebug!("resumption token {}", hex_snip_middle(enc.as_ref()));
381 ResumptionToken::new(enc.into(), t.expiration_time())
382 })
383 } else {
384 unreachable!("It is a server");
385 }
386 }
387
388 pub fn has_resumption_token(&self) -> bool {
389 if let Agent::Client(c) = &self.tls {
390 c.has_resumption_token()
391 } else {
392 unreachable!("It is a server");
393 }
394 }
395
396 #[must_use]
397 pub fn tls_mut(&mut self) -> &mut Agent {
398 &mut self.tls
399 }
400
401 #[must_use]
402 pub const fn tls(&self) -> &Agent {
403 &self.tls
404 }
405
406 #[must_use]
407 pub const fn streams(&self) -> &CryptoStreams {
408 &self.streams
409 }
410
411 #[must_use]
412 pub fn streams_mut(&mut self) -> &mut CryptoStreams {
413 &mut self.streams
414 }
415
416 #[must_use]
417 pub const fn states(&self) -> &CryptoStates {
418 &self.states
419 }
420
421 #[must_use]
422 pub fn states_mut(&mut self) -> &mut CryptoStates {
423 &mut self.states
424 }
425 }
426
427 impl Display for Crypto {
428 fn fmt(&self, f: &mut Formatter) -> fmt::Result {
429 write!(f, "Crypto")
430 }
431 }
432
433 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
434 pub enum CryptoDxDirection {
435 Read,
436 Write,
437 }
438
439 #[derive(Debug)]
440 pub struct CryptoDxState {
441 /// The QUIC version.
442 version: Version,
443 /// Whether packets protected with this state will be read or written.
444 direction: CryptoDxDirection,
445 /// The epoch of this crypto state. This initially tracks TLS epochs
446 /// via DTLS: 0 = initial, 1 = 0-RTT, 2 = handshake, 3 = application.
447 /// But we don't need to keep that, and QUIC isn't limited in how
448 /// many times keys can be updated, so we don't use `u16` for this.
449 epoch: usize,
450 aead: Aead,
451 hpkey: HpKey,
452 /// This tracks the range of packet numbers that have been seen. This allows
453 /// for verifying that packet numbers before a key update are strictly lower
454 /// than packet numbers after a key update.
455 used_pn: Range<PacketNumber>,
456 /// This is the minimum packet number that is allowed.
457 min_pn: PacketNumber,
458 /// The total number of operations that are remaining before the keys
459 /// become exhausted and can't be used any more.
460 invocations: PacketNumber,
461 /// The basis of the invocation limits in `invocations`.
462 largest_packet_len: usize,
463 }
464
465 const INITIAL_LARGEST_PACKET_LEN: usize = 1 << 11; // 2048
466
467 impl CryptoDxState {
468 pub fn new(
469 version: Version,
470 direction: CryptoDxDirection,
471 epoch: Epoch,
472 secret: &SymKey,
473 cipher: Cipher,
474 ) -> Res<Self> {
475 qdebug!("Making {direction:?} {epoch:?} CryptoDxState, v={version:?} cipher={cipher}",);
476 let hplabel = String::from(version.label_prefix()) + "hp";
477 Ok(Self {
478 version,
479 direction,
480 epoch: usize::from(epoch),
481 aead: Aead::new(TLS_VERSION_1_3, cipher, secret, version.label_prefix())?,
482 hpkey: HpKey::extract(TLS_VERSION_1_3, cipher, secret, &hplabel)?,
483 used_pn: 0..0,
484 min_pn: 0,
485 invocations: Self::limit(direction, cipher),
486 largest_packet_len: INITIAL_LARGEST_PACKET_LEN,
487 })
488 }
489
490 pub fn new_initial(
491 version: Version,
492 direction: CryptoDxDirection,
493 label: &str,
494 dcid: &[u8],
495 ) -> Res<Self> {
496 qtrace!("new_initial {version:?} {}", ConnectionIdRef::from(dcid));
497 let salt = version.initial_salt();
498 let cipher = TLS_AES_128_GCM_SHA256;
499 let initial_secret = hkdf::extract(
500 TLS_VERSION_1_3,
501 cipher,
502 Some(&hkdf::import_key(TLS_VERSION_1_3, salt)?),
503 &hkdf::import_key(TLS_VERSION_1_3, dcid)?,
504 )?;
505
506 let secret = hkdf::expand_label(TLS_VERSION_1_3, cipher, &initial_secret, &[], label)?;
507
508 Self::new(version, direction, Epoch::Initial, &secret, cipher)
509 }
510
511 /// Determine the confidentiality and integrity limits for the cipher.
512 fn limit(direction: CryptoDxDirection, cipher: Cipher) -> PacketNumber {
513 match direction {
514 // This uses the smaller limits for 2^16 byte packets
515 // as we don't control incoming packet size.
516 CryptoDxDirection::Read => match cipher {
517 TLS_AES_128_GCM_SHA256 => 1 << 52,
518 TLS_AES_256_GCM_SHA384 => PacketNumber::MAX,
519 TLS_CHACHA20_POLY1305_SHA256 => 1 << 36,
520 _ => unreachable!(),
521 },
522 // This uses the larger limits for 2^11 byte packets.
523 CryptoDxDirection::Write => match cipher {
524 TLS_AES_128_GCM_SHA256 | TLS_AES_256_GCM_SHA384 => 1 << 28,
525 TLS_CHACHA20_POLY1305_SHA256 => PacketNumber::MAX,
526 _ => unreachable!(),
527 },
528 }
529 }
530
531 fn invoked(&mut self) -> Res<()> {
532 #[cfg(test)]
533 OVERWRITE_INVOCATIONS.with(|v| {
534 if let Some(i) = v.borrow_mut().take() {
535 log::warn!("Setting {:?} invocations to {}", self.direction, i);
536 self.invocations = i;
537 }
538 });
539 self.invocations = self
540 .invocations
541 .checked_sub(1)
542 .ok_or(Error::KeysExhausted)?;
543 Ok(())
544 }
545
546 /// Determine whether we should initiate a key update.
547 pub fn should_update(&self) -> bool {
548 // There is no point in updating read keys as the limit is global.
549 debug_assert_eq!(self.direction, CryptoDxDirection::Write);
550 self.invocations <= UPDATE_WRITE_KEYS_AT
551 }
552
553 pub fn next(&self, next_secret: &SymKey, cipher: Cipher) -> Res<Self> {
554 let pn = self.next_pn();
555 // We count invocations of each write key just for that key, but all
556 // attempts to invocations to read count toward a single limit.
557 // This doesn't count use of Handshake keys.
558 let invocations = if self.direction == CryptoDxDirection::Read {
559 self.invocations
560 } else {
561 Self::limit(CryptoDxDirection::Write, cipher)
562 };
563 Ok(Self {
564 version: self.version,
565 direction: self.direction,
566 epoch: self.epoch + 1,
567 aead: Aead::new(
568 TLS_VERSION_1_3,
569 cipher,
570 next_secret,
571 self.version.label_prefix(),
572 )?,
573 hpkey: self.hpkey.clone(),
574 used_pn: pn..pn,
575 min_pn: pn,
576 invocations,
577 largest_packet_len: INITIAL_LARGEST_PACKET_LEN,
578 })
579 }
580
581 #[must_use]
582 pub const fn version(&self) -> Version {
583 self.version
584 }
585
586 #[must_use]
587 pub const fn key_phase(&self) -> bool {
588 // Epoch 3 => 0, 4 => 1, 5 => 0, 6 => 1, ...
589 self.epoch & 1 != 1
590 }
591
592 /// This is a continuation of a previous, so adjust the range accordingly.
593 /// Fail if the two ranges overlap. Do nothing if the directions don't match.
594 pub fn continuation(&mut self, prev: &Self) -> Res<()> {
595 debug_assert_eq!(self.direction, prev.direction);
596 let next = prev.next_pn();
597 self.min_pn = next;
598 if self.used_pn.is_empty() {
599 self.used_pn = next..next;
600 Ok(())
601 } else if prev.used_pn.end > self.used_pn.start {
602 qdebug!(
603 "[{self}] Found packet with too new packet number {} > {}, compared to {prev}",
604 self.used_pn.start,
605 prev.used_pn.end,
606 );
607 Err(Error::PacketNumberOverlap)
608 } else {
609 self.used_pn.start = next;
610 Ok(())
611 }
612 }
613
614 /// Mark a packet number as used. If this is too low, reject it.
615 /// Note that this won't catch a value that is too high if packets protected with
616 /// old keys are received after a key update. That needs to be caught elsewhere.
617 pub fn used(&mut self, pn: PacketNumber) -> Res<()> {
618 if pn < self.min_pn {
619 qdebug!(
620 "[{self}] Found packet with too old packet number: {pn} < {}",
621 self.min_pn
622 );
623 return Err(Error::PacketNumberOverlap);
624 }
625 if self.used_pn.start == self.used_pn.end {
626 self.used_pn.start = pn;
627 }
628 self.used_pn.end = max(pn + 1, self.used_pn.end);
629 Ok(())
630 }
631
632 #[must_use]
633 pub fn needs_update(&self) -> bool {
634 // Only initiate a key update if we have processed exactly one packet
635 // and we are in an epoch greater than 3.
636 self.used_pn.start + 1 == self.used_pn.end
637 && self.epoch > usize::from(Epoch::ApplicationData)
638 }
639
640 #[must_use]
641 pub fn can_update(&self, largest_acknowledged: Option<PacketNumber>) -> bool {
642 largest_acknowledged.map_or_else(
643 || self.epoch == usize::from(Epoch::ApplicationData),
644 |la| self.used_pn.contains(&la),
645 )
646 }
647
648 pub fn compute_mask(&self, sample: &[u8]) -> Res<[u8; HpKey::SAMPLE_SIZE]> {
649 let mask = self.hpkey.mask(sample)?;
650 qtrace!("[{self}] HP sample={} mask={}", hex(sample), hex(mask));
651 Ok(mask)
652 }
653
654 #[must_use]
655 pub const fn next_pn(&self) -> PacketNumber {
656 self.used_pn.end
657 }
658
659 pub fn encrypt<'a>(
660 &mut self,
661 pn: PacketNumber,
662 hdr: Range<usize>,
663 data: &'a mut [u8],
664 ) -> Res<&'a mut [u8]> {
665 debug_assert_eq!(self.direction, CryptoDxDirection::Write);
666 qtrace!(
667 "[{self}] encrypt_in_place pn={pn} hdr={} body={}",
668 hex(data[hdr.clone()].as_ref()),
669 hex(data[hdr.end..].as_ref())
670 );
671
672 // The numbers in `Self::limit` assume a maximum packet size of `LIMIT`.
673 // Adjust them as we encounter larger packets.
674 let body_len = data.len() - hdr.len() - self.aead.expansion();
675 debug_assert!(body_len <= u16::MAX.into());
676 if body_len > self.largest_packet_len {
677 let new_bits = usize::leading_zeros(self.largest_packet_len - 1)
678 - usize::leading_zeros(body_len - 1);
679 self.invocations >>= new_bits;
680 self.largest_packet_len = body_len;
681 }
682 self.invoked()?;
683
684 let (prev, data) = data.split_at_mut(hdr.end);
685 // `prev` may have already-encrypted packets this one is being coalesced with.
686 // Use only the actual current header for AAD.
687 let data = self.aead.encrypt_in_place(pn, &prev[hdr], data)?;
688
689 qtrace!("[{self}] encrypt ct={}", hex(&data));
690 debug_assert_eq!(pn, self.next_pn());
691 self.used(pn)?;
692 Ok(data)
693 }
694
695 #[must_use]
696 pub const fn expansion(&self) -> usize {
697 self.aead.expansion()
698 }
699
700 pub fn decrypt<'a>(
701 &mut self,
702 pn: PacketNumber,
703 hdr: Range<usize>,
704 data: &'a mut [u8],
705 ) -> Res<&'a mut [u8]> {
706 debug_assert_eq!(self.direction, CryptoDxDirection::Read);
707 qtrace!(
708 "[{self}] decrypt_in_place pn={pn} hdr={} body={}",
709 hex(data[hdr.clone()].as_ref()),
710 hex(data[hdr.end..].as_ref())
711 );
712 self.invoked()?;
713 let (hdr, data) = data.split_at_mut(hdr.end);
714 let data = self.aead.decrypt_in_place(pn, hdr, data)?;
715 self.used(pn)?;
716 Ok(data)
717 }
718
719 #[cfg(not(feature = "disable-encryption"))]
720 #[cfg(test)]
721 pub(crate) fn test_default() -> Self {
722 // This matches the value in packet.rs
723 const CLIENT_CID: &[u8] = &[0x83, 0x94, 0xc8, 0xf0, 0x3e, 0x51, 0x57, 0x08];
724 Self::new_initial(
725 Version::default(),
726 CryptoDxDirection::Write,
727 "server in",
728 CLIENT_CID,
729 )
730 .unwrap()
731 }
732
733 /// Get the amount of extra padding packets protected with this profile need.
734 /// This is the difference between the size of the header protection sample
735 /// and the AEAD expansion.
736 pub const fn extra_padding(&self) -> usize {
737 HpKey::SAMPLE_SIZE.saturating_sub(self.aead.expansion())
738 }
739 }
740
741 impl Display for CryptoDxState {
742 fn fmt(&self, f: &mut Formatter) -> fmt::Result {
743 write!(f, "epoch {} {:?}", self.epoch, self.direction)
744 }
745 }
746
747 #[derive(Debug)]
748 pub struct CryptoState {
749 tx: CryptoDxState,
750 rx: CryptoDxState,
751 }
752
753 impl Index<CryptoDxDirection> for CryptoState {
754 type Output = CryptoDxState;
755
756 fn index(&self, index: CryptoDxDirection) -> &Self::Output {
757 match index {
758 CryptoDxDirection::Read => &self.rx,
759 CryptoDxDirection::Write => &self.tx,
760 }
761 }
762 }
763
764 impl IndexMut<CryptoDxDirection> for CryptoState {
765 fn index_mut(&mut self, index: CryptoDxDirection) -> &mut Self::Output {
766 match index {
767 CryptoDxDirection::Read => &mut self.rx,
768 CryptoDxDirection::Write => &mut self.tx,
769 }
770 }
771 }
772
773 /// `CryptoDxAppData` wraps the state necessary for one direction of application data keys.
774 /// This includes the secret needed to generate the next set of keys.
775 #[derive(Debug)]
776 pub struct CryptoDxAppData {
777 dx: CryptoDxState,
778 cipher: Cipher,
779 // Not the secret used to create `self.dx`, but the one needed for the next iteration.
780 next_secret: SymKey,
781 }
782
783 impl CryptoDxAppData {
784 pub fn new(
785 version: Version,
786 dir: CryptoDxDirection,
787 secret: &SymKey,
788 cipher: Cipher,
789 ) -> Res<Self> {
790 Ok(Self {
791 dx: CryptoDxState::new(version, dir, Epoch::ApplicationData, secret, cipher)?,
792 cipher,
793 next_secret: Self::update_secret(cipher, secret)?,
794 })
795 }
796
797 fn update_secret(cipher: Cipher, secret: &SymKey) -> Res<SymKey> {
798 let next = hkdf::expand_label(TLS_VERSION_1_3, cipher, secret, &[], "quic ku")?;
799 Ok(next)
800 }
801
802 pub fn next(&self) -> Res<Self> {
803 if self.dx.epoch == usize::MAX {
804 // Guard against too many key updates.
805 return Err(Error::KeysExhausted);
806 }
807 let next_secret = Self::update_secret(self.cipher, &self.next_secret)?;
808 Ok(Self {
809 dx: self.dx.next(&self.next_secret, self.cipher)?,
810 cipher: self.cipher,
811 next_secret,
812 })
813 }
814
815 pub const fn epoch(&self) -> usize {
816 self.dx.epoch
817 }
818 }
819
820 /// All of the keying material needed for a connection.
821 ///
822 /// Note that the methods on this struct take a version but those are only ever
823 /// used for Initial keys; a version has been selected at the time we need to
824 /// get other keys, so those have fixed versions.
825 #[derive(Debug, Default)]
826 pub struct CryptoStates {
827 initials: EnumMap<Version, Option<CryptoState>>,
828 handshake: Option<CryptoState>,
829 zero_rtt: Option<CryptoDxState>, // One direction only!
830 cipher: Cipher,
831 app_write: Option<CryptoDxAppData>,
832 app_read: Option<CryptoDxAppData>,
833 app_read_next: Option<CryptoDxAppData>,
834 // If this is set, then we have noticed a genuine update.
835 // Once this time passes, we should switch in new keys.
836 read_update_time: Option<Instant>,
837 }
838
839 impl CryptoStates {
840 fn initials_is_empty(&self) -> bool {
841 self.initials.values().flatten().count() == 0
842 }
843
844 /// Select a `CryptoDxState` and `CryptoSpace` for the given `PacketNumberSpace`.
845 /// This selects 0-RTT keys for `PacketNumberSpace::ApplicationData` if 1-RTT keys are
846 /// not yet available.
847 pub fn select_tx_mut(
848 &mut self,
849 version: Version,
850 space: PacketNumberSpace,
851 ) -> Option<(Epoch, &mut CryptoDxState)> {
852 match space {
853 PacketNumberSpace::Initial => self
854 .tx_mut(version, Epoch::Initial)
855 .map(|dx| (Epoch::Initial, dx)),
856 PacketNumberSpace::Handshake => self
857 .tx_mut(version, Epoch::Handshake)
858 .map(|dx| (Epoch::Handshake, dx)),
859 PacketNumberSpace::ApplicationData => {
860 if let Some(app) = self.app_write.as_mut() {
861 Some((Epoch::ApplicationData, &mut app.dx))
862 } else {
863 self.zero_rtt.as_mut().map(|dx| (Epoch::ZeroRtt, dx))
864 }
865 }
866 }
867 }
868
869 pub fn tx_mut<'a>(
870 &'a mut self,
871 version: Version,
872 epoch: Epoch,
873 ) -> Option<&'a mut CryptoDxState> {
874 let tx = |k: Option<&'a mut CryptoState>| k.map(|dx| &mut dx.tx);
875 match epoch {
876 Epoch::Initial => tx(self.initials[version].as_mut()),
877 Epoch::ZeroRtt => self
878 .zero_rtt
879 .as_mut()
880 .filter(|z| z.direction == CryptoDxDirection::Write),
881 Epoch::Handshake => tx(self.handshake.as_mut()),
882 Epoch::ApplicationData => self.app_write.as_mut().map(|app| &mut app.dx),
883 }
884 }
885
886 pub fn tx<'a>(&'a self, version: Version, epoch: Epoch) -> Option<&'a CryptoDxState> {
887 let tx = |k: Option<&'a CryptoState>| k.map(|dx| &dx.tx);
888 match epoch {
889 Epoch::Initial => tx(self.initials[version].as_ref()),
890 Epoch::ZeroRtt => self
891 .zero_rtt
892 .as_ref()
893 .filter(|z| z.direction == CryptoDxDirection::Write),
894 Epoch::Handshake => tx(self.handshake.as_ref()),
895 Epoch::ApplicationData => self.app_write.as_ref().map(|app| &app.dx),
896 }
897 }
898
899 pub fn select_tx(
900 &self,
901 version: Version,
902 space: PacketNumberSpace,
903 ) -> Option<(Epoch, &CryptoDxState)> {
904 match space {
905 PacketNumberSpace::Initial => self
906 .tx(version, Epoch::Initial)
907 .map(|dx| (Epoch::Initial, dx)),
908 PacketNumberSpace::Handshake => self
909 .tx(version, Epoch::Handshake)
910 .map(|dx| (Epoch::Handshake, dx)),
911 PacketNumberSpace::ApplicationData => self.app_write.as_ref().map_or_else(
912 || self.zero_rtt.as_ref().map(|dx| (Epoch::ZeroRtt, dx)),
913 |app| Some((Epoch::ApplicationData, &app.dx)),
914 ),
915 }
916 }
917
918 pub fn rx_hp(&mut self, version: Version, epoch: Epoch) -> Option<&mut CryptoDxState> {
919 if epoch == Epoch::ApplicationData {
920 self.app_read.as_mut().map(|ar| &mut ar.dx)
921 } else {
922 self.rx(version, epoch, false)
923 }
924 }
925
926 pub fn rx<'a>(
927 &'a mut self,
928 version: Version,
929 epoch: Epoch,
930 key_phase: bool,
931 ) -> Option<&'a mut CryptoDxState> {
932 let rx = |x: Option<&'a mut CryptoState>| x.map(|dx| &mut dx.rx);
933 match epoch {
934 Epoch::Initial => rx(self.initials[version].as_mut()),
935 Epoch::ZeroRtt => self
936 .zero_rtt
937 .as_mut()
938 .filter(|z| z.direction == CryptoDxDirection::Read),
939 Epoch::Handshake => rx(self.handshake.as_mut()),
940 Epoch::ApplicationData => {
941 let f = |a: Option<&'a mut CryptoDxAppData>| {
942 a.filter(|ar| ar.dx.key_phase() == key_phase)
943 };
944 // XOR to reduce the leakage about which key is chosen.
945 f(self.app_read.as_mut())
946 .xor(f(self.app_read_next.as_mut()))
947 .map(|ar| &mut ar.dx)
948 }
949 }
950 }
951
952 /// Whether keys for processing packets in the indicated space are pending.
953 /// This allows the caller to determine whether to save a packet for later
954 /// when keys are not available.
955 /// NOTE: 0-RTT keys are not considered here. The expectation is that a
956 /// server will have to save 0-RTT packets in a different place. Though it
957 /// is possible to attribute 0-RTT packets to an existing connection if there
958 /// is a multi-packet Initial, that is an unusual circumstance, so we
959 /// don't do caching for that in those places that call this function.
960 pub fn rx_pending(&self, space: Epoch) -> bool {
961 match space {
962 Epoch::Initial | Epoch::ZeroRtt => false,
963 Epoch::Handshake => self.handshake.is_none() && !self.initials_is_empty(),
964 Epoch::ApplicationData => self.app_read.is_none(),
965 }
966 }
967
968 /// Create the initial crypto state.
969 /// Note that the version here can change and that's OK.
970 pub fn init<'v, V>(&mut self, versions: V, role: Role, dcid: &[u8]) -> Res<()>
971 where
972 V: IntoIterator<Item = &'v Version>,
973 {
974 const CLIENT_INITIAL_LABEL: &str = "client in";
975 const SERVER_INITIAL_LABEL: &str = "server in";
976
977 let (write, read) = match role {
978 Role::Client => (CLIENT_INITIAL_LABEL, SERVER_INITIAL_LABEL),
979 Role::Server => (SERVER_INITIAL_LABEL, CLIENT_INITIAL_LABEL),
980 };
981
982 for v in versions {
983 qdebug!(
984 "[{self}] Creating initial cipher state v={v:?}, role={role:?} dcid={}",
985 hex(dcid)
986 );
987
988 let mut initial = CryptoState {
989 tx: CryptoDxState::new_initial(*v, CryptoDxDirection::Write, write, dcid)?,
990 rx: CryptoDxState::new_initial(*v, CryptoDxDirection::Read, read, dcid)?,
991 };
992 if let Some(prev) = &self.initials[*v] {
993 qinfo!(
994 "[{self}] Continue packet numbers for initial after retry (write is {:?})",
995 prev.rx.used_pn,
996 );
997 initial.tx.continuation(&prev.tx)?;
998 }
999 self.initials[*v] = Some(initial);
1000 }
1001 Ok(())
1002 }
1003
1004 /// At a server, we can be more targeted in initializing.
1005 /// Initialize on demand: either to decrypt Initial packets that we receive
1006 /// or after a version has been selected.
1007 /// This is maybe slightly inefficient in the first case, because we might
1008 /// not need the send keys if the packet is subsequently discarded, but
1009 /// the overall effort is small enough to write off.
1010 pub fn init_server(&mut self, version: Version, dcid: &[u8]) -> Res<()> {
1011 if self.initials[version].is_none() {
1012 self.init(&[version], Role::Server, dcid)?;
1013 }
1014 Ok(())
1015 }
1016
1017 pub fn confirm_version(&mut self, orig: Version, confirmed: Version) -> Res<()> {
1018 if orig != confirmed {
1019 // This part where the old data is removed and then re-added is to
1020 // appease the borrow checker.
1021 // Note that on the server, we might not have initials for |orig| if it
1022 // was configured for |orig| and only |confirmed| Initial packets arrived.
1023 if let Some(prev) = self.initials[orig].take() {
1024 let next = self.initials[confirmed]
1025 .as_mut()
1026 .ok_or(Error::VersionNegotiation)?;
1027 next.tx.continuation(&prev.tx)?;
1028 self.initials[orig] = Some(prev);
1029 }
1030 }
1031 Ok(())
1032 }
1033
1034 pub fn set_0rtt_keys(
1035 &mut self,
1036 version: Version,
1037 dir: CryptoDxDirection,
1038 secret: &SymKey,
1039 cipher: Cipher,
1040 ) -> Res<()> {
1041 qtrace!("[{self}] install 0-RTT keys");
1042 self.zero_rtt = Some(CryptoDxState::new(
1043 version,
1044 dir,
1045 Epoch::ZeroRtt,
1046 secret,
1047 cipher,
1048 )?);
1049 Ok(())
1050 }
1051
1052 /// Discard keys and return true if that happened.
1053 pub fn discard(&mut self, space: PacketNumberSpace) -> bool {
1054 match space {
1055 PacketNumberSpace::Initial => {
1056 let empty = self.initials_is_empty();
1057 self.initials.clear();
1058 !empty
1059 }
1060 PacketNumberSpace::Handshake => self.handshake.take().is_some(),
1061 PacketNumberSpace::ApplicationData => panic!("Can't drop application data keys"),
1062 }
1063 }
1064
1065 pub fn discard_0rtt_keys(&mut self) {
1066 qtrace!("[{self}] discard 0-RTT keys");
1067 assert!(
1068 self.app_read.is_none(),
1069 "Can't discard 0-RTT after setting application keys"
1070 );
1071 self.zero_rtt = None;
1072 }
1073
1074 pub fn set_handshake_keys(
1075 &mut self,
1076 version: Version,
1077 write_secret: &SymKey,
1078 read_secret: &SymKey,
1079 cipher: Cipher,
1080 ) -> Res<()> {
1081 self.cipher = cipher;
1082 self.handshake = Some(CryptoState {
1083 tx: CryptoDxState::new(
1084 version,
1085 CryptoDxDirection::Write,
1086 Epoch::Handshake,
1087 write_secret,
1088 cipher,
1089 )?,
1090 rx: CryptoDxState::new(
1091 version,
1092 CryptoDxDirection::Read,
1093 Epoch::Handshake,
1094 read_secret,
1095 cipher,
1096 )?,
1097 });
1098 Ok(())
1099 }
1100
1101 pub fn set_application_write_key(&mut self, version: Version, secret: &SymKey) -> Res<()> {
1102 debug_assert!(self.app_write.is_none());
1103 debug_assert_ne!(self.cipher, 0);
1104 let mut app = CryptoDxAppData::new(version, CryptoDxDirection::Write, secret, self.cipher)?;
1105 if let Some(z) = &self.zero_rtt {
1106 if z.direction == CryptoDxDirection::Write {
1107 app.dx.continuation(z)?;
1108 }
1109 }
1110 self.zero_rtt = None;
1111 self.app_write = Some(app);
1112 Ok(())
1113 }
1114
1115 pub fn set_application_read_key(
1116 &mut self,
1117 version: Version,
1118 secret: &SymKey,
1119 expire_0rtt: Instant,
1120 ) -> Res<()> {
1121 debug_assert!(self.app_write.is_some(), "should have write keys installed");
1122 debug_assert!(self.app_read.is_none());
1123 let mut app = CryptoDxAppData::new(version, CryptoDxDirection::Read, secret, self.cipher)?;
1124 if let Some(z) = &self.zero_rtt {
1125 if z.direction == CryptoDxDirection::Read {
1126 app.dx.continuation(z)?;
1127 }
1128 self.read_update_time = Some(expire_0rtt);
1129 }
1130 self.app_read_next = Some(app.next()?);
1131 self.app_read = Some(app);
1132 Ok(())
1133 }
1134
1135 /// Update the write keys.
1136 pub fn initiate_key_update(&mut self, largest_acknowledged: Option<PacketNumber>) -> Res<()> {
1137 // Only update if we are able to. We can only do this if we have
1138 // received an acknowledgement for a packet in the current phase.
1139 // Also, skip this if we are waiting for read keys on the existing
1140 // key update to be rolled over.
1141 let write = &self.app_write.as_ref().ok_or(Error::InternalError)?.dx;
1142 if write.can_update(largest_acknowledged) && self.read_update_time.is_none() {
1143 // This call additionally checks that we don't advance to the next
1144 // epoch while a key update is in progress.
1145 if self.maybe_update_write()? {
1146 Ok(())
1147 } else {
1148 qdebug!("[{self}] Write keys already updated");
1149 Err(Error::KeyUpdateBlocked)
1150 }
1151 } else {
1152 qdebug!("[{self}] Waiting for ACK or blocked on read key timer");
1153 Err(Error::KeyUpdateBlocked)
1154 }
1155 }
1156
1157 /// Try to update, and return true if it happened.
1158 fn maybe_update_write(&mut self) -> Res<bool> {
1159 // Update write keys. But only do so if the write keys are not already
1160 // ahead of the read keys. If we initiated the key update, the write keys
1161 // will already be ahead.
1162 debug_assert!(self.read_update_time.is_none());
1163 let write = &self.app_write.as_ref().ok_or(Error::InternalError)?;
1164 let read = &self.app_read.as_ref().ok_or(Error::InternalError)?;
1165 if write.epoch() == read.epoch() {
1166 qdebug!("[{self}] Update write keys to epoch={}", write.epoch() + 1);
1167 self.app_write = Some(write.next()?);
1168 Ok(true)
1169 } else {
1170 Ok(false)
1171 }
1172 }
1173
1174 /// Check whether write keys are close to running out of invocations.
1175 /// If that is close, update them if possible. Failing to update at
1176 /// this stage is cause for a fatal error.
1177 pub fn auto_update(&mut self) -> Res<()> {
1178 if let Some(app_write) = self.app_write.as_ref() {
1179 if app_write.dx.should_update() {
1180 qinfo!("[{self}] Initiating automatic key update");
1181 if !self.maybe_update_write()? {
1182 return Err(Error::KeysExhausted);
1183 }
1184 }
1185 }
1186 Ok(())
1187 }
1188
1189 fn has_0rtt_read(&self) -> bool {
1190 self.zero_rtt
1191 .as_ref()
1192 .filter(|z| z.direction == CryptoDxDirection::Read)
1193 .is_some()
1194 }
1195
1196 /// Prepare to update read keys. This doesn't happen immediately as
1197 /// we want to ensure that we can continue to receive any delayed
1198 /// packets that use the old keys. So we just set a timer.
1199 pub fn key_update_received(&mut self, expiration: Instant) -> Res<()> {
1200 qtrace!("[{self}] Key update received");
1201 // If we received a key update, then we assume that the peer has
1202 // acknowledged a packet we sent in this epoch. It's OK to do that
1203 // because they aren't allowed to update without first having received
1204 // something from us. If the ACK isn't in the packet that triggered this
1205 // key update, it must be in some other packet they have sent.
1206 _ = self.maybe_update_write()?;
1207
1208 // We shouldn't have 0-RTT keys at this point, but if we do, dump them.
1209 debug_assert_eq!(self.read_update_time.is_some(), self.has_0rtt_read());
1210 if self.has_0rtt_read() {
1211 self.zero_rtt = None;
1212 }
1213 self.read_update_time = Some(expiration);
1214 Ok(())
1215 }
1216
1217 #[must_use]
1218 pub const fn update_time(&self) -> Option<Instant> {
1219 self.read_update_time
1220 }
1221
1222 /// Check if time has passed for updating key update parameters.
1223 /// If it has, then swap keys over and allow more key updates to be initiated.
1224 /// This is also used to discard 0-RTT read keys at the server in the same way.
1225 pub fn check_key_update(&mut self, now: Instant) -> Res<()> {
1226 if let Some(expiry) = self.read_update_time {
1227 // If enough time has passed, then install new keys and clear the timer.
1228 if now >= expiry {
1229 if self.has_0rtt_read() {
1230 qtrace!("[{self}] Discarding 0-RTT keys");
1231 self.zero_rtt = None;
1232 } else {
1233 qtrace!("[{self}] Rotating read keys");
1234 mem::swap(&mut self.app_read, &mut self.app_read_next);
1235 self.app_read_next =
1236 Some(self.app_read.as_ref().ok_or(Error::InternalError)?.next()?);
1237 }
1238 self.read_update_time = None;
1239 }
1240 }
1241 Ok(())
1242 }
1243
1244 /// Get the current/highest epoch. This returns (write, read) epochs.
1245 #[cfg(test)]
1246 pub fn get_epochs(&self) -> (Option<usize>, Option<usize>) {
1247 let to_epoch = |app: &Option<CryptoDxAppData>| app.as_ref().map(|a| a.dx.epoch);
1248 (to_epoch(&self.app_write), to_epoch(&self.app_read))
1249 }
1250
1251 /// While we are awaiting the completion of a key update, we might receive
1252 /// valid packets that are protected with old keys. We need to ensure that
1253 /// these don't carry packet numbers higher than those in packets protected
1254 /// with the newer keys. To ensure that, this is called after every decryption.
1255 pub fn check_pn_overlap(&mut self) -> Res<()> {
1256 // We only need to do the check while we are waiting for read keys to be updated.
1257 if self.read_update_time.is_some() {
1258 qtrace!("[{self}] Checking for PN overlap");
1259 let next_dx = &mut self.app_read_next.as_mut().ok_or(Error::InternalError)?.dx;
1260 next_dx.continuation(&self.app_read.as_ref().ok_or(Error::InternalError)?.dx)?;
1261 }
1262 Ok(())
1263 }
1264
1265 /// Make some state for removing protection in tests.
1266 #[cfg(not(feature = "disable-encryption"))]
1267 #[cfg(test)]
1268 pub(crate) fn test_default() -> Self {
1269 let read = |epoch| {
1270 let mut dx = CryptoDxState::test_default();
1271 dx.direction = CryptoDxDirection::Read;
1272 dx.epoch = epoch;
1273 dx
1274 };
1275 let app_read = |epoch| CryptoDxAppData {
1276 dx: read(epoch),
1277 cipher: TLS_AES_128_GCM_SHA256,
1278 next_secret: hkdf::import_key(TLS_VERSION_1_3, &[0xaa; 32]).unwrap(),
1279 };
1280 let initials = EnumMap::from_array([
1281 None,
1282 Some(CryptoState {
1283 tx: CryptoDxState::test_default(),
1284 rx: read(0),
1285 }),
1286 None,
1287 ]);
1288 Self {
1289 initials,
1290 handshake: None,
1291 zero_rtt: None,
1292 cipher: TLS_AES_128_GCM_SHA256,
1293 // This isn't used, but the epoch is read to check for a key update.
1294 app_write: Some(app_read(3)),
1295 app_read: Some(app_read(3)),
1296 app_read_next: Some(app_read(4)),
1297 read_update_time: None,
1298 }
1299 }
1300
1301 #[cfg(all(not(feature = "disable-encryption"), test))]
1302 #[cfg(test)]
1303 pub(crate) fn test_chacha() -> Self {
1304 const SECRET: &[u8] = &[
1305 0x9a, 0xc3, 0x12, 0xa7, 0xf8, 0x77, 0x46, 0x8e, 0xbe, 0x69, 0x42, 0x27, 0x48, 0xad,
1306 0x00, 0xa1, 0x54, 0x43, 0xf1, 0x82, 0x03, 0xa0, 0x7d, 0x60, 0x60, 0xf6, 0x88, 0xf3,
1307 0x0f, 0x21, 0x63, 0x2b,
1308 ];
1309 let secret = hkdf::import_key(TLS_VERSION_1_3, SECRET).unwrap();
1310 let app_read = |epoch| CryptoDxAppData {
1311 dx: CryptoDxState {
1312 version: Version::Version1,
1313 direction: CryptoDxDirection::Read,
1314 epoch,
1315 aead: Aead::new(
1316 TLS_VERSION_1_3,
1317 TLS_CHACHA20_POLY1305_SHA256,
1318 &secret,
1319 "quic ", // This is a v1 test so hard-code the label.
1320 )
1321 .unwrap(),
1322 hpkey: HpKey::extract(
1323 TLS_VERSION_1_3,
1324 TLS_CHACHA20_POLY1305_SHA256,
1325 &secret,
1326 "quic hp",
1327 )
1328 .unwrap(),
1329 used_pn: 0..645_971_972,
1330 min_pn: 0,
1331 invocations: 10,
1332 largest_packet_len: INITIAL_LARGEST_PACKET_LEN,
1333 },
1334 cipher: TLS_CHACHA20_POLY1305_SHA256,
1335 next_secret: secret.clone(),
1336 };
1337 Self {
1338 initials: EnumMap::default(),
1339 handshake: None,
1340 zero_rtt: None,
1341 cipher: TLS_CHACHA20_POLY1305_SHA256,
1342 app_write: Some(app_read(3)),
1343 app_read: Some(app_read(3)),
1344 app_read_next: Some(app_read(4)),
1345 read_update_time: None,
1346 }
1347 }
1348 }
1349
1350 impl Display for CryptoStates {
1351 fn fmt(&self, f: &mut Formatter) -> fmt::Result {
1352 write!(f, "CryptoStates")
1353 }
1354 }
1355
1356 #[derive(Debug, Default)]
1357 pub struct CryptoStream {
1358 tx: TxBuffer,
1359 rx: RxStreamOrderer,
1360 }
1361
1362 #[derive(Debug)]
1363 pub enum CryptoStreams {
1364 Initial {
1365 initial: CryptoStream,
1366 handshake: CryptoStream,
1367 application: CryptoStream,
1368 },
1369 Handshake {
1370 handshake: CryptoStream,
1371 application: CryptoStream,
1372 },
1373 ApplicationData {
1374 application: CryptoStream,
1375 },
1376 }
1377
1378 impl CryptoStreams {
1379 /// Keep around 64k if a server wants to push excess data at us.
1380 const BUFFER_LIMIT: u64 = 65536;
1381
1382 pub fn discard(&mut self, space: PacketNumberSpace) {
1383 match space {
1384 PacketNumberSpace::Initial => {
1385 if let Self::Initial {
1386 handshake,
1387 application,
1388 ..
1389 } = self
1390 {
1391 *self = Self::Handshake {
1392 handshake: mem::take(handshake),
1393 application: mem::take(application),
1394 };
1395 }
1396 }
1397 PacketNumberSpace::Handshake => {
1398 if let Self::Handshake { application, .. } = self {
1399 *self = Self::ApplicationData {
1400 application: mem::take(application),
1401 };
1402 } else if matches!(self, Self::Initial { .. }) {
1403 panic!("Discarding handshake before initial discarded");
1404 }
1405 }
1406 PacketNumberSpace::ApplicationData => {
1407 panic!("Discarding application data crypto streams")
1408 }
1409 }
1410 }
1411
1412 pub fn send(&mut self, space: PacketNumberSpace, data: &[u8]) -> Res<()> {
1413 self.get_mut(space)
1414 .ok_or(Error::ProtocolViolation)?
1415 .tx
1416 .send(data);
1417 Ok(())
1418 }
1419
1420 pub fn inbound_frame(&mut self, space: PacketNumberSpace, offset: u64, data: &[u8]) -> Res<()> {
1421 let rx = &mut self.get_mut(space).ok_or(Error::InternalError)?.rx;
1422 rx.inbound_frame(offset, data);
1423 if rx.received() - rx.retired() <= Self::BUFFER_LIMIT {
1424 Ok(())
1425 } else {
1426 Err(Error::CryptoBufferExceeded)
1427 }
1428 }
1429
1430 pub fn data_ready(&self, space: PacketNumberSpace) -> bool {
1431 self.get(space).is_some_and(|cs| cs.rx.data_ready())
1432 }
1433
1434 pub fn read_to_end(&mut self, space: PacketNumberSpace, buf: &mut Vec<u8>) -> Res<usize> {
1435 Ok(self
1436 .get_mut(space)
1437 .ok_or(Error::ProtocolViolation)?
1438 .rx
1439 .read_to_end(buf))
1440 }
1441
1442 pub fn acked(&mut self, token: &CryptoRecoveryToken) {
1443 if let Some(cs) = self.get_mut(token.space) {
1444 cs.tx.mark_as_acked(token.offset, token.length);
1445 }
1446 }
1447
1448 pub fn lost(&mut self, token: &CryptoRecoveryToken) {
1449 // See BZ 1624800, ignore lost packets in spaces we've dropped keys
1450 if let Some(cs) = self.get_mut(token.space) {
1451 cs.tx.mark_as_lost(token.offset, token.length);
1452 }
1453 }
1454
1455 /// Resend any Initial or Handshake CRYPTO frames that might be outstanding.
1456 /// This can help speed up handshake times.
1457 pub fn resend_unacked(&mut self, space: PacketNumberSpace) {
1458 if space != PacketNumberSpace::ApplicationData {
1459 if let Some(cs) = self.get_mut(space) {
1460 cs.tx.unmark_sent();
1461 }
1462 }
1463 }
1464
1465 pub fn is_empty(&mut self, space: PacketNumberSpace) -> bool {
1466 self.get_mut(space).is_none_or(|cs| cs.tx.is_empty())
1467 }
1468
1469 const fn get(&self, space: PacketNumberSpace) -> Option<&CryptoStream> {
1470 let (initial, hs, app) = match self {
1471 Self::Initial {
1472 initial,
1473 handshake,
1474 application,
1475 } => (Some(initial), Some(handshake), Some(application)),
1476 Self::Handshake {
1477 handshake,
1478 application,
1479 } => (None, Some(handshake), Some(application)),
1480 Self::ApplicationData { application } => (None, None, Some(application)),
1481 };
1482 match space {
1483 PacketNumberSpace::Initial => initial,
1484 PacketNumberSpace::Handshake => hs,
1485 PacketNumberSpace::ApplicationData => app,
1486 }
1487 }
1488
1489 fn get_mut(&mut self, space: PacketNumberSpace) -> Option<&mut CryptoStream> {
1490 let (initial, hs, app) = match self {
1491 Self::Initial {
1492 initial,
1493 handshake,
1494 application,
1495 } => (Some(initial), Some(handshake), Some(application)),
1496 Self::Handshake {
1497 handshake,
1498 application,
1499 } => (None, Some(handshake), Some(application)),
1500 Self::ApplicationData { application } => (None, None, Some(application)),
1501 };
1502 match space {
1503 PacketNumberSpace::Initial => initial,
1504 PacketNumberSpace::Handshake => hs,
1505 PacketNumberSpace::ApplicationData => app,
1506 }
1507 }
1508
1509 pub fn write_frame(
1510 &mut self,
1511 space: PacketNumberSpace,
1512 sni_slicing: bool,
1513 builder: &mut PacketBuilder,
1514 tokens: &mut Vec<RecoveryToken>,
1515 stats: &mut FrameStats,
1516 ) {
1517 fn write_chunk(
1518 offset: u64,
1519 data: &[u8],
1520 builder: &mut PacketBuilder,
1521 ) -> Option<(u64, usize)> {
1522 let mut header_len = 1 + Encoder::varint_len(offset) + 1;
1523
1524 // Don't bother if there isn't room for the header and some data.
1525 if builder.remaining() < header_len + 1 {
1526 return None;
1527 }
1528 // Calculate length of data based on the minimum of:
1529 // - available data
1530 // - remaining space, less the header, which counts only one byte for the length at
1531 // first to avoid underestimating length
1532 let length = min(data.len(), builder.remaining() - header_len);
1533 header_len +=
1534 Encoder::varint_len(u64::try_from(length).expect("usize fits in u64")) - 1;
1535 let length = min(data.len(), builder.remaining() - header_len);
1536
1537 builder.encode_varint(FrameType::Crypto);
1538 builder.encode_varint(offset);
1539 builder.encode_vvec(&data[..length]);
1540 Some((offset, length))
1541 }
1542
1543 fn mark_as_sent(
1544 cs: &mut CryptoStream,
1545 space: PacketNumberSpace,
1546 tokens: &mut Vec<RecoveryToken>,
1547 offset: u64,
1548 len: usize,
1549 stats: &mut FrameStats,
1550 ) {
1551 cs.tx.mark_as_sent(offset, len);
1552 qdebug!("CRYPTO for {space} offset={offset}, len={len}");
1553 tokens.push(RecoveryToken::Crypto(CryptoRecoveryToken {
1554 space,
1555 offset,
1556 length: len,
1557 }));
1558 stats.crypto += 1;
1559 }
1560
1561 #[expect(clippy::type_complexity, reason = "Yeah, a bit complex but still OK.")]
1562 const fn limit_chunks<'a>(
1563 left: (u64, &'a [u8]),
1564 right: (u64, &'a [u8]),
1565 limit: usize,
1566 ) -> ((u64, &'a [u8]), (u64, &'a [u8])) {
1567 let (left_offset, mut left) = left;
1568 let (mut right_offset, mut right) = right;
1569 if left.len() + right.len() <= limit {
1570 // Nothing to do. Both chunks will fit into one packet, meaning the SNI isn't spread
1571 // over multiple packets. But at least it's in two unordered CRYPTO frames.
1572 } else if left.len() <= limit {
1573 // `left` is short enough to fit into this packet. So send from the *end*
1574 // of `right`, so that the second half of the SNI is in another packet.
1575 let right_len = right.len() + left.len() - limit;
1576 right_offset += right_len as u64;
1577 (_, right) = right.split_at(right_len);
1578 } else if right.len() <= limit {
1579 // `right` is short enough to fit into this packet. So only send a part of `left`.
1580 // The SNI begins at the end of `left`, so send the beginnig of it in this packet.
1581 (left, _) = left.split_at(limit - right.len());
1582 } else {
1583 // Both chunks are too long to fit into one packet. Just send a part of each.
1584 (left, _) = left.split_at(limit / 2);
1585 (right, _) = right.split_at(limit / 2);
1586 }
1587 ((left_offset, left), (right_offset, right))
1588 }
1589
1590 let Some(cs) = self.get_mut(space) else {
1591 return;
1592 };
1593 while let Some((offset, data)) = cs.tx.next_bytes() {
1594 let written = if sni_slicing && offset == 0 {
1595 if let Some(sni) = find_sni(data) {
1596 // Cut the crypto data in two at the midpoint of the SNI and swap the chunks.
1597 let mid = sni.start + (sni.end - sni.start) / 2;
1598 let (left, right) = data.split_at(mid);
1599
1600 // Truncate the chunks so we can fit them into roughly evenly-filled packets.
1601 let packets_needed = data.len().div_ceil(builder.limit());
1602 let limit = data.len() / packets_needed;
1603 let ((left_offset, left), (right_offset, right)) =
1604 limit_chunks((offset, left), (offset + mid as u64, right), limit);
1605 (
1606 write_chunk(right_offset, right, builder),
1607 write_chunk(left_offset, left, builder),
1608 )
1609 } else {
1610 // No SNI found, write the entire data.
1611 (write_chunk(offset, data, builder), None)
1612 }
1613 } else {
1614 // SNI slicing disabled or data not at offset 0, write the entire data.
1615 (write_chunk(offset, data, builder), None)
1616 };
1617
1618 match written {
1619 (None, None) => break,
1620 (None, Some((offset, len))) | (Some((offset, len)), None) => {
1621 mark_as_sent(cs, space, tokens, offset, len, stats);
1622 }
1623 (Some((offset1, len1)), Some((offset2, len2))) => {
1624 mark_as_sent(cs, space, tokens, offset1, len1, stats);
1625 mark_as_sent(cs, space, tokens, offset2, len2, stats);
1626 // We only end up in this arm if we successfully sliced above. In that case,
1627 // don't try and fit more crypto data into this packet.
1628 break;
1629 }
1630 }
1631 }
1632 }
1633 }
1634
1635 impl Default for CryptoStreams {
1636 fn default() -> Self {
1637 Self::Initial {
1638 initial: CryptoStream::default(),
1639 handshake: CryptoStream::default(),
1640 application: CryptoStream::default(),
1641 }
1642 }
1643 }
1644
1645 #[derive(Debug, Clone)]
1646 pub struct CryptoRecoveryToken {
1647 space: PacketNumberSpace,
1648 offset: u64,
1649 length: usize,
1650 }