1use crate::enums::{AlertDescription, ContentType, HandshakeType, ProtocolVersion};
2use crate::error::{Error, InvalidMessage, PeerMisbehaved};
3#[cfg(feature = "logging")]
4use crate::log::{debug, warn};
5use crate::msgs::alert::AlertMessagePayload;
6use crate::msgs::base::Payload;
7use crate::msgs::enums::{AlertLevel, KeyUpdateRequest};
8use crate::msgs::fragmenter::MessageFragmenter;
9use crate::msgs::handshake::CertificateChain;
10use crate::msgs::message::MessagePayload;
11use crate::msgs::message::{BorrowedPlainMessage, Message, OpaqueMessage, PlainMessage};
12use crate::quic;
13use crate::record_layer;
14use crate::suites::PartiallyExtractedSecrets;
15use crate::suites::SupportedCipherSuite;
16#[cfg(feature = "tls12")]
17use crate::tls12::ConnectionSecrets;
18use crate::vecbuf::ChunkVecBuffer;
19
20use alloc::boxed::Box;
21use alloc::vec::Vec;
22
23use pki_types::CertificateDer;
24
25/// Connection state common to both client and server connections.
26pub struct CommonState {
27 pub(crate) negotiated_version: Option<ProtocolVersion>,
28 pub(crate) side: Side,
29 pub(crate) record_layer: record_layer::RecordLayer,
30 pub(crate) suite: Option<SupportedCipherSuite>,
31 pub(crate) alpn_protocol: Option<Vec<u8>>,
32 pub(crate) aligned_handshake: bool,
33 pub(crate) may_send_application_data: bool,
34 pub(crate) may_receive_application_data: bool,
35 pub(crate) early_traffic: bool,
36 sent_fatal_alert: bool,
37 /// If the peer has signaled end of stream.
38 pub(crate) has_received_close_notify: bool,
39 pub(crate) has_seen_eof: bool,
40 pub(crate) received_middlebox_ccs: u8,
41 pub(crate) peer_certificates: Option<CertificateChain>,
42 message_fragmenter: MessageFragmenter,
43 pub(crate) received_plaintext: ChunkVecBuffer,
44 sendable_plaintext: ChunkVecBuffer,
45 pub(crate) sendable_tls: ChunkVecBuffer,
46 queued_key_update_message: Option<Vec<u8>>,
47
48 /// Protocol whose key schedule should be used. Unused for TLS < 1.3.
49 pub(crate) protocol: Protocol,
50 pub(crate) quic: quic::Quic,
51 pub(crate) enable_secret_extraction: bool,
52}
53
54impl CommonState {
55 pub(crate) fn new(side: Side) -> Self {
56 Self {
57 negotiated_version: None,
58 side,
59 record_layer: record_layer::RecordLayer::new(),
60 suite: None,
61 alpn_protocol: None,
62 aligned_handshake: true,
63 may_send_application_data: false,
64 may_receive_application_data: false,
65 early_traffic: false,
66 sent_fatal_alert: false,
67 has_received_close_notify: false,
68 has_seen_eof: false,
69 received_middlebox_ccs: 0,
70 peer_certificates: None,
71 message_fragmenter: MessageFragmenter::default(),
72 received_plaintext: ChunkVecBuffer::new(Some(DEFAULT_RECEIVED_PLAINTEXT_LIMIT)),
73 sendable_plaintext: ChunkVecBuffer::new(Some(DEFAULT_BUFFER_LIMIT)),
74 sendable_tls: ChunkVecBuffer::new(Some(DEFAULT_BUFFER_LIMIT)),
75 queued_key_update_message: None,
76 protocol: Protocol::Tcp,
77 quic: quic::Quic::default(),
78 enable_secret_extraction: false,
79 }
80 }
81
82 /// Returns true if the caller should call [`Connection::write_tls`] as soon as possible.
83 ///
84 /// [`Connection::write_tls`]: crate::Connection::write_tls
85 pub fn wants_write(&self) -> bool {
86 !self.sendable_tls.is_empty()
87 }
88
89 /// Returns true if the connection is currently performing the TLS handshake.
90 ///
91 /// During this time plaintext written to the connection is buffered in memory. After
92 /// [`Connection::process_new_packets()`] has been called, this might start to return `false`
93 /// while the final handshake packets still need to be extracted from the connection's buffers.
94 ///
95 /// [`Connection::process_new_packets()`]: crate::Connection::process_new_packets
96 pub fn is_handshaking(&self) -> bool {
97 !(self.may_send_application_data && self.may_receive_application_data)
98 }
99
100 /// Retrieves the certificate chain used by the peer to authenticate.
101 ///
102 /// The order of the certificate chain is as it appears in the TLS
103 /// protocol: the first certificate relates to the peer, the
104 /// second certifies the first, the third certifies the second, and
105 /// so on.
106 ///
107 /// This is made available for both full and resumed handshakes.
108 ///
109 /// For clients, this is the certificate chain of the server.
110 ///
111 /// For servers, this is the certificate chain of the client,
112 /// if client authentication was completed.
113 ///
114 /// The return value is None until this value is available.
115 pub fn peer_certificates(&self) -> Option<&[CertificateDer<'_>]> {
116 self.peer_certificates.as_deref()
117 }
118
119 /// Retrieves the protocol agreed with the peer via ALPN.
120 ///
121 /// A return value of `None` after handshake completion
122 /// means no protocol was agreed (because no protocols
123 /// were offered or accepted by the peer).
124 pub fn alpn_protocol(&self) -> Option<&[u8]> {
125 self.get_alpn_protocol()
126 }
127
128 /// Retrieves the ciphersuite agreed with the peer.
129 ///
130 /// This returns None until the ciphersuite is agreed.
131 pub fn negotiated_cipher_suite(&self) -> Option<SupportedCipherSuite> {
132 self.suite
133 }
134
135 /// Retrieves the protocol version agreed with the peer.
136 ///
137 /// This returns `None` until the version is agreed.
138 pub fn protocol_version(&self) -> Option<ProtocolVersion> {
139 self.negotiated_version
140 }
141
142 pub(crate) fn is_tls13(&self) -> bool {
143 matches!(self.negotiated_version, Some(ProtocolVersion::TLSv1_3))
144 }
145
146 pub(crate) fn process_main_protocol<Data>(
147 &mut self,
148 msg: Message,
149 mut state: Box<dyn State<Data>>,
150 data: &mut Data,
151 ) -> Result<Box<dyn State<Data>>, Error> {
152 // For TLS1.2, outside of the handshake, send rejection alerts for
153 // renegotiation requests. These can occur any time.
154 if self.may_receive_application_data && !self.is_tls13() {
155 let reject_ty = match self.side {
156 Side::Client => HandshakeType::HelloRequest,
157 Side::Server => HandshakeType::ClientHello,
158 };
159 if msg.is_handshake_type(reject_ty) {
160 self.send_warning_alert(AlertDescription::NoRenegotiation);
161 return Ok(state);
162 }
163 }
164
165 let mut cx = Context { common: self, data };
166 match state.handle(&mut cx, msg) {
167 Ok(next) => {
168 state = next;
169 Ok(state)
170 }
171 Err(e @ Error::InappropriateMessage { .. })
172 | Err(e @ Error::InappropriateHandshakeMessage { .. }) => {
173 Err(self.send_fatal_alert(AlertDescription::UnexpectedMessage, e))
174 }
175 Err(e) => Err(e),
176 }
177 }
178
179 /// Send plaintext application data, fragmenting and
180 /// encrypting it as it goes out.
181 ///
182 /// If internal buffers are too small, this function will not accept
183 /// all the data.
184 pub(crate) fn send_some_plaintext(&mut self, data: &[u8]) -> usize {
185 self.perhaps_write_key_update();
186 self.send_plain(data, Limit::Yes)
187 }
188
189 pub(crate) fn send_early_plaintext(&mut self, data: &[u8]) -> usize {
190 debug_assert!(self.early_traffic);
191 debug_assert!(self.record_layer.is_encrypting());
192
193 if data.is_empty() {
194 // Don't send empty fragments.
195 return 0;
196 }
197
198 self.send_appdata_encrypt(data, Limit::Yes)
199 }
200
201 // Changing the keys must not span any fragmented handshake
202 // messages. Otherwise the defragmented messages will have
203 // been protected with two different record layer protections,
204 // which is illegal. Not mentioned in RFC.
205 pub(crate) fn check_aligned_handshake(&mut self) -> Result<(), Error> {
206 if !self.aligned_handshake {
207 Err(self.send_fatal_alert(
208 AlertDescription::UnexpectedMessage,
209 PeerMisbehaved::KeyEpochWithPendingFragment,
210 ))
211 } else {
212 Ok(())
213 }
214 }
215
216 /// Fragment `m`, encrypt the fragments, and then queue
217 /// the encrypted fragments for sending.
218 pub(crate) fn send_msg_encrypt(&mut self, m: PlainMessage) {
219 let iter = self
220 .message_fragmenter
221 .fragment_message(&m);
222 for m in iter {
223 self.send_single_fragment(m);
224 }
225 }
226
227 /// Like send_msg_encrypt, but operate on an appdata directly.
228 fn send_appdata_encrypt(&mut self, payload: &[u8], limit: Limit) -> usize {
229 // Here, the limit on sendable_tls applies to encrypted data,
230 // but we're respecting it for plaintext data -- so we'll
231 // be out by whatever the cipher+record overhead is. That's a
232 // constant and predictable amount, so it's not a terrible issue.
233 let len = match limit {
234 Limit::Yes => self
235 .sendable_tls
236 .apply_limit(payload.len()),
237 Limit::No => payload.len(),
238 };
239
240 let iter = self.message_fragmenter.fragment_slice(
241 ContentType::ApplicationData,
242 ProtocolVersion::TLSv1_2,
243 &payload[..len],
244 );
245 for m in iter {
246 self.send_single_fragment(m);
247 }
248
249 len
250 }
251
252 fn send_single_fragment(&mut self, m: BorrowedPlainMessage) {
253 // Close connection once we start to run out of
254 // sequence space.
255 if self
256 .record_layer
257 .wants_close_before_encrypt()
258 {
259 self.send_close_notify();
260 }
261
262 // Refuse to wrap counter at all costs. This
263 // is basically untestable unfortunately.
264 if self.record_layer.encrypt_exhausted() {
265 return;
266 }
267
268 let em = self.record_layer.encrypt_outgoing(m);
269 self.queue_tls_message(em);
270 }
271
272 /// Encrypt and send some plaintext `data`. `limit` controls
273 /// whether the per-connection buffer limits apply.
274 ///
275 /// Returns the number of bytes written from `data`: this might
276 /// be less than `data.len()` if buffer limits were exceeded.
277 fn send_plain(&mut self, data: &[u8], limit: Limit) -> usize {
278 if !self.may_send_application_data {
279 // If we haven't completed handshaking, buffer
280 // plaintext to send once we do.
281 let len = match limit {
282 Limit::Yes => self
283 .sendable_plaintext
284 .append_limited_copy(data),
285 Limit::No => self
286 .sendable_plaintext
287 .append(data.to_vec()),
288 };
289 return len;
290 }
291
292 debug_assert!(self.record_layer.is_encrypting());
293
294 if data.is_empty() {
295 // Don't send empty fragments.
296 return 0;
297 }
298
299 self.send_appdata_encrypt(data, limit)
300 }
301
302 pub(crate) fn start_outgoing_traffic(&mut self) {
303 self.may_send_application_data = true;
304 self.flush_plaintext();
305 }
306
307 pub(crate) fn start_traffic(&mut self) {
308 self.may_receive_application_data = true;
309 self.start_outgoing_traffic();
310 }
311
312 /// Sets a limit on the internal buffers used to buffer
313 /// unsent plaintext (prior to completing the TLS handshake)
314 /// and unsent TLS records. This limit acts only on application
315 /// data written through [`Connection::writer`].
316 ///
317 /// By default the limit is 64KB. The limit can be set
318 /// at any time, even if the current buffer use is higher.
319 ///
320 /// [`None`] means no limit applies, and will mean that written
321 /// data is buffered without bound -- it is up to the application
322 /// to appropriately schedule its plaintext and TLS writes to bound
323 /// memory usage.
324 ///
325 /// For illustration: `Some(1)` means a limit of one byte applies:
326 /// [`Connection::writer`] will accept only one byte, encrypt it and
327 /// add a TLS header. Once this is sent via [`Connection::write_tls`],
328 /// another byte may be sent.
329 ///
330 /// # Internal write-direction buffering
331 /// rustls has two buffers whose size are bounded by this setting:
332 ///
333 /// ## Buffering of unsent plaintext data prior to handshake completion
334 ///
335 /// Calls to [`Connection::writer`] before or during the handshake
336 /// are buffered (up to the limit specified here). Once the
337 /// handshake completes this data is encrypted and the resulting
338 /// TLS records are added to the outgoing buffer.
339 ///
340 /// ## Buffering of outgoing TLS records
341 ///
342 /// This buffer is used to store TLS records that rustls needs to
343 /// send to the peer. It is used in these two circumstances:
344 ///
345 /// - by [`Connection::process_new_packets`] when a handshake or alert
346 /// TLS record needs to be sent.
347 /// - by [`Connection::writer`] post-handshake: the plaintext is
348 /// encrypted and the resulting TLS record is buffered.
349 ///
350 /// This buffer is emptied by [`Connection::write_tls`].
351 ///
352 /// [`Connection::writer`]: crate::Connection::writer
353 /// [`Connection::write_tls`]: crate::Connection::write_tls
354 /// [`Connection::process_new_packets`]: crate::Connection::process_new_packets
355 pub fn set_buffer_limit(&mut self, limit: Option<usize>) {
356 self.sendable_plaintext.set_limit(limit);
357 self.sendable_tls.set_limit(limit);
358 }
359
360 /// Send any buffered plaintext. Plaintext is buffered if
361 /// written during handshake.
362 fn flush_plaintext(&mut self) {
363 if !self.may_send_application_data {
364 return;
365 }
366
367 while let Some(buf) = self.sendable_plaintext.pop() {
368 self.send_plain(&buf, Limit::No);
369 }
370 }
371
372 // Put m into sendable_tls for writing.
373 fn queue_tls_message(&mut self, m: OpaqueMessage) {
374 self.sendable_tls.append(m.encode());
375 }
376
377 /// Send a raw TLS message, fragmenting it if needed.
378 pub(crate) fn send_msg(&mut self, m: Message, must_encrypt: bool) {
379 {
380 if let Protocol::Quic = self.protocol {
381 if let MessagePayload::Alert(alert) = m.payload {
382 self.quic.alert = Some(alert.description);
383 } else {
384 debug_assert!(
385 matches!(m.payload, MessagePayload::Handshake { .. }),
386 "QUIC uses TLS for the cryptographic handshake only"
387 );
388 let mut bytes = Vec::new();
389 m.payload.encode(&mut bytes);
390 self.quic
391 .hs_queue
392 .push_back((must_encrypt, bytes));
393 }
394 return;
395 }
396 }
397 if !must_encrypt {
398 let msg = &m.into();
399 let iter = self
400 .message_fragmenter
401 .fragment_message(msg);
402 for m in iter {
403 self.queue_tls_message(m.to_unencrypted_opaque());
404 }
405 } else {
406 self.send_msg_encrypt(m.into());
407 }
408 }
409
410 pub(crate) fn take_received_plaintext(&mut self, bytes: Payload) {
411 self.received_plaintext.append(bytes.0);
412 }
413
414 #[cfg(feature = "tls12")]
415 pub(crate) fn start_encryption_tls12(&mut self, secrets: &ConnectionSecrets, side: Side) {
416 let (dec, enc) = secrets.make_cipher_pair(side);
417 self.record_layer
418 .prepare_message_encrypter(enc);
419 self.record_layer
420 .prepare_message_decrypter(dec);
421 }
422
423 pub(crate) fn missing_extension(&mut self, why: PeerMisbehaved) -> Error {
424 self.send_fatal_alert(AlertDescription::MissingExtension, why)
425 }
426
427 fn send_warning_alert(&mut self, desc: AlertDescription) {
428 warn!("Sending warning alert {:?}", desc);
429 self.send_warning_alert_no_log(desc);
430 }
431
432 pub(crate) fn process_alert(&mut self, alert: &AlertMessagePayload) -> Result<(), Error> {
433 // Reject unknown AlertLevels.
434 if let AlertLevel::Unknown(_) = alert.level {
435 return Err(self.send_fatal_alert(
436 AlertDescription::IllegalParameter,
437 Error::AlertReceived(alert.description),
438 ));
439 }
440
441 // If we get a CloseNotify, make a note to declare EOF to our
442 // caller.
443 if alert.description == AlertDescription::CloseNotify {
444 self.has_received_close_notify = true;
445 return Ok(());
446 }
447
448 // Warnings are nonfatal for TLS1.2, but outlawed in TLS1.3
449 // (except, for no good reason, user_cancelled).
450 let err = Error::AlertReceived(alert.description);
451 if alert.level == AlertLevel::Warning {
452 if self.is_tls13() && alert.description != AlertDescription::UserCanceled {
453 return Err(self.send_fatal_alert(AlertDescription::DecodeError, err));
454 } else {
455 warn!("TLS alert warning received: {:#?}", alert);
456 return Ok(());
457 }
458 }
459
460 Err(err)
461 }
462
463 pub(crate) fn send_cert_verify_error_alert(&mut self, err: Error) -> Error {
464 self.send_fatal_alert(
465 match &err {
466 Error::InvalidCertificate(e) => e.clone().into(),
467 Error::PeerMisbehaved(_) => AlertDescription::IllegalParameter,
468 _ => AlertDescription::HandshakeFailure,
469 },
470 err,
471 )
472 }
473
474 pub(crate) fn send_fatal_alert(
475 &mut self,
476 desc: AlertDescription,
477 err: impl Into<Error>,
478 ) -> Error {
479 debug_assert!(!self.sent_fatal_alert);
480 let m = Message::build_alert(AlertLevel::Fatal, desc);
481 self.send_msg(m, self.record_layer.is_encrypting());
482 self.sent_fatal_alert = true;
483 err.into()
484 }
485
486 /// Queues a close_notify warning alert to be sent in the next
487 /// [`Connection::write_tls`] call. This informs the peer that the
488 /// connection is being closed.
489 ///
490 /// [`Connection::write_tls`]: crate::Connection::write_tls
491 pub fn send_close_notify(&mut self) {
492 debug!("Sending warning alert {:?}", AlertDescription::CloseNotify);
493 self.send_warning_alert_no_log(AlertDescription::CloseNotify);
494 }
495
496 fn send_warning_alert_no_log(&mut self, desc: AlertDescription) {
497 let m = Message::build_alert(AlertLevel::Warning, desc);
498 self.send_msg(m, self.record_layer.is_encrypting());
499 }
500
501 pub(crate) fn set_max_fragment_size(&mut self, new: Option<usize>) -> Result<(), Error> {
502 self.message_fragmenter
503 .set_max_fragment_size(new)
504 }
505
506 pub(crate) fn get_alpn_protocol(&self) -> Option<&[u8]> {
507 self.alpn_protocol
508 .as_ref()
509 .map(AsRef::as_ref)
510 }
511
512 /// Returns true if the caller should call [`Connection::read_tls`] as soon
513 /// as possible.
514 ///
515 /// If there is pending plaintext data to read with [`Connection::reader`],
516 /// this returns false. If your application respects this mechanism,
517 /// only one full TLS message will be buffered by rustls.
518 ///
519 /// [`Connection::reader`]: crate::Connection::reader
520 /// [`Connection::read_tls`]: crate::Connection::read_tls
521 pub fn wants_read(&self) -> bool {
522 // We want to read more data all the time, except when we have unprocessed plaintext.
523 // This provides back-pressure to the TCP buffers. We also don't want to read more after
524 // the peer has sent us a close notification.
525 //
526 // In the handshake case we don't have readable plaintext before the handshake has
527 // completed, but also don't want to read if we still have sendable tls.
528 self.received_plaintext.is_empty()
529 && !self.has_received_close_notify
530 && (self.may_send_application_data || self.sendable_tls.is_empty())
531 }
532
533 pub(crate) fn current_io_state(&self) -> IoState {
534 IoState {
535 tls_bytes_to_write: self.sendable_tls.len(),
536 plaintext_bytes_to_read: self.received_plaintext.len(),
537 peer_has_closed: self.has_received_close_notify,
538 }
539 }
540
541 pub(crate) fn is_quic(&self) -> bool {
542 self.protocol == Protocol::Quic
543 }
544
545 pub(crate) fn should_update_key(
546 &mut self,
547 key_update_request: &KeyUpdateRequest,
548 ) -> Result<bool, Error> {
549 match key_update_request {
550 KeyUpdateRequest::UpdateNotRequested => Ok(false),
551 KeyUpdateRequest::UpdateRequested => Ok(self.queued_key_update_message.is_none()),
552 _ => Err(self.send_fatal_alert(
553 AlertDescription::IllegalParameter,
554 InvalidMessage::InvalidKeyUpdate,
555 )),
556 }
557 }
558
559 pub(crate) fn enqueue_key_update_notification(&mut self) {
560 let message = PlainMessage::from(Message::build_key_update_notify());
561 self.queued_key_update_message = Some(
562 self.record_layer
563 .encrypt_outgoing(message.borrow())
564 .encode(),
565 );
566 }
567
568 pub(crate) fn perhaps_write_key_update(&mut self) {
569 if let Some(message) = self.queued_key_update_message.take() {
570 self.sendable_tls.append(message);
571 }
572 }
573}
574
575/// Values of this structure are returned from [`Connection::process_new_packets`]
576/// and tell the caller the current I/O state of the TLS connection.
577///
578/// [`Connection::process_new_packets`]: crate::Connection::process_new_packets
579#[derive(Debug, Eq, PartialEq)]
580pub struct IoState {
581 tls_bytes_to_write: usize,
582 plaintext_bytes_to_read: usize,
583 peer_has_closed: bool,
584}
585
586impl IoState {
587 /// How many bytes could be written by [`Connection::write_tls`] if called
588 /// right now. A non-zero value implies [`CommonState::wants_write`].
589 ///
590 /// [`Connection::write_tls`]: crate::Connection::write_tls
591 pub fn tls_bytes_to_write(&self) -> usize {
592 self.tls_bytes_to_write
593 }
594
595 /// How many plaintext bytes could be obtained via [`std::io::Read`]
596 /// without further I/O.
597 pub fn plaintext_bytes_to_read(&self) -> usize {
598 self.plaintext_bytes_to_read
599 }
600
601 /// True if the peer has sent us a close_notify alert. This is
602 /// the TLS mechanism to securely half-close a TLS connection,
603 /// and signifies that the peer will not send any further data
604 /// on this connection.
605 ///
606 /// This is also signalled via returning `Ok(0)` from
607 /// [`std::io::Read`], after all the received bytes have been
608 /// retrieved.
609 pub fn peer_has_closed(&self) -> bool {
610 self.peer_has_closed
611 }
612}
613
614pub(crate) trait State<Data>: Send + Sync {
615 fn handle(
616 self: Box<Self>,
617 cx: &mut Context<'_, Data>,
618 message: Message,
619 ) -> Result<Box<dyn State<Data>>, Error>;
620
621 fn export_keying_material(
622 &self,
623 _output: &mut [u8],
624 _label: &[u8],
625 _context: Option<&[u8]>,
626 ) -> Result<(), Error> {
627 Err(Error::HandshakeNotComplete)
628 }
629
630 fn extract_secrets(&self) -> Result<PartiallyExtractedSecrets, Error> {
631 Err(Error::HandshakeNotComplete)
632 }
633
634 fn handle_decrypt_error(&self) {}
635}
636
637pub(crate) struct Context<'a, Data> {
638 pub(crate) common: &'a mut CommonState,
639 pub(crate) data: &'a mut Data,
640}
641
642/// Side of the connection.
643#[derive(Clone, Copy, Debug, PartialEq)]
644pub enum Side {
645 /// A client initiates the connection.
646 Client,
647 /// A server waits for a client to connect.
648 Server,
649}
650
651impl Side {
652 pub(crate) fn peer(&self) -> Self {
653 match self {
654 Self::Client => Self::Server,
655 Self::Server => Self::Client,
656 }
657 }
658}
659
660#[derive(Copy, Clone, Eq, PartialEq, Debug)]
661pub(crate) enum Protocol {
662 Tcp,
663 Quic,
664}
665
666enum Limit {
667 Yes,
668 No,
669}
670
671const DEFAULT_RECEIVED_PLAINTEXT_LIMIT: usize = 16 * 1024;
672const DEFAULT_BUFFER_LIMIT: usize = 64 * 1024;
673