rustls/client/
connection.rs

1use alloc::vec::Vec;
2use core::ops::Deref;
3use core::{fmt, mem};
4use std::io;
5
6use pki_types::{FipsStatus, ServerName};
7
8use super::config::ClientConfig;
9use super::hs::ClientHelloInput;
10use crate::client::EchStatus;
11use crate::common_state::{CommonState, ConnectionOutputs, EarlyDataEvent, Event, Protocol, Side};
12use crate::conn::private::SideOutput;
13use crate::conn::{
14    Connection, ConnectionCommon, ConnectionCore, IoState, KeyingMaterialExporter, Reader,
15    SideCommonOutput, Writer,
16};
17#[cfg(doc)]
18use crate::crypto;
19use crate::enums::ApplicationProtocol;
20use crate::error::Error;
21use crate::log::trace;
22use crate::msgs::ClientExtensionsInput;
23use crate::quic::QuicOutput;
24use crate::suites::ExtractedSecrets;
25use crate::sync::Arc;
26
27/// This represents a single TLS client connection.
28pub struct ClientConnection {
29    inner: ConnectionCommon<ClientSide>,
30}
31
32impl fmt::Debug for ClientConnection {
33    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
34        f.debug_struct("ClientConnection")
35            .finish_non_exhaustive()
36    }
37}
38
39impl ClientConnection {
40    /// Returns an `io::Write` implementer you can write bytes to
41    /// to send TLS1.3 early data (a.k.a. "0-RTT data") to the server.
42    ///
43    /// This returns None in many circumstances when the capability to
44    /// send early data is not available, including but not limited to:
45    ///
46    /// - The server hasn't been talked to previously.
47    /// - The server does not support resumption.
48    /// - The server does not support early data.
49    /// - The resumption data for the server has expired.
50    ///
51    /// The server specifies a maximum amount of early data.  You can
52    /// learn this limit through the returned object, and writes through
53    /// it will process only this many bytes.
54    ///
55    /// The server can choose not to accept any sent early data --
56    /// in this case the data is lost but the connection continues.  You
57    /// can tell this happened using `is_early_data_accepted`.
58    pub fn early_data(&mut self) -> Option<WriteEarlyData<'_>> {
59        if self
60            .inner
61            .core
62            .side
63            .early_data
64            .is_enabled()
65        {
66            Some(WriteEarlyData::new(self))
67        } else {
68            None
69        }
70    }
71
72    /// Returns True if the server signalled it will process early data.
73    ///
74    /// If you sent early data and this returns false at the end of the
75    /// handshake then the server will not process the data.  This
76    /// is not an error, but you may wish to resend the data.
77    pub fn is_early_data_accepted(&self) -> bool {
78        self.inner.core.is_early_data_accepted()
79    }
80
81    /// Return the connection's Encrypted Client Hello (ECH) status.
82    pub fn ech_status(&self) -> EchStatus {
83        self.inner.core.side.ech_status
84    }
85
86    fn write_early_data(&mut self, data: &[u8]) -> io::Result<usize> {
87        self.inner
88            .core
89            .side
90            .early_data
91            .check_write(data.len())
92            .map(|sz| {
93                self.inner
94                    .send
95                    .send_early_plaintext(&data[..sz])
96            })
97    }
98
99    /// Returns the number of TLS1.3 tickets that have been received.
100    pub fn tls13_tickets_received(&self) -> u32 {
101        self.inner
102            .core
103            .common
104            .recv
105            .tls13_tickets_received
106    }
107}
108
109impl Connection for ClientConnection {
110    fn read_tls(&mut self, rd: &mut dyn io::Read) -> Result<usize, io::Error> {
111        self.inner.read_tls(rd)
112    }
113
114    fn write_tls(&mut self, wr: &mut dyn io::Write) -> Result<usize, io::Error> {
115        self.inner.write_tls(wr)
116    }
117
118    fn wants_read(&self) -> bool {
119        self.inner.wants_read()
120    }
121
122    fn wants_write(&self) -> bool {
123        self.inner.wants_write()
124    }
125
126    fn reader(&mut self) -> Reader<'_> {
127        self.inner.reader()
128    }
129
130    fn writer(&mut self) -> Writer<'_> {
131        self.inner.writer()
132    }
133
134    fn process_new_packets(&mut self) -> Result<IoState, Error> {
135        self.inner.process_new_packets()
136    }
137
138    fn exporter(&mut self) -> Result<KeyingMaterialExporter, Error> {
139        self.inner.exporter()
140    }
141
142    fn dangerous_extract_secrets(self) -> Result<ExtractedSecrets, Error> {
143        self.inner.dangerous_extract_secrets()
144    }
145
146    fn set_buffer_limit(&mut self, limit: Option<usize>) {
147        self.inner.set_buffer_limit(limit)
148    }
149
150    fn set_plaintext_buffer_limit(&mut self, limit: Option<usize>) {
151        self.inner
152            .set_plaintext_buffer_limit(limit)
153    }
154
155    fn refresh_traffic_keys(&mut self) -> Result<(), Error> {
156        self.inner.refresh_traffic_keys()
157    }
158
159    fn send_close_notify(&mut self) {
160        self.inner.send_close_notify();
161    }
162
163    fn is_handshaking(&self) -> bool {
164        self.inner.is_handshaking()
165    }
166
167    fn fips(&self) -> FipsStatus {
168        self.inner.fips
169    }
170}
171
172impl Deref for ClientConnection {
173    type Target = ConnectionOutputs;
174
175    fn deref(&self) -> &Self::Target {
176        &self.inner
177    }
178}
179
180/// Builder for [`ClientConnection`] values.
181///
182/// Create one with [`ClientConfig::connect()`].
183pub struct ClientConnectionBuilder {
184    pub(crate) config: Arc<ClientConfig>,
185    pub(crate) name: ServerName<'static>,
186    pub(crate) alpn_protocols: Option<Vec<ApplicationProtocol<'static>>>,
187}
188
189impl ClientConnectionBuilder {
190    /// Specify the ALPN protocols to use for this connection.
191    pub fn with_alpn(mut self, alpn_protocols: Vec<ApplicationProtocol<'static>>) -> Self {
192        self.alpn_protocols = Some(alpn_protocols);
193        self
194    }
195
196    /// Finalize the builder and create the `ClientConnection`.
197    pub fn build(self) -> Result<ClientConnection, Error> {
198        let Self {
199            config,
200            name,
201            alpn_protocols,
202        } = self;
203
204        let alpn_protocols = alpn_protocols.unwrap_or_else(|| config.alpn_protocols.clone());
205        Ok(ClientConnection {
206            inner: ConnectionCommon::new(ConnectionCore::for_client(
207                config,
208                name,
209                ClientExtensionsInput::from_alpn(alpn_protocols),
210                None,
211                Protocol::Tcp,
212            )?),
213        })
214    }
215}
216
217/// Allows writing of early data in resumed TLS 1.3 connections.
218///
219/// "Early data" is also known as "0-RTT data".
220///
221/// This type implements [`io::Write`].
222pub struct WriteEarlyData<'a> {
223    sess: &'a mut ClientConnection,
224}
225
226impl<'a> WriteEarlyData<'a> {
227    fn new(sess: &'a mut ClientConnection) -> Self {
228        WriteEarlyData { sess }
229    }
230
231    /// How many bytes you may send.  Writes will become short
232    /// once this reaches zero.
233    pub fn bytes_left(&self) -> usize {
234        self.sess
235            .inner
236            .core
237            .side
238            .early_data
239            .bytes_left()
240    }
241
242    /// Returns the "early" exporter that can derive key material for use in early data
243    ///
244    /// See [RFC5705][] for general details on what exporters are, and [RFC8446 S7.5][] for
245    /// specific details on the "early" exporter.
246    ///
247    /// **Beware** that the early exporter requires care, as it is subject to the same
248    /// potential for replay as early data itself.  See [RFC8446 appendix E.5.1][] for
249    /// more detail.
250    ///
251    /// This function can be called at most once per connection. This function will error:
252    /// if called more than once per connection.
253    ///
254    /// If you are looking for the normal exporter, this is available from
255    /// [`Connection::exporter()`].
256    ///
257    /// [RFC5705]: https://datatracker.ietf.org/doc/html/rfc5705
258    /// [RFC8446 S7.5]: https://datatracker.ietf.org/doc/html/rfc8446#section-7.5
259    /// [RFC8446 appendix E.5.1]: https://datatracker.ietf.org/doc/html/rfc8446#appendix-E.5.1
260    /// [`Connection::exporter()`]: crate::conn::Connection::exporter()
261    pub fn exporter(&mut self) -> Result<KeyingMaterialExporter, Error> {
262        self.sess.inner.core.early_exporter()
263    }
264}
265
266impl io::Write for WriteEarlyData<'_> {
267    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
268        self.sess.write_early_data(buf)
269    }
270
271    fn flush(&mut self) -> io::Result<()> {
272        Ok(())
273    }
274}
275
276impl ConnectionCore<ClientSide> {
277    pub(crate) fn for_client(
278        config: Arc<ClientConfig>,
279        name: ServerName<'static>,
280        extra_exts: ClientExtensionsInput,
281        quic: Option<&mut dyn QuicOutput>,
282        protocol: Protocol,
283    ) -> Result<Self, Error> {
284        let mut common_state = CommonState::new(Side::Client, config.fips());
285        common_state
286            .send
287            .set_max_fragment_size(config.max_fragment_size)?;
288        let mut data = ClientConnectionData::new();
289
290        let mut output = SideCommonOutput {
291            side: &mut data,
292            quic,
293            common: &mut common_state,
294        };
295
296        let input = ClientHelloInput::new(name, &extra_exts, protocol, &mut output, config)?;
297        let state = input.start_handshake(extra_exts, &mut output)?;
298
299        Ok(Self::new(state, data, common_state))
300    }
301
302    pub(crate) fn is_early_data_accepted(&self) -> bool {
303        self.side.early_data.is_accepted()
304    }
305}
306
307pub(super) struct EarlyData {
308    state: EarlyDataState,
309    left: usize,
310}
311
312impl EarlyData {
313    fn new() -> Self {
314        Self {
315            state: EarlyDataState::Disabled,
316            left: 0,
317        }
318    }
319
320    fn is_enabled(&self) -> bool {
321        matches!(
322            self.state,
323            EarlyDataState::Ready | EarlyDataState::Sending | EarlyDataState::Accepted
324        )
325    }
326
327    fn is_accepted(&self) -> bool {
328        matches!(
329            self.state,
330            EarlyDataState::Accepted | EarlyDataState::AcceptedFinished
331        )
332    }
333
334    fn enable(&mut self, max_data: usize) {
335        assert_eq!(self.state, EarlyDataState::Disabled);
336        self.state = EarlyDataState::Ready;
337        self.left = max_data;
338    }
339
340    fn start(&mut self) {
341        assert_eq!(self.state, EarlyDataState::Ready);
342        self.state = EarlyDataState::Sending;
343    }
344
345    fn rejected(&mut self) {
346        trace!("EarlyData rejected");
347        self.state = EarlyDataState::Rejected;
348    }
349
350    fn accepted(&mut self) {
351        trace!("EarlyData accepted");
352        assert_eq!(self.state, EarlyDataState::Sending);
353        self.state = EarlyDataState::Accepted;
354    }
355
356    pub(super) fn finished(&mut self) {
357        trace!("EarlyData finished");
358        self.state = match self.state {
359            EarlyDataState::Accepted => EarlyDataState::AcceptedFinished,
360            _ => panic!("bad EarlyData state"),
361        }
362    }
363
364    fn check_write(&mut self, sz: usize) -> io::Result<usize> {
365        self.check_write_opt(sz)
366            .ok_or_else(|| io::Error::from(io::ErrorKind::InvalidInput))
367    }
368
369    fn check_write_opt(&mut self, sz: usize) -> Option<usize> {
370        match self.state {
371            EarlyDataState::Disabled => unreachable!(),
372            EarlyDataState::Ready | EarlyDataState::Sending | EarlyDataState::Accepted => {
373                let take = if self.left < sz {
374                    mem::replace(&mut self.left, 0)
375                } else {
376                    self.left -= sz;
377                    sz
378                };
379
380                Some(take)
381            }
382            EarlyDataState::Rejected | EarlyDataState::AcceptedFinished => None,
383        }
384    }
385
386    fn bytes_left(&self) -> usize {
387        self.left
388    }
389}
390
391#[derive(Debug, PartialEq)]
392enum EarlyDataState {
393    Disabled,
394    Ready,
395    Sending,
396    Accepted,
397    AcceptedFinished,
398    Rejected,
399}
400
401pub(crate) struct ClientConnectionData {
402    early_data: EarlyData,
403    ech_status: EchStatus,
404}
405
406impl ClientConnectionData {
407    fn new() -> Self {
408        Self {
409            early_data: EarlyData::new(),
410            ech_status: EchStatus::default(),
411        }
412    }
413}
414
415/// State associated with a client connection.
416#[expect(clippy::exhaustive_structs)]
417#[derive(Debug)]
418pub struct ClientSide;
419
420impl crate::conn::SideData for ClientSide {}
421
422impl crate::conn::private::Side for ClientSide {
423    type Data = ClientConnectionData;
424    type State = super::hs::ClientState;
425}
426
427impl SideOutput for ClientConnectionData {
428    fn emit(&mut self, ev: Event<'_>) {
429        match ev {
430            Event::EchStatus(ech) => self.ech_status = ech,
431            Event::EarlyData(EarlyDataEvent::Accepted) => self.early_data.accepted(),
432            Event::EarlyData(EarlyDataEvent::Enable(sz)) => self.early_data.enable(sz),
433            Event::EarlyData(EarlyDataEvent::Finished) => self.early_data.finished(),
434            Event::EarlyData(EarlyDataEvent::Start) => self.early_data.start(),
435            Event::EarlyData(EarlyDataEvent::Rejected) => self.early_data.rejected(),
436            _ => unreachable!(),
437        }
438    }
439}
rustls/client/connection.rs

rustls/client/
connection.rs
