rustls/
lib.rs

1//! # Rustls - a modern TLS library
2//!
3//! Rustls is a TLS library that aims to provide a good level of cryptographic security,
4//! requires no configuration to achieve that security, and provides no unsafe features or
5//! obsolete cryptography by default.
6//!
7//! Rustls implements TLS1.2 and TLS1.3 for both clients and servers. See [the full
8//! list of protocol features](manual::_04_features).
9//!
10//! ### Platform support
11//!
12//! While Rustls itself is platform independent, by default it uses [`aws-lc-rs`] for implementing
13//! the cryptography in TLS.  See [the aws-lc-rs FAQ][aws-lc-rs-platforms-faq] for more details of the
14//! platform/architecture support constraints in aws-lc-rs.
15//!
16//! [`ring`] is also available via the `ring` crate feature: see
17//! [the supported `ring` target platforms][ring-target-platforms].
18//!
19//! By providing a custom instance of the [`crypto::CryptoProvider`] struct, you
20//! can replace all cryptography dependencies of rustls.  This is a route to being portable
21//! to a wider set of architectures and environments, or compliance requirements.  See the
22//! [`crypto::CryptoProvider`] documentation for more details.
23//!
24//! Specifying `default-features = false` when depending on rustls will remove the implicit
25//! dependency on aws-lc-rs.
26//!
27//! Rustls requires Rust 1.71 or later. It has an optional dependency on zlib-rs which requires 1.75 or later.
28//!
29//! [ring-target-platforms]: https://github.com/briansmith/ring/blob/2e8363b433fa3b3962c877d9ed2e9145612f3160/include/ring-core/target.h#L18-L64
30//! [`crypto::CryptoProvider`]: crate::crypto::CryptoProvider
31//! [`ring`]: https://crates.io/crates/ring
32//! [aws-lc-rs-platforms-faq]: https://aws.github.io/aws-lc-rs/faq.html#can-i-run-aws-lc-rs-on-x-platform-or-architecture
33//! [`aws-lc-rs`]: https://crates.io/crates/aws-lc-rs
34//!
35//! ### Cryptography providers
36//!
37//! Since Rustls 0.22 it has been possible to choose the provider of the cryptographic primitives
38//! that Rustls uses. This may be appealing if you have specific platform, compliance or feature
39//! requirements that aren't met by the default provider, [`aws-lc-rs`].
40//!
41//! Users that wish to customize the provider in use can do so when constructing `ClientConfig`
42//! and `ServerConfig` instances using the `with_crypto_provider` method on the respective config
43//! builder types. See the [`crypto::CryptoProvider`] documentation for more details.
44//!
45//! #### Built-in providers
46//!
47//! Rustls ships with two built-in providers controlled by associated crate features:
48//!
49//!   * [`aws-lc-rs`] - enabled by default, available with the `aws_lc_rs` crate feature enabled.
50//!   * [`ring`] - available with the `ring` crate feature enabled.
51//!
52//! See the documentation for [`crypto::CryptoProvider`] for details on how providers are
53//! selected.
54//!
55//! #### Third-party providers
56//!
57//! The community has also started developing third-party providers for Rustls:
58//!
59//!   * [`boring-rustls-provider`] - a work-in-progress provider that uses [`boringssl`] for
60//!     cryptography.
61//!   * [`rustls-graviola`] - a provider that uses [`graviola`] for cryptography.
62//!   * [`rustls-mbedtls-provider`] - a provider that uses [`mbedtls`] for cryptography.
63//!   * [`rustls-openssl`] - a provider that uses [OpenSSL] for cryptography.
64//!   * [`rustls-rustcrypto`] - an experimental provider that uses the crypto primitives
65//!     from [`RustCrypto`] for cryptography.
66//!   * [`rustls-symcrypt`] - a provider that uses Microsoft's [SymCrypt] library.
67//!   * [`rustls-wolfcrypt-provider`] - a work-in-progress provider that uses [`wolfCrypt`] for cryptography.
68//!
69//! [`rustls-graviola`]: https://crates.io/crates/rustls-graviola
70//! [`graviola`]: https://github.com/ctz/graviola
71//! [`rustls-mbedtls-provider`]: https://github.com/fortanix/rustls-mbedtls-provider
72//! [`mbedtls`]: https://github.com/Mbed-TLS/mbedtls
73//! [`rustls-openssl`]: https://github.com/tofay/rustls-openssl
74//! [OpenSSL]: https://openssl-library.org/
75//! [`rustls-symcrypt`]: https://github.com/microsoft/rustls-symcrypt
76//! [SymCrypt]: https://github.com/microsoft/SymCrypt
77//! [`boring-rustls-provider`]: https://github.com/janrueth/boring-rustls-provider
78//! [`boringssl`]: https://github.com/google/boringssl
79//! [`rustls-rustcrypto`]: https://github.com/RustCrypto/rustls-rustcrypto
80//! [`RustCrypto`]: https://github.com/RustCrypto
81//! [`rustls-wolfcrypt-provider`]: https://github.com/wolfSSL/rustls-wolfcrypt-provider
82//! [`wolfCrypt`]: https://www.wolfssl.com/products/wolfcrypt
83//!
84//! #### Custom provider
85//!
86//! We also provide a simple example of writing your own provider in the [custom provider example].
87//! This example implements a minimal provider using parts of the [`RustCrypto`] ecosystem.
88//!
89//! See the [Making a custom CryptoProvider] section of the documentation for more information
90//! on this topic.
91//!
92//! [custom provider example]: https://github.com/rustls/rustls/tree/main/provider-example/
93//! [`RustCrypto`]: https://github.com/RustCrypto
94//! [Making a custom CryptoProvider]: https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html#making-a-custom-cryptoprovider
95//!
96//! ## Design overview
97//!
98//! Rustls is a low-level library. If your goal is to make HTTPS connections you may prefer
99//! to use a library built on top of Rustls like [hyper] or [ureq].
100//!
101//! [hyper]: https://crates.io/crates/hyper
102//! [ureq]: https://crates.io/crates/ureq
103//!
104//! ### Rustls does not take care of network IO
105//! It doesn't make or accept TCP connections, or do DNS, or read or write files.
106//!
107//! Our [examples] directory contains demos that show how to handle I/O using the
108//! [`stream::Stream`] helper, as well as more complex asynchronous I/O using [`mio`].
109//! If you're already using Tokio for an async runtime you may prefer to use [`tokio-rustls`] instead
110//! of interacting with rustls directly.
111//!
112//! [examples]: https://github.com/rustls/rustls/tree/main/examples
113//! [`tokio-rustls`]: https://github.com/rustls/tokio-rustls
114//!
115//! ### Rustls provides encrypted pipes
116//! These are the [`ServerConnection`] and [`ClientConnection`] types.  You supply raw TLS traffic
117//! on the left (via the [`read_tls()`] and [`write_tls()`] methods) and then read/write the
118//! plaintext on the right:
119//!
120//! [`read_tls()`]: Connection::read_tls
121//! [`write_tls()`]: Connection::read_tls
122//!
123//! ```text
124//!          TLS                                   Plaintext
125//!          ===                                   =========
126//!     read_tls()      +-----------------------+      reader() as io::Read
127//!                     |                       |
128//!           +--------->   ClientConnection    +--------->
129//!                     |          or           |
130//!           <---------+   ServerConnection    <---------+
131//!                     |                       |
132//!     write_tls()     +-----------------------+      writer() as io::Write
133//! ```
134//!
135//! ### Rustls takes care of server certificate verification
136//! You do not need to provide anything other than a set of root certificates to trust.
137//! Certificate verification cannot be turned off or disabled in the main API.
138//!
139//! ## Getting started
140//! This is the minimum you need to do to make a TLS client connection.
141//!
142//! First we load some root certificates.  These are used to authenticate the server.
143//! The simplest way is to depend on the [`webpki_roots`] crate which contains
144//! the Mozilla set of root certificates.
145//!
146//! ```rust,no_run
147//! # #[cfg(feature = "aws-lc-rs")] {
148//! let root_store = rustls::RootCertStore::from_iter(
149//!     webpki_roots::TLS_SERVER_ROOTS
150//!         .iter()
151//!         .cloned(),
152//! );
153//! # }
154//! ```
155//!
156//! [`webpki_roots`]: https://crates.io/crates/webpki-roots
157//!
158//! Next, we make a `ClientConfig`.  You're likely to make one of these per process,
159//! and use it for all connections made by that process.
160//!
161//! ```rust,no_run
162//! # #[cfg(feature = "aws_lc_rs")] {
163//! # let root_store: rustls::RootCertStore = panic!();
164//! let config = rustls::ClientConfig::builder()
165//!     .with_root_certificates(root_store)
166//!     .with_no_client_auth();
167//! # }
168//! ```
169//!
170//! Now we can make a connection.  You need to provide the server's hostname so we
171//! know what to expect to find in the server's certificate.
172//!
173//! ```rust
174//! # #[cfg(feature = "aws_lc_rs")] {
175//! # use rustls;
176//! # use webpki;
177//! # use std::sync::Arc;
178//! # rustls::crypto::aws_lc_rs::default_provider().install_default();
179//! # let root_store = rustls::RootCertStore::from_iter(
180//! #  webpki_roots::TLS_SERVER_ROOTS
181//! #      .iter()
182//! #      .cloned(),
183//! # );
184//! # let config = rustls::ClientConfig::builder()
185//! #     .with_root_certificates(root_store)
186//! #     .with_no_client_auth();
187//! let rc_config = Arc::new(config);
188//! let example_com = "example.com".try_into().unwrap();
189//! let mut client = rustls::ClientConnection::new(rc_config, example_com);
190//! # }
191//! ```
192//!
193//! Now you should do appropriate IO for the `client` object.  If `client.wants_read()` yields
194//! true, you should call `client.read_tls()` when the underlying connection has data.
195//! Likewise, if `client.wants_write()` yields true, you should call `client.write_tls()`
196//! when the underlying connection is able to send data.  You should continue doing this
197//! as long as the connection is valid.
198//!
199//! The return types of `read_tls()` and `write_tls()` only tell you if the IO worked.  No
200//! parsing or processing of the TLS messages is done.  After each `read_tls()` you should
201//! therefore call `client.process_new_packets()` which parses and processes the messages.
202//! Any error returned from `process_new_packets` is fatal to the connection, and will tell you
203//! why.  For example, if the server's certificate is expired `process_new_packets` will
204//! return `Err(InvalidCertificate(Expired))`.  From this point on,
205//! `process_new_packets` will not do any new work and will return that error continually.
206//!
207//! You can extract newly received data by calling `client.reader()` (which implements the
208//! `io::Read` trait).  You can send data to the peer by calling `client.writer()` (which
209//! implements `io::Write` trait).  Note that `client.writer().write()` buffers data you
210//! send if the TLS connection is not yet established: this is useful for writing (say) a
211//! HTTP request, but this is buffered so avoid large amounts of data.
212//!
213//! The following code uses a fictional socket IO API for illustration, and does not handle
214//! errors.
215//!
216//! ```rust,no_run
217//! # #[cfg(feature = "aws_lc_rs")] {
218//! # let mut client = rustls::ClientConnection::new(panic!(), panic!()).unwrap();
219//! # struct Socket { }
220//! # impl Socket {
221//! #   fn ready_for_write(&self) -> bool { false }
222//! #   fn ready_for_read(&self) -> bool { false }
223//! #   fn wait_for_something_to_happen(&self) { }
224//! # }
225//! #
226//! # use std::io::{Read, Write, Result};
227//! # impl Read for Socket {
228//! #   fn read(&mut self, buf: &mut [u8]) -> Result<usize> { panic!() }
229//! # }
230//! # impl Write for Socket {
231//! #   fn write(&mut self, buf: &[u8]) -> Result<usize> { panic!() }
232//! #   fn flush(&mut self) -> Result<()> { panic!() }
233//! # }
234//! #
235//! # fn connect(_address: &str, _port: u16) -> Socket {
236//! #   panic!();
237//! # }
238//! use std::io;
239//! use rustls::Connection;
240//!
241//! client.writer().write(b"GET / HTTP/1.0\r\n\r\n").unwrap();
242//! let mut socket = connect("example.com", 443);
243//! loop {
244//!   if client.wants_read() && socket.ready_for_read() {
245//!     client.read_tls(&mut socket).unwrap();
246//!     client.process_new_packets().unwrap();
247//!
248//!     let mut plaintext = Vec::new();
249//!     client.reader().read_to_end(&mut plaintext).unwrap();
250//!     io::stdout().write(&plaintext).unwrap();
251//!   }
252//!
253//!   if client.wants_write() && socket.ready_for_write() {
254//!     client.write_tls(&mut socket).unwrap();
255//!   }
256//!
257//!   socket.wait_for_something_to_happen();
258//! }
259//! # }
260//! ```
261//!
262//! # Examples
263//!
264//! You can find several client and server examples of varying complexity in the [examples]
265//! directory, including [`tlsserver-mio`](https://github.com/rustls/rustls/blob/main/examples/src/bin/tlsserver-mio.rs)
266//! and [`tlsclient-mio`](https://github.com/rustls/rustls/blob/main/examples/src/bin/tlsclient-mio.rs)
267//! \- full worked examples using [`mio`].
268//!
269//! [`mio`]: https://docs.rs/mio/latest/mio/
270//!
271//! # Manual
272//!
273//! The [rustls manual](crate::manual) explains design decisions and includes how-to guidance.
274//!
275//! # Crate features
276//! Here's a list of what features are exposed by the rustls crate and what
277//! they mean.
278//!
279//! - `std` (enabled by default): enable the high-level (buffered) Connection API and other functionality
280//!   which relies on the `std` library.
281//!
282//! - `aws_lc_rs` (enabled by default): makes the rustls crate depend on the [`aws-lc-rs`] crate.
283//!   Use `rustls::crypto::aws_lc_rs::default_provider().install_default()` to
284//!   use it as the default `CryptoProvider`, or provide it explicitly
285//!   when making a `ClientConfig` or `ServerConfig`.
286//!
287//!   Note that aws-lc-rs has additional build-time dependencies like cmake.
288//!   See [the documentation](https://aws.github.io/aws-lc-rs/requirements/index.html) for details.
289//!
290//! - `ring`: makes the rustls crate depend on the *ring* crate for cryptography.
291//!   Use `rustls::crypto::ring::default_provider().install_default()` to
292//!   use it as the default `CryptoProvider`, or provide it explicitly
293//!   when making a `ClientConfig` or `ServerConfig`.
294//!
295//! - `fips`: enable support for FIPS140-3-approved cryptography, via the [`aws-lc-rs`] crate.
296//!   This feature enables the `aws_lc_rs` crate feature, which makes the rustls crate depend
297//!   on [aws-lc-rs](https://github.com/aws/aws-lc-rs).  It also changes the default
298//!   for [`ServerConfig::require_ems`] and [`ClientConfig::require_ems`].
299//!
300//!   See [manual::_06_fips] for more details.
301//!
302//! - `prefer-post-quantum` (enabled by default): for the [`aws-lc-rs`]-backed provider,
303//!   prioritizes post-quantum secure key exchange by default (using X25519MLKEM768).
304//!   This feature merely alters the order of `rustls::crypto::aws_lc_rs::DEFAULT_KX_GROUPS`.
305//!   See [the manual][x25519mlkem768-manual] for more details.
306//!
307//! - `custom-provider`: disables implicit use of built-in providers (`aws-lc-rs` or `ring`). This forces
308//!   applications to manually install one, for instance, when using a custom `CryptoProvider`.
309//!
310//! - `tls12` (enabled by default): enable support for TLS version 1.2. Note that, due to the
311//!   additive nature of Cargo features and because it is enabled by default, other crates
312//!   in your dependency graph could re-enable it for your application. If you want to disable
313//!   TLS 1.2 for security reasons, consider explicitly enabling TLS 1.3 only in the config
314//!   builder API.
315//!
316//! - `logging` (enabled by default): make the rustls crate depend on the `log` crate.
317//!   rustls outputs interesting protocol-level messages at `trace!` and `debug!` level,
318//!   and protocol-level errors at `warn!` and `error!` level.  The log messages do not
319//!   contain secret key data, and so are safe to archive without affecting session security.
320//!
321//! - `read_buf`: when building with Rust Nightly, adds support for the unstable
322//!   `std::io::ReadBuf` and related APIs. This reduces costs from initializing
323//!   buffers. Will do nothing on non-Nightly releases.
324//!
325//! - `brotli`: uses the `brotli` crate for RFC8879 certificate compression support.
326//!
327//! - `zlib`: uses the `zlib-rs` crate for RFC8879 certificate compression support.
328//!
329//! [x25519mlkem768-manual]: manual::_05_defaults#about-the-post-quantum-secure-key-exchange-x25519mlkem768
330
331// Require docs for public APIs, deny unsafe code, etc.
332#![forbid(unsafe_code, unused_must_use)]
333#![cfg_attr(not(any(read_buf, bench, coverage_nightly)), forbid(unstable_features))]
334#![warn(
335    clippy::alloc_instead_of_core,
336    clippy::manual_let_else,
337    clippy::std_instead_of_core,
338    clippy::use_self,
339    clippy::upper_case_acronyms,
340    elided_lifetimes_in_paths,
341    missing_docs,
342    trivial_casts,
343    trivial_numeric_casts,
344    unreachable_pub,
345    unused_import_braces,
346    unused_extern_crates,
347    unused_qualifications
348)]
349// Relax these clippy lints:
350// - ptr_arg: this triggers on references to type aliases that are Vec
351//   underneath.
352// - too_many_arguments: some things just need a lot of state, wrapping it
353//   doesn't necessarily make it easier to follow what's going on
354// - new_ret_no_self: we sometimes return `Arc<Self>`, which seems fine
355// - single_component_path_imports: our top-level `use log` import causes
356//   a false positive, https://github.com/rust-lang/rust-clippy/issues/5210
357// - new_without_default: for internal constructors, the indirection is not
358//   helpful
359#![allow(
360    clippy::too_many_arguments,
361    clippy::new_ret_no_self,
362    clippy::ptr_arg,
363    clippy::single_component_path_imports,
364    clippy::new_without_default
365)]
366// Enable documentation for all features on docs.rs
367#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
368// Enable coverage() attr for nightly coverage builds, see
369// <https://github.com/rust-lang/rust/issues/84605>
370// (`coverage_nightly` is a cfg set by `cargo-llvm-cov`)
371#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
372// XXX: Because of https://github.com/rust-lang/rust/issues/54726, we cannot
373// write `#![rustversion::attr(nightly, feature(read_buf))]` here. Instead,
374// build.rs set `read_buf` for (only) Rust Nightly to get the same effect.
375//
376// All the other conditional logic in the crate could use
377// `#[rustversion::nightly]` instead of `#[cfg(read_buf)]`; `#[cfg(read_buf)]`
378// is used to avoid needing `rustversion` to be compiled twice during
379// cross-compiling.
380#![cfg_attr(read_buf, feature(read_buf))]
381#![cfg_attr(read_buf, feature(core_io_borrowed_buf))]
382#![cfg_attr(bench, feature(test))]
383#![no_std]
384
385extern crate alloc;
386// This `extern crate` plus the `#![no_std]` attribute changes the default prelude from
387// `std::prelude` to `core::prelude`. That forces one to _explicitly_ import (`use`) everything that
388// is in `std::prelude` but not in `core::prelude`. This helps maintain no-std support as even
389// developers that are not interested in, or aware of, no-std support and / or that never run
390// `cargo build --no-default-features` locally will get errors when they rely on `std::prelude` API.
391#[cfg(any(feature = "std", test))]
392extern crate std;
393
394#[cfg(doc)]
395use crate::crypto::CryptoProvider;
396
397// Import `test` sysroot crate for `Bencher` definitions.
398#[cfg(bench)]
399#[allow(unused_extern_crates)]
400extern crate test;
401
402// log for logging (optional).
403#[cfg(feature = "logging")]
404use log;
405
406#[cfg(not(feature = "logging"))]
407mod log {
408    macro_rules! trace    ( ($($tt:tt)*) => {{}} );
409    macro_rules! debug    ( ($($tt:tt)*) => {{}} );
410    macro_rules! error    ( ($($tt:tt)*) => {{}} );
411    macro_rules! _warn    ( ($($tt:tt)*) => {{}} );
412    pub(crate) use {_warn as warn, debug, error, trace};
413}
414
415#[cfg(test)]
416#[macro_use]
417mod test_macros;
418
419/// This internal `sync` module aliases the `Arc` implementation to allow downstream forks
420/// of rustls targeting architectures without atomic pointers to replace the implementation
421/// with another implementation such as `portable_atomic_util::Arc` in one central location.
422mod sync {
423    #[allow(clippy::disallowed_types)]
424    pub(crate) type Arc<T> = alloc::sync::Arc<T>;
425    #[allow(clippy::disallowed_types)]
426    pub(crate) type Weak<T> = alloc::sync::Weak<T>;
427}
428
429#[macro_use]
430mod msgs;
431mod common_state;
432pub mod compress;
433mod conn;
434/// Crypto provider interface.
435pub mod crypto;
436mod error;
437mod hash_hs;
438#[cfg(any(feature = "std", feature = "hashbrown"))]
439mod limited_cache;
440mod rand;
441mod record_layer;
442#[cfg(feature = "std")]
443mod stream;
444#[cfg(feature = "tls12")]
445mod tls12;
446mod tls13;
447mod vecbuf;
448mod verify;
449#[cfg(test)]
450mod verifybench;
451mod x509;
452#[macro_use]
453mod check;
454#[cfg(feature = "logging")]
455mod bs_debug;
456mod builder;
457mod enums;
458mod key_log;
459#[cfg(feature = "std")]
460mod key_log_file;
461mod suites;
462mod versions;
463mod webpki;
464
465/// Internal classes that are used in integration tests.
466/// The contents of this section DO NOT form part of the stable interface.
467#[allow(missing_docs)]
468#[doc(hidden)]
469pub mod internal {
470    /// Low-level TLS message parsing and encoding functions.
471    pub mod msgs {
472        pub mod base {
473            pub use crate::msgs::base::{Payload, PayloadU16};
474        }
475        pub mod codec {
476            pub use crate::msgs::codec::{Codec, Reader};
477        }
478        pub mod enums {
479            pub use crate::msgs::enums::{
480                AlertLevel, EchVersion, ExtensionType, HpkeAead, HpkeKdf, HpkeKem,
481            };
482        }
483        pub mod fragmenter {
484            pub use crate::msgs::fragmenter::MessageFragmenter;
485        }
486        pub mod handshake {
487            pub use crate::msgs::handshake::{
488                EchConfigContents, EchConfigPayload, HpkeKeyConfig, HpkeSymmetricCipherSuite,
489            };
490        }
491        pub mod message {
492            pub use crate::msgs::message::{
493                Message, MessagePayload, OutboundOpaqueMessage, PlainMessage,
494            };
495        }
496        pub mod persist {
497            pub use crate::msgs::persist::ServerSessionValue;
498        }
499    }
500
501    pub use crate::tls13::key_schedule::{derive_traffic_iv, derive_traffic_key};
502
503    pub mod fuzzing {
504        pub use crate::msgs::deframer::fuzz_deframer;
505    }
506}
507
508/// Unbuffered connection API
509///
510/// This is an alternative to the [`crate::ConnectionCommon`] API that does not internally buffer
511/// TLS nor plaintext data. Instead those buffers are managed by the API user so they have
512/// control over when and how to allocate, resize and dispose of them.
513///
514/// This API is lower level than the `ConnectionCommon` API and is built around a state machine
515/// interface where the API user must handle each state to advance and complete the
516/// handshake process.
517///
518/// Like the `ConnectionCommon` API, no IO happens internally so all IO must be handled by the API
519/// user. Unlike the `ConnectionCommon` API, this API does not make use of the [`std::io::Read`] and
520/// [`std::io::Write`] traits so it's usable in no-std context.
521///
522/// The entry points into this API are [`crate::client::UnbufferedClientConnection::new`],
523/// [`crate::server::UnbufferedServerConnection::new`] and
524/// [`unbuffered::UnbufferedConnectionCommon::process_tls_records`]. The state machine API is
525/// documented in [`unbuffered::ConnectionState`].
526///
527/// # Examples
528///
529/// [`unbuffered-client`] and [`unbuffered-server`] are examples that fully exercise the API in
530/// std, non-async context.
531///
532/// [`unbuffered-client`]: https://github.com/rustls/rustls/blob/main/examples/src/bin/unbuffered-client.rs
533/// [`unbuffered-server`]: https://github.com/rustls/rustls/blob/main/examples/src/bin/unbuffered-server.rs
534pub mod unbuffered {
535    pub use crate::conn::UnbufferedConnectionCommon;
536    pub use crate::conn::unbuffered::{
537        AppDataRecord, ConnectionState, EncodeError, EncodeTlsData, EncryptError,
538        InsufficientSizeError, ReadEarlyData, ReadTraffic, TransmitTlsData, UnbufferedStatus,
539        WriteTraffic,
540    };
541}
542
543// The public interface is:
544pub use crate::builder::{ConfigBuilder, ConfigSide, WantsVerifier, WantsVersions};
545pub use crate::common_state::{CommonState, HandshakeKind, IoState, Side};
546#[cfg(feature = "std")]
547pub use crate::conn::{Connection, Reader, Writer};
548pub use crate::conn::{ConnectionCommon, SideData, kernel};
549pub use crate::enums::{
550    AlertDescription, CertificateCompressionAlgorithm, CipherSuite, ContentType, HandshakeType,
551    ProtocolVersion, SignatureAlgorithm, SignatureScheme,
552};
553pub use crate::error::{
554    CertRevocationListError, CertificateError, EncryptedClientHelloError, Error,
555    ExtendedKeyPurpose, InconsistentKeys, InvalidMessage, OtherError, PeerIncompatible,
556    PeerMisbehaved,
557};
558pub use crate::key_log::{KeyLog, NoKeyLog};
559#[cfg(feature = "std")]
560pub use crate::key_log_file::KeyLogFile;
561pub use crate::msgs::enums::NamedGroup;
562pub use crate::msgs::ffdhe_groups;
563pub use crate::msgs::handshake::DistinguishedName;
564#[cfg(feature = "std")]
565pub use crate::stream::{Stream, StreamOwned};
566pub use crate::suites::{
567    CipherSuiteCommon, ConnectionTrafficSecrets, ExtractedSecrets, SupportedCipherSuite,
568};
569#[cfg(feature = "std")]
570pub use crate::ticketer::TicketRotator;
571#[cfg(any(feature = "std", feature = "hashbrown"))] // < XXX: incorrect feature gate
572pub use crate::ticketer::TicketSwitcher;
573#[cfg(feature = "tls12")]
574pub use crate::tls12::Tls12CipherSuite;
575pub use crate::tls13::Tls13CipherSuite;
576pub use crate::verify::DigitallySignedStruct;
577pub use crate::versions::{ALL_VERSIONS, DEFAULT_VERSIONS, SupportedProtocolVersion};
578pub use crate::webpki::RootCertStore;
579
580/// Items for use in a client.
581pub mod client {
582    pub(super) mod builder;
583    mod client_conn;
584    mod common;
585    mod ech;
586    pub(super) mod handy;
587    mod hs;
588    #[cfg(test)]
589    mod test;
590    #[cfg(feature = "tls12")]
591    mod tls12;
592    mod tls13;
593
594    pub use builder::WantsClientCert;
595    pub use client_conn::{
596        ClientConfig, ClientConnectionData, ClientSessionStore, EarlyDataError, ResolvesClientCert,
597        Resumption, Tls12Resumption, UnbufferedClientConnection,
598    };
599    #[cfg(feature = "std")]
600    pub use client_conn::{ClientConnection, WriteEarlyData};
601    pub use ech::{EchConfig, EchGreaseConfig, EchMode, EchStatus};
602    pub use handy::AlwaysResolvesClientRawPublicKeys;
603    #[cfg(any(feature = "std", feature = "hashbrown"))]
604    pub use handy::ClientSessionMemoryCache;
605
606    /// Dangerous configuration that should be audited and used with extreme care.
607    pub mod danger {
608        pub use super::builder::danger::DangerousClientConfigBuilder;
609        pub use super::client_conn::danger::DangerousClientConfig;
610        pub use crate::verify::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier};
611    }
612
613    pub use crate::msgs::persist::{Tls12ClientSessionValue, Tls13ClientSessionValue};
614    pub use crate::webpki::{
615        ServerCertVerifierBuilder, VerifierBuilderError, WebPkiServerVerifier,
616        verify_server_cert_signed_by_trust_anchor, verify_server_name,
617    };
618}
619
620pub use client::ClientConfig;
621#[cfg(feature = "std")]
622pub use client::ClientConnection;
623
624/// Items for use in a server.
625pub mod server {
626    pub(crate) mod builder;
627    mod common;
628    pub(crate) mod handy;
629    mod hs;
630    mod server_conn;
631    #[cfg(test)]
632    mod test;
633    #[cfg(feature = "tls12")]
634    mod tls12;
635    mod tls13;
636
637    pub use builder::WantsServerCert;
638    #[cfg(any(feature = "std", feature = "hashbrown"))]
639    pub use handy::ResolvesServerCertUsingSni;
640    #[cfg(any(feature = "std", feature = "hashbrown"))]
641    pub use handy::ServerSessionMemoryCache;
642    pub use handy::{AlwaysResolvesServerRawPublicKeys, NoServerSessionStorage};
643    pub use server_conn::{
644        Accepted, ClientHello, ProducesTickets, ResolvesServerCert, ServerConfig,
645        ServerConnectionData, StoresServerSessions, UnbufferedServerConnection,
646    };
647    #[cfg(feature = "std")]
648    pub use server_conn::{AcceptedAlert, Acceptor, ReadEarlyData, ServerConnection};
649
650    pub use crate::enums::CertificateType;
651    pub use crate::verify::NoClientAuth;
652    pub use crate::webpki::{
653        ClientCertVerifierBuilder, ParsedCertificate, VerifierBuilderError, WebPkiClientVerifier,
654    };
655
656    /// Dangerous configuration that should be audited and used with extreme care.
657    pub mod danger {
658        pub use crate::verify::{ClientCertVerified, ClientCertVerifier};
659    }
660}
661
662pub use server::ServerConfig;
663#[cfg(feature = "std")]
664pub use server::ServerConnection;
665
666/// All defined protocol versions appear in this module.
667///
668/// ALL_VERSIONS is a provided as an array of all of these values.
669pub mod version {
670    #[cfg(feature = "tls12")]
671    pub use crate::versions::TLS12;
672    pub use crate::versions::TLS13;
673}
674
675/// Re-exports the contents of the [rustls-pki-types](https://docs.rs/rustls-pki-types) crate for easy access
676pub mod pki_types {
677    #[doc(no_inline)]
678    pub use pki_types::*;
679}
680
681/// Message signing interfaces.
682pub mod sign {
683    pub use crate::crypto::signer::{CertifiedKey, Signer, SigningKey, SingleCertAndKey};
684}
685
686/// APIs for implementing QUIC TLS
687pub mod quic;
688
689#[cfg(any(feature = "std", feature = "hashbrown"))] // < XXX: incorrect feature gate
690/// APIs for implementing TLS tickets
691pub mod ticketer;
692
693/// This is the rustls manual.
694pub mod manual;
695
696pub mod time_provider;
697
698/// APIs abstracting over locking primitives.
699pub mod lock;
700
701/// Polyfills for features that are not yet stabilized or available with current MSRV.
702pub(crate) mod polyfill;
703
704#[cfg(any(feature = "std", feature = "hashbrown"))]
705mod hash_map {
706    #[cfg(feature = "std")]
707    pub(crate) use std::collections::HashMap;
708    #[cfg(feature = "std")]
709    pub(crate) use std::collections::hash_map::Entry;
710
711    #[cfg(all(not(feature = "std"), feature = "hashbrown"))]
712    pub(crate) use hashbrown::HashMap;
713    #[cfg(all(not(feature = "std"), feature = "hashbrown"))]
714    pub(crate) use hashbrown::hash_map::Entry;
715}