Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_text/tests/annealer_corpus/rustls_lib.rs

18.8 KiB, 1 run

created by r1870400018:11820, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

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, it requires the use of cryptography primitives
13//! for implementing the cryptography algorithms used in TLS. In Rustls, a
14//! [`crypto::CryptoProvider`] represents a collection of crypto primitive implementations.
15//!
16//! By providing a custom instance of the [`crypto::CryptoProvider`] struct, you
17//! can replace all cryptography dependencies of rustls. This is a route to being portable
18//! to a wider set of architectures and environments, or compliance requirements. See the
19//! [`crypto::CryptoProvider`] documentation for more details.
20//!
21//! [`crypto::CryptoProvider`]: crate::crypto::CryptoProvider
22//!
23//! ### Cryptography providers
24//!
25//! Since Rustls 0.22 it has been possible to choose the provider of the cryptographic primitives
26//! that Rustls uses. This may be appealing if you have specific platform, compliance or feature
27//! requirements.
28//!
29//! From 0.24, users must explicitly provide a crypto provider when constructing `ClientConfig` or
30//! `ServerConfig` instances. See the [`crypto::CryptoProvider`] documentation for more details.
31//!
32//! #### First-party providers
33//!
34//! The Rustls project currently maintains two cryptography providers:
35//!
36//! * [`rustls-aws-lc-rs`] - a provider that uses the [`aws-lc-rs`] crate for cryptography.
37//! While this provider can be harder to build on [some platforms][aws-lc-rs-platforms-faq], it provides excellent
38//! performance and a complete feature set (including post-quantum algorithms).
39//! * [`rustls-ring`] - a provider that uses the [`ring`] crate for cryptography. This
40//! provider is easier to build on a variety of platforms, but has a more limited feature set
41//! (for example, it does not support post-quantum algorithms).
42//!
43//! The Rustls team recommends using the [`rustls-aws-lc-rs`] crate for its complete feature set
44//! and performance. See [the aws-lc-rs FAQ][aws-lc-rs-platforms-faq] for more details of the
45//! platform/architecture support constraints in aws-lc-rs.
46//!
47//! See the documentation for [`crypto::CryptoProvider`] for details on how providers are
48//! selected.
49//!
50//! (For rustls versions prior to 0.24, both of these providers were shipped as part of the rustls
51//! crate, and Cargo features were used to select the preferred provider. The `aws-lc-rs` feature
52//! was enabled by default.)
53//!
54//! [`rustls-aws-lc-rs`]: https://crates.io/crates/rustls-aws-lc-rs
55//! [`aws-lc-rs`]: https://crates.io/crates/aws-lc-rs
56//! [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
57//! [`rustls-ring`]: https://crates.io/crates/rustls-ring
58//! [`ring`]: https://crates.io/crates/ring
59//!
60//! #### Third-party providers
61//!
62//! The community has also started developing third-party providers for Rustls:
63//!
64//! * [`boring-rustls-provider`] - a work-in-progress provider that uses [`boringssl`] for
65//! cryptography.
66//! * [`rustls-ccm`] - adds AES-CCM cipher suites (TLS 1.2 and 1.3) using [`RustCrypto`], for IoT/constrained-device protocols (IEEE 2030.5, Matter, RFC 7925).
67//! * [`rustls-graviola`] - a provider that uses [`graviola`] for cryptography.
68//! * [`rustls-mbedtls-provider`] - a provider that uses [`mbedtls`] for cryptography.
69//! * [`rustls-openssl`] - a provider that uses [OpenSSL] for cryptography.
70//! * [`rustls-rustcrypto`] - an experimental provider that uses the crypto primitives
71//! from [`RustCrypto`] for cryptography.
72//! * [`rustls-symcrypt`] - a provider that uses Microsoft's [SymCrypt] library.
73//! * [`rustls-wolfcrypt-provider`] - a work-in-progress provider that uses [`wolfCrypt`] for cryptography.
74//!
75//! [`rustls-ccm`]: https://github.com/jsulmont/rustls-ccm
76//! [`rustls-graviola`]: https://crates.io/crates/rustls-graviola
77//! [`graviola`]: https://github.com/ctz/graviola
78//! [`rustls-mbedtls-provider`]: https://github.com/fortanix/rustls-mbedtls-provider
79//! [`mbedtls`]: https://github.com/Mbed-TLS/mbedtls
80//! [`rustls-openssl`]: https://github.com/tofay/rustls-openssl
81//! [OpenSSL]: https://openssl-library.org/
82//! [`rustls-symcrypt`]: https://github.com/microsoft/rustls-symcrypt
83//! [SymCrypt]: https://github.com/microsoft/SymCrypt
84//! [`boring-rustls-provider`]: https://github.com/janrueth/boring-rustls-provider
85//! [`boringssl`]: https://github.com/google/boringssl
86//! [`rustls-rustcrypto`]: https://github.com/RustCrypto/rustls-rustcrypto
87//! [`RustCrypto`]: https://github.com/RustCrypto
88//! [`rustls-wolfcrypt-provider`]: https://github.com/wolfSSL/rustls-wolfcrypt-provider
89//! [`wolfCrypt`]: https://www.wolfssl.com/products/wolfcrypt
90//!
91//! See the [Making a custom CryptoProvider] section of the documentation for more information
92//! on this topic.
93//!
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//! `rustls_util::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::write_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//! let root_store = rustls::RootCertStore::from_iter(
148//! webpki_roots::TLS_SERVER_ROOTS
149//! .iter()
150//! .cloned(),
151//! );
152//! ```
153//!
154//! [`webpki_roots`]: https://crates.io/crates/webpki-roots
155//!
156//! Next, we make a `ClientConfig`. You're likely to make one of these per process,
157//! and use it for all connections made by that process.
158//!
159//! ```rust,no_run
160//! # let DEFAULT_PROVIDER = rustls::crypto::CryptoProvider::get_default().unwrap().clone();
161//! # let root_store: rustls::RootCertStore = panic!();
162//! let config = rustls::ClientConfig::builder(DEFAULT_PROVIDER)
163//! .with_root_certificates(root_store)
164//! .with_no_client_auth()
165//! .unwrap();
166//! ```
167//!
168//! Now we can make a connection. You need to provide the server's hostname so we
169//! know what to expect to find in the server's certificate.
170//!
171//! ```rust,no_run
172//! # use rustls;
173//! # use webpki;
174//! # use std::sync::Arc;
175//! # let DEFAULT_PROVIDER = rustls::crypto::CryptoProvider::get_default().unwrap().clone();
176//! # let root_store = rustls::RootCertStore::from_iter(
177//! # webpki_roots::TLS_SERVER_ROOTS
178//! # .iter()
179//! # .cloned(),
180//! # );
181//! # let client_config = Arc::new(rustls::ClientConfig::builder(DEFAULT_PROVIDER)
182//! # .with_root_certificates(root_store)
183//! # .with_no_client_auth()
184//! # .unwrap());
185//!
186//! let example_com = "example.com".try_into().unwrap();
187//! let mut client = client_config.connect(example_com)
188//! .build()
189//! .unwrap();
190//! ```
191//!
192//! Now you should do appropriate IO for the `client` object. If `client.wants_read()` yields
193//! true, you should call `client.read_tls()` when the underlying connection has data.
194//! Likewise, if `client.wants_write()` yields true, you should call `client.write_tls()`
195//! when the underlying connection is able to send data. You should continue doing this
196//! as long as the connection is valid.
197//!
198//! The return types of `read_tls()` and `write_tls()` only tell you if the IO worked. No
199//! parsing or processing of the TLS messages is done. After each `read_tls()` you should
200//! therefore call `client.process_new_packets()` which parses and processes the messages.
201//! Any error returned from `process_new_packets` is fatal to the connection, and will tell you
202//! why. For example, if the server's certificate is expired `process_new_packets` will
203//! return `Err(InvalidCertificate(Expired))`. From this point on,
204//! `process_new_packets` will not do any new work and will return that error continually.
205//!
206//! You can extract newly received data by calling `client.reader()` (which implements the
207//! `io::Read` trait). You can send data to the peer by calling `client.writer()` (which
208//! implements `io::Write` trait). Note that `client.writer().write()` buffers data you
209//! send if the TLS connection is not yet established: this is useful for writing (say) a
210//! HTTP request, but this is buffered so avoid large amounts of data.
211//!
212//! The following code uses a fictional socket IO API for illustration, and does not handle
213//! errors.
214//!
215//! ```rust,no_run
216//! # let mut client: rustls::ClientConnection = panic!();
217//! # struct Socket { }
218//! # impl Socket {
219//! # fn ready_for_write(&self) -> bool { false }
220//! # fn ready_for_read(&self) -> bool { false }
221//! # fn wait_for_something_to_happen(&self) { }
222//! # }
223//! #
224//! # use std::io::{Read, Write, Result};
225//! # impl Read for Socket {
226//! # fn read(&mut self, buf: &mut [u8]) -> Result<usize> { panic!() }
227//! # }
228//! # impl Write for Socket {
229//! # fn write(&mut self, buf: &[u8]) -> Result<usize> { panic!() }
230//! # fn flush(&mut self) -> Result<()> { panic!() }
231//! # }
232//! #
233//! # fn connect(_address: &str, _port: u16) -> Socket {
234//! # panic!();
235//! # }
236//! use std::io;
237//! use rustls::Connection;
238//!
239//! client.writer().write(b"GET / HTTP/1.0\r\n\r\n").unwrap();
240//! let mut socket = connect("example.com", 443);
241//! loop {
242//! if client.wants_read() && socket.ready_for_read() {
243//! client.read_tls(&mut socket).unwrap();
244//! client.process_new_packets().unwrap();
245//!
246//! let mut plaintext = Vec::new();
247//! client.reader().read_to_end(&mut plaintext).unwrap();
248//! io::stdout().write(&plaintext).unwrap();
249//! }
250//!
251//! if client.wants_write() && socket.ready_for_write() {
252//! client.write_tls(&mut socket).unwrap();
253//! }
254//!
255//! socket.wait_for_something_to_happen();
256//! }
257//! ```
258//!
259//! # Examples
260//!
261//! You can find several client and server examples of varying complexity in the [examples]
262//! directory, including [`tlsserver-mio`](https://github.com/rustls/rustls/blob/main/examples/src/bin/tlsserver-mio.rs)
263//! and [`tlsclient-mio`](https://github.com/rustls/rustls/blob/main/examples/src/bin/tlsclient-mio.rs)
264//! \- full worked examples using [`mio`].
265//!
266//! [`mio`]: https://docs.rs/mio/latest/mio/
267//!
268//! # Manual
269//!
270//! The [rustls manual](crate::manual) explains design decisions and includes how-to guidance.
271//!
272//! # Crate features
273//! Here's a list of what features are exposed by the rustls crate and what
274//! they mean.
275//!
276//! - `std` (enabled by default): enable the high-level (buffered) Connection API and other functionality
277//! which relies on the `std` library.
278//!
279//! - `log` (enabled by default): make the rustls crate depend on the `log` crate.
280//! rustls outputs interesting protocol-level messages at `trace!` and `debug!` level,
281//! and protocol-level errors at `warn!` and `error!` level. The log messages do not
282//! contain secret key data, and so are safe to archive without affecting session security.
283//!
284//! - `webpki` (enabled by default): make the rustls crate depend on the `rustls-wepbki` crate, which
285//! is used by default to provide built-in certificate verification. Without this feature, users must
286//! provide certificate verification themselves.
287//!
288//! - `brotli`: uses the `brotli` crate for RFC8879 certificate compression support.
289//!
290//! - `zlib`: uses the `zlib-rs` crate for RFC8879 certificate compression support.
291//!
292//! [x25519mlkem768-manual]: manual::_05_defaults#about-the-post-quantum-secure-key-exchange-x25519mlkem768
293
294// Require docs for public APIs, deny unsafe code, etc.
295#![warn(missing_docs, clippy::exhaustive_enums, clippy::exhaustive_structs)]
296#![forbid(unsafe_code, unused_must_use)]
297#![cfg_attr(not(any(bench, coverage_nightly)), forbid(unstable_features))]
298// Enable documentation for all features on docs.rs
299#![cfg_attr(rustls_docsrs, feature(doc_cfg))]
300// Enable coverage() attr for nightly coverage builds, see
301// <https://github.com/rust-lang/rust/issues/84605>
302// (`coverage_nightly` is a cfg set by `cargo-llvm-cov`)
303#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
304#![cfg_attr(bench, feature(test))]
305#![no_std]
306
307extern crate alloc;
308// This `extern crate` plus the `#![no_std]` attribute changes the default prelude from
309// `std::prelude` to `core::prelude`. That forces one to _explicitly_ import (`use`) everything that
310// is in `std::prelude` but not in `core::prelude`. This helps maintain no-std support as even
311// developers that are not interested in, or aware of, no-std support and / or that never run
312// `cargo build --no-default-features` locally will get errors when they rely on `std::prelude` API.
313extern crate std;
314
315#[cfg(doc)]
316use crate::crypto::CryptoProvider;
317
318// Import `test` sysroot crate for `Bencher` definitions.
319#[cfg(bench)]
320#[allow(unused_extern_crates)]
321extern crate test;
322
323// log for logging (optional).
324#[cfg(feature = "log")]
325#[expect(clippy::single_component_path_imports)]
326use log;
327
328#[cfg(not(feature = "log"))]
329mod log {
330 macro_rules! trace ( ($($tt:tt)*) => { crate::log::_used!($($tt)*) } );
331 macro_rules! debug ( ($($tt:tt)*) => { crate::log::_used!($($tt)*) } );
332 macro_rules! error ( ($($tt:tt)*) => { crate::log::_used!($($tt)*) } );
333 macro_rules! _warn ( ($($tt:tt)*) => { crate::log::_used!($($tt)*) } );
334 macro_rules! _used ( ($($tt:tt)*) => { { let _ = format_args!($($tt)*); } } );
335 pub(crate) use _used;
336 pub(crate) use _warn as warn;
337 pub(crate) use debug;
338 pub(crate) use error;
339 pub(crate) use trace;
340}
341
342/// This internal `sync` module aliases the `Arc` implementation to allow downstream forks
343/// of rustls targeting architectures without atomic pointers to replace the implementation
344/// with another implementation such as `portable_atomic_util::Arc` in one central location.
345mod sync {
346 #[expect(clippy::disallowed_types)]
347 pub(crate) type Arc<T> = alloc::sync::Arc<T>;
348}
349
350#[expect(unnameable_types)]
351#[macro_use]
352mod msgs;
353mod common_state;
354pub mod compress;
355mod conn;
356/// Crypto provider interface.
357pub mod crypto;
358pub mod error;
359mod hash_hs;
360mod limited_cache;
361mod tls12;
362mod tls13;
363mod vecbuf;
364mod verify;
365mod x509;
366#[macro_use]
367mod check;
368mod bs_debug;
369mod builder;
370pub mod enums;
371mod key_log;
372mod suites;
373mod versions;
374#[cfg(feature = "webpki")]
375mod webpki;
376
377/// Internal classes that are used in integration tests.
378/// The contents of this section DO NOT form part of the stable interface.
379#[doc(hidden)]
380pub mod internal {
381 pub use crate::msgs::fuzzing;
382}
383
384// The public interface is:
385pub use crate::builder::{ConfigBuilder, ConfigSide, WantsVerifier};
386pub use crate::common_state::{CommonState, ConnectionOutputs, HandshakeKind};
387pub use crate::conn::{
388 Connection, IoState, KeyingMaterialExporter, Reader, SideData, Writer, kernel,
389};
390pub use crate::error::Error;
391pub use crate::key_log::{KeyLog, NoKeyLog};
392pub use crate::suites::{
393 CipherSuiteCommon, ConnectionTrafficSecrets, ExtractedSecrets, SupportedCipherSuite,
394};
395pub use crate::ticketer::TicketRotator;
396pub use crate::tls12::Tls12CipherSuite;
397pub use crate::tls13::Tls13CipherSuite;
398pub use crate::verify::{DigitallySignedStruct, DistinguishedName, SignerPublicKey};
399pub use crate::versions::{ALL_VERSIONS, DEFAULT_VERSIONS, SupportedProtocolVersion};
400#[cfg(feature = "webpki")]
401pub use crate::webpki::RootCertStore;
402
403/// Items for use in a client.
404pub mod client;
405pub use client::{ClientConfig, ClientConnection};
406
407/// Items for use in a server.
408pub mod server;
409pub use server::{ServerConfig, ServerConnection};
410
411/// All defined protocol versions appear in this module.
412///
413/// ALL_VERSIONS is provided as an array of all of these values.
414pub mod version {
415 pub use crate::versions::{
416 TLS12, TLS12_VERSION, TLS13, TLS13_VERSION, Tls12Version, Tls13Version,
417 };
418}
419
420/// Re-exports the contents of the [rustls-pki-types](https://docs.rs/rustls-pki-types) crate for easy access
421pub mod pki_types {
422 #[doc(no_inline)]
423 pub use pki_types::*;
424}
425
426/// APIs for implementing QUIC TLS
427pub mod quic;
428
429/// APIs for implementing TLS tickets
430pub mod ticketer;
431
432/// This is the rustls manual.
433pub mod manual;
434
435pub mod time_provider;
436
437/// APIs abstracting over locking primitives.
438pub mod lock;
439
440mod hash_map {
441 pub(crate) use std::collections::HashMap;
442 pub(crate) use std::collections::hash_map::Entry;
443}
444
445mod sealed {
446 #[expect(unnameable_types)]
447 pub trait Sealed {}
448}
449
450mod core_hash_polyfill {
451 use core::hash::Hasher;
452
453 /// Working around `core::hash::Hasher` not being dyn-compatible
454 pub(super) struct DynHasher<'a>(pub(crate) &'a mut dyn Hasher);
455
456 impl Hasher for DynHasher<'_> {
457 fn finish(&self) -> u64 {
458 self.0.finish()
459 }
460
461 fn write(&mut self, bytes: &[u8]) {
462 self.0.write(bytes)
463 }
464 }
465}
466
467pub(crate) use core_hash_polyfill::DynHasher;