rustls/
common_state.rs

1use alloc::boxed::Box;
2use alloc::vec::Vec;
3use core::fmt;
4use core::ops::{Deref, DerefMut, Range};
5
6use pki_types::{DnsName, FipsStatus};
7
8use crate::client::EchStatus;
9use crate::conn::{Exporter, ReceivePath, SendOutput, SendPath};
10use crate::crypto::Identity;
11use crate::crypto::cipher::Payload;
12use crate::crypto::kx::SupportedKxGroup;
13use crate::enums::{ApplicationProtocol, ProtocolVersion};
14use crate::error::{AlertDescription, Error};
15use crate::hash_hs::HandshakeHash;
16use crate::msgs::{
17    AlertLevel, Codec, Delocator, HandshakeMessagePayload, Locator, Message, MessagePayload,
18};
19use crate::quic::{self, QuicOutput};
20use crate::suites::SupportedCipherSuite;
21
22/// Connection state common to both client and server connections.
23pub struct CommonState {
24    pub(crate) outputs: ConnectionOutputs,
25    pub(crate) send: SendPath,
26    pub(crate) recv: ReceivePath,
27    pub(crate) fips: FipsStatus,
28}
29
30impl CommonState {
31    pub(crate) fn new(side: Side, fips: FipsStatus) -> Self {
32        Self {
33            outputs: ConnectionOutputs::default(),
34            send: SendPath::default(),
35            recv: ReceivePath::new(side),
36            fips,
37        }
38    }
39
40    /// Returns true if the caller should call [`Connection::write_tls`] as soon as possible.
41    ///
42    /// [`Connection::write_tls`]: crate::Connection::write_tls
43    pub fn wants_write(&self) -> bool {
44        !self.send.sendable_tls.is_empty()
45    }
46
47    /// Queues a `close_notify` warning alert to be sent in the next
48    /// [`Connection::write_tls`] call.  This informs the peer that the
49    /// connection is being closed.
50    ///
51    /// Does nothing if any `close_notify` or fatal alert was already sent.
52    ///
53    /// [`Connection::write_tls`]: crate::Connection::write_tls
54    pub fn send_close_notify(&mut self) {
55        self.send.send_close_notify()
56    }
57
58    /// Returns true if the connection is currently performing the TLS handshake.
59    ///
60    /// During this time plaintext written to the connection is buffered in memory. After
61    /// [`Connection::process_new_packets()`] has been called, this might start to return `false`
62    /// while the final handshake packets still need to be extracted from the connection's buffers.
63    ///
64    /// [`Connection::process_new_packets()`]: crate::Connection::process_new_packets
65    pub fn is_handshaking(&self) -> bool {
66        !(self.send.may_send_application_data && self.recv.may_receive_application_data)
67    }
68}
69
70impl Deref for CommonState {
71    type Target = ConnectionOutputs;
72
73    fn deref(&self) -> &Self::Target {
74        &self.outputs
75    }
76}
77
78impl DerefMut for CommonState {
79    fn deref_mut(&mut self) -> &mut Self::Target {
80        &mut self.outputs
81    }
82}
83
84impl fmt::Debug for CommonState {
85    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86        f.debug_struct("CommonState")
87            .finish_non_exhaustive()
88    }
89}
90
91/// Facts about the connection learned through the handshake.
92#[derive(Default)]
93pub struct ConnectionOutputs {
94    negotiated_version: Option<ProtocolVersion>,
95    handshake_kind: Option<HandshakeKind>,
96    suite: Option<SupportedCipherSuite>,
97    negotiated_kx_group: Option<&'static dyn SupportedKxGroup>,
98    alpn_protocol: Option<ApplicationProtocol<'static>>,
99    peer_identity: Option<Identity<'static>>,
100    extended_master_secret: Option<bool>,
101    pub(crate) exporter: Option<Box<dyn Exporter>>,
102    pub(crate) early_exporter: Option<Box<dyn Exporter>>,
103}
104
105impl ConnectionOutputs {
106    /// Retrieves the certificate chain or the raw public key used by the peer to authenticate.
107    ///
108    /// This is made available for both full and resumed handshakes.
109    ///
110    /// For clients, this is the identity of the server. For servers, this is the identity of the
111    /// client, if client authentication was completed.
112    ///
113    /// The return value is None until this value is available.
114    pub fn peer_identity(&self) -> Option<&Identity<'static>> {
115        self.peer_identity.as_ref()
116    }
117
118    /// Retrieves the protocol agreed with the peer via ALPN.
119    ///
120    /// A return value of `None` after handshake completion
121    /// means no protocol was agreed (because no protocols
122    /// were offered or accepted by the peer).
123    pub fn alpn_protocol(&self) -> Option<&ApplicationProtocol<'static>> {
124        self.alpn_protocol.as_ref()
125    }
126
127    /// Retrieves the cipher suite agreed with the peer.
128    ///
129    /// This returns None until the cipher suite is agreed.
130    pub fn negotiated_cipher_suite(&self) -> Option<SupportedCipherSuite> {
131        self.suite
132    }
133
134    /// Retrieves the key exchange group agreed with the peer.
135    ///
136    /// This function may return `None` depending on the state of the connection,
137    /// the type of handshake, and the protocol version.
138    ///
139    /// If [`CommonState::is_handshaking()`] is true this function will return `None`.
140    /// Similarly, if the [`ConnectionOutputs::handshake_kind()`] is [`HandshakeKind::Resumed`]
141    /// and the [`ConnectionOutputs::protocol_version()`] is TLS 1.2, then no key exchange will have
142    /// occurred and this function will return `None`.
143    pub fn negotiated_key_exchange_group(&self) -> Option<&'static dyn SupportedKxGroup> {
144        self.negotiated_kx_group
145    }
146
147    /// Retrieves the protocol version agreed with the peer.
148    ///
149    /// This returns `None` until the version is agreed.
150    pub fn protocol_version(&self) -> Option<ProtocolVersion> {
151        self.negotiated_version
152    }
153
154    /// Whether the Extended Master Secret extension was negotiated.
155    ///
156    /// Returns:
157    /// - `None` until the handshake reaches the point where this is known.
158    /// - `None` for TLS 1.3, where the extension does not apply.
159    /// - `Some(true)` for TLS 1.2 if the extension was negotiated.
160    /// - `Some(false)` otherwise.
161    pub fn extended_master_secret(&self) -> Option<bool> {
162        self.extended_master_secret
163    }
164
165    /// Which kind of handshake was performed.
166    ///
167    /// This tells you whether the handshake was a resumption or not.
168    ///
169    /// This will return `None` before it is known which sort of
170    /// handshake occurred.
171    pub fn handshake_kind(&self) -> Option<HandshakeKind> {
172        self.handshake_kind
173    }
174
175    pub(super) fn into_kernel_parts(self) -> Option<(ProtocolVersion, SupportedCipherSuite)> {
176        let Self {
177            negotiated_version,
178            suite,
179            ..
180        } = self;
181
182        match (negotiated_version, suite) {
183            (Some(version), Some(suite)) => Some((version, suite)),
184            _ => None,
185        }
186    }
187}
188
189impl ConnectionOutput for ConnectionOutputs {
190    fn handle(&mut self, ev: OutputEvent<'_>) {
191        match ev {
192            OutputEvent::ApplicationProtocol(protocol) => {
193                self.alpn_protocol = Some(ApplicationProtocol::from(protocol.as_ref()).to_owned())
194            }
195            OutputEvent::CipherSuite(suite) => self.suite = Some(suite),
196            OutputEvent::EarlyExporter(exporter) => self.early_exporter = Some(exporter),
197            OutputEvent::Exporter(exporter) => self.exporter = Some(exporter),
198            OutputEvent::ExtendedMasterSecret(ems) => self.extended_master_secret = Some(ems),
199            OutputEvent::HandshakeKind(hk) => {
200                assert!(self.handshake_kind.is_none());
201                self.handshake_kind = Some(hk);
202            }
203            OutputEvent::KeyExchangeGroup(kxg) => {
204                assert!(self.negotiated_kx_group.is_none());
205                self.negotiated_kx_group = Some(kxg);
206            }
207            OutputEvent::PeerIdentity(identity) => self.peer_identity = Some(identity),
208            OutputEvent::ProtocolVersion(ver) => {
209                self.negotiated_version = Some(ver);
210            }
211        }
212    }
213}
214
215/// Send an alert via `output` if `error` specifies one.
216pub(crate) fn maybe_send_fatal_alert(send: &mut dyn SendOutput, error: &Error) {
217    let Ok(alert) = AlertDescription::try_from(error) else {
218        return;
219    };
220    send.send_alert(AlertLevel::Fatal, alert);
221}
222
223/// Describes which sort of handshake happened.
224#[derive(Debug, PartialEq, Clone, Copy)]
225#[non_exhaustive]
226pub enum HandshakeKind {
227    /// A full handshake.
228    ///
229    /// This is the typical TLS connection initiation process when resumption is
230    /// not available, and the initial `ClientHello` was accepted by the server.
231    Full,
232
233    /// A full TLS1.3 handshake, with an extra round-trip for a `HelloRetryRequest`.
234    ///
235    /// The server can respond with a `HelloRetryRequest` if the initial `ClientHello`
236    /// is unacceptable for several reasons, the most likely being if no supported key
237    /// shares were offered by the client.
238    FullWithHelloRetryRequest,
239
240    /// A resumed handshake.
241    ///
242    /// Resumed handshakes involve fewer round trips and less cryptography than
243    /// full ones, but can only happen when the peers have previously done a full
244    /// handshake together, and then remember data about it.
245    Resumed,
246
247    /// A resumed handshake, with an extra round-trip for a `HelloRetryRequest`.
248    ///
249    /// The server can respond with a `HelloRetryRequest` if the initial `ClientHello`
250    /// is unacceptable for several reasons, but this does not prevent the client
251    /// from resuming.
252    ResumedWithHelloRetryRequest,
253}
254
255/// The route for handshake state machine to surface determinations about the connection.
256pub(crate) trait Output<'m> {
257    fn emit(&mut self, ev: Event<'_>);
258
259    fn output(&mut self, ev: OutputEvent<'_>);
260
261    fn send_msg(&mut self, m: Message<'_>, must_encrypt: bool);
262
263    fn quic(&mut self) -> Option<&mut dyn QuicOutput> {
264        None
265    }
266
267    fn received_plaintext(&mut self, _payload: Payload<'m>) {}
268
269    fn start_traffic(&mut self);
270
271    fn receive(&mut self) -> &mut ReceivePath;
272
273    fn send(&mut self) -> &mut dyn SendOutput;
274}
275
276pub(crate) trait ConnectionOutput {
277    fn handle(&mut self, ev: OutputEvent<'_>);
278}
279
280/// The set of events output by the low-level handshake state machine.
281pub(crate) enum Event<'a> {
282    EarlyApplicationData(Payload<'a>),
283    EarlyData(EarlyDataEvent),
284    EchStatus(EchStatus),
285    ReceivedServerName(Option<DnsName<'static>>),
286    ResumptionData(Vec<u8>),
287}
288
289pub(crate) enum OutputEvent<'a> {
290    ApplicationProtocol(ApplicationProtocol<'a>),
291    CipherSuite(SupportedCipherSuite),
292    EarlyExporter(Box<dyn Exporter>),
293    Exporter(Box<dyn Exporter>),
294    ExtendedMasterSecret(bool),
295    HandshakeKind(HandshakeKind),
296    KeyExchangeGroup(&'static dyn SupportedKxGroup),
297    PeerIdentity(Identity<'static>),
298    ProtocolVersion(ProtocolVersion),
299}
300
301pub(crate) enum EarlyDataEvent {
302    /// server: we accepted an early_data offer
303    Accepted,
304    /// client: declares the maximum amount of early data that can be sent
305    Enable(usize),
306    /// client: early data can now be sent using the record layer as normal
307    Start,
308    /// client: early data phase has closed after sending EndOfEarlyData
309    Finished,
310    /// client: the server rejected our request for early data
311    Rejected,
312}
313
314/// Lifetime-erased equivalent to [`Payload`]
315///
316/// Stores an index into [`Payload`] buffer enabling in-place decryption
317/// without holding a lifetime to the receive buffer.
318pub(crate) enum UnborrowedPayload {
319    Unborrowed(Range<usize>),
320    Owned(Vec<u8>),
321}
322
323impl UnborrowedPayload {
324    /// Convert [`Payload`] into [`UnborrowedPayload`] which stores a range
325    /// into the [`Payload`] slice without borrowing such that it can be later
326    /// reborrowed.
327    ///
328    /// # Panics
329    ///
330    /// Passed [`Locator`] must have been created from the same slice which
331    /// contains the payload.
332    pub(crate) fn unborrow(locator: &Locator, payload: Payload<'_>) -> Self {
333        match payload {
334            Payload::Borrowed(payload) => Self::Unborrowed(locator.locate(payload)),
335            Payload::Owned(payload) => Self::Owned(payload),
336        }
337    }
338
339    /// Convert [`UnborrowedPayload`] back into [`Payload`]
340    ///
341    /// # Panics
342    ///
343    /// Passed [`Delocator`] must have been created from the same slice that
344    /// [`UnborrowedPayload`] was originally unborrowed from.
345    pub(crate) fn reborrow<'b>(self, delocator: &Delocator<'b>) -> Payload<'b> {
346        match self {
347            Self::Unborrowed(range) => Payload::Borrowed(delocator.slice_from_range(&range)),
348            Self::Owned(payload) => Payload::Owned(payload),
349        }
350    }
351}
352
353/// Side of the connection.
354#[expect(clippy::exhaustive_enums)]
355#[derive(Clone, Copy, Debug, PartialEq)]
356pub enum Side {
357    /// A client initiates the connection.
358    Client,
359    /// A server waits for a client to connect.
360    Server,
361}
362
363#[derive(Copy, Clone, Eq, PartialEq, Debug)]
364pub(crate) enum Protocol {
365    /// TCP-TLS, standardized in RFC5246 and RFC8446
366    Tcp,
367    /// QUIC, standardized in RFC9001
368    Quic(quic::Version),
369}
370
371impl Protocol {
372    pub(crate) fn is_quic(&self) -> bool {
373        matches!(self, Self::Quic(_))
374    }
375}
376
377pub(crate) struct HandshakeFlight<'a, const TLS13: bool> {
378    pub(crate) transcript: &'a mut HandshakeHash,
379    body: Vec<u8>,
380}
381
382impl<'a, const TLS13: bool> HandshakeFlight<'a, TLS13> {
383    pub(crate) fn new(transcript: &'a mut HandshakeHash) -> Self {
384        Self {
385            transcript,
386            body: Vec::new(),
387        }
388    }
389
390    pub(crate) fn add(&mut self, hs: HandshakeMessagePayload<'_>) {
391        let start_len = self.body.len();
392        hs.encode(&mut self.body);
393        self.transcript
394            .add(&self.body[start_len..]);
395    }
396
397    pub(crate) fn finish(self, output: &mut dyn Output<'_>) {
398        let m = Message {
399            version: match TLS13 {
400                true => ProtocolVersion::TLSv1_3,
401                false => ProtocolVersion::TLSv1_2,
402            },
403            payload: MessagePayload::HandshakeFlight(Payload::new(self.body)),
404        };
405
406        output.send_msg(m, TLS13);
407    }
408}
409
410pub(crate) type HandshakeFlightTls12<'a> = HandshakeFlight<'a, false>;
411pub(crate) type HandshakeFlightTls13<'a> = HandshakeFlight<'a, true>;
rustls/common_state.rs

rustls/
common_state.rs
