rustls/lib.rs
1//! # Rustls - a modern TLS library
2//! Rustls is a TLS library that aims to provide a good level of cryptographic security,
3//! requires no configuration to achieve that security, and provides no unsafe features or
4//! obsolete cryptography.
5//!
6//! ## Current features
7//!
8//! * TLS1.2 and TLS1.3.
9//! * ECDSA, Ed25519 or RSA server authentication by clients.
10//! * ECDSA, Ed25519 or RSA server authentication by servers.
11//! * Forward secrecy using ECDHE; with curve25519, nistp256 or nistp384 curves.
12//! * AES128-GCM and AES256-GCM bulk encryption, with safe nonces.
13//! * ChaCha20-Poly1305 bulk encryption ([RFC7905](https://tools.ietf.org/html/rfc7905)).
14//! * ALPN support.
15//! * SNI support.
16//! * Tunable MTU to make TLS messages match size of underlying transport.
17//! * Optional use of vectored IO to minimise system calls.
18//! * TLS1.2 session resumption.
19//! * TLS1.2 resumption via tickets (RFC5077).
20//! * TLS1.3 resumption via tickets or session storage.
21//! * TLS1.3 0-RTT data for clients.
22//! * Client authentication by clients.
23//! * Client authentication by servers.
24//! * Extended master secret support (RFC7627).
25//! * Exporters (RFC5705).
26//! * OCSP stapling by servers.
27//! * SCT stapling by servers.
28//! * SCT verification by clients.
29//!
30//! ## Possible future features
31//!
32//! * PSK support.
33//! * OCSP verification by clients.
34//! * Certificate pinning.
35//!
36//! ## Non-features
37//!
38//! The following things are broken, obsolete, badly designed, underspecified,
39//! dangerous and/or insane. Rustls does not support:
40//!
41//! * SSL1, SSL2, SSL3, TLS1 or TLS1.1.
42//! * RC4.
43//! * DES or triple DES.
44//! * EXPORT ciphersuites.
45//! * MAC-then-encrypt ciphersuites.
46//! * Ciphersuites without forward secrecy.
47//! * Renegotiation.
48//! * Kerberos.
49//! * Compression.
50//! * Discrete-log Diffie-Hellman.
51//! * Automatic protocol version downgrade.
52//! * AES-GCM with unsafe nonces.
53//!
54//! There are plenty of other libraries that provide these features should you
55//! need them.
56//!
57//! ### Platform support
58//!
59//! Rustls uses [`ring`](https://crates.io/crates/ring) for implementing the
60//! cryptography in TLS. As a result, rustls only runs on platforms
61//! [supported by `ring`](https://github.com/briansmith/ring#online-automated-testing).
62//! At the time of writing this means x86, x86-64, armv7, and aarch64.
63//!
64//! ## Design Overview
65//! ### Rustls does not take care of network IO
66//! It doesn't make or accept TCP connections, or do DNS, or read or write files.
67//!
68//! There's example client and server code which uses mio to do all needed network
69//! IO.
70//!
71//! ### Rustls provides encrypted pipes
72//! These are the `ServerSession` and `ClientSession` types. You supply raw TLS traffic
73//! on the left (via the `read_tls()` and `write_tls()` methods) and then read/write the
74//! plaintext on the right:
75//!
76//! ```text
77//! TLS Plaintext
78//! === =========
79//! read_tls() +-----------------------+ io::Read
80//! | |
81//! +---------> ClientSession +--------->
82//! | or |
83//! <---------+ ServerSession <---------+
84//! | |
85//! write_tls() +-----------------------+ io::Write
86//! ```
87//!
88//! ### Rustls takes care of server certificate verification
89//! You do not need to provide anything other than a set of root certificates to trust.
90//! Certificate verification cannot be turned off or disabled in the main API.
91//!
92//! ## Getting started
93//! This is the minimum you need to do to make a TLS client connection.
94//!
95//! First, we make a `ClientConfig`. You're likely to make one of these per process,
96//! and use it for all connections made by that process.
97//!
98//! ```
99//! let mut config = rustls::ClientConfig::new();
100//! ```
101//!
102//! Next we load some root certificates. These are used to authenticate the server.
103//! The recommended way is to depend on the `webpki_roots` crate which contains
104//! the Mozilla set of root certificates.
105//!
106//! ```rust,ignore
107//! config.root_store.add_server_trust_anchors(&webpki_roots::TLS_SERVER_ROOTS);
108//! ```
109//!
110//! Now we can make a session. You need to provide the server's hostname so we
111//! know what to expect to find in the server's certificate.
112//!
113//! ```no_run
114//! # use rustls;
115//! # use webpki;
116//! # use std::sync::Arc;
117//! # let mut config = rustls::ClientConfig::new();
118//! let rc_config = Arc::new(config);
119//! let example_com = webpki::DNSNameRef::try_from_ascii_str("example.com").unwrap();
120//! let mut client = rustls::ClientSession::new(&rc_config, example_com);
121//! ```
122//!
123//! Now you should do appropriate IO for the `client` object. If `client.wants_read()` yields
124//! true, you should call `client.read_tls()` when the underlying connection has data.
125//! Likewise, if `client.wants_write()` yields true, you should call `client.write_tls()`
126//! when the underlying connection is able to send data. You should continue doing this
127//! as long as the connection is valid.
128//!
129//! The return types of `read_tls()` and `write_tls()` only tell you if the IO worked. No
130//! parsing or processing of the TLS messages is done. After each `read_tls()` you should
131//! therefore call `client.process_new_packets()` which parses and processes the messages.
132//! Any error returned from `process_new_packets` is fatal to the session, and will tell you
133//! why. For example, if the server's certificate is expired `process_new_packets` will
134//! return `Err(WebPKIError(CertExpired))`. From this point on, `process_new_packets` will
135//! not do any new work and will return that error continually.
136//!
137//! You can extract newly received data by calling `client.read()` (via the `io::Read`
138//! trait). You can send data to the peer by calling `client.write()` (via the `io::Write`
139//! trait). Note that `client.write()` buffers data you send if the TLS session is not
140//! yet established: this is useful for writing (say) a HTTP request, but don't write huge
141//! amounts of data.
142//!
143//! The following code uses a fictional socket IO API for illustration, and does not handle
144//! errors.
145//!
146//! ```text
147//! use std::io;
148//!
149//! client.write(b"GET / HTTP/1.0\r\n\r\n").unwrap();
150//! let mut socket = connect("example.com", 443);
151//! loop {
152//! if client.wants_read() && socket.ready_for_read() {
153//! client.read_tls(&mut socket).unwrap();
154//! client.process_new_packets().unwrap();
155//!
156//! let mut plaintext = Vec::new();
157//! client.read_to_end(&mut plaintext).unwrap();
158//! io::stdout().write(&plaintext).unwrap();
159//! }
160//!
161//! if client.wants_write() && socket.ready_for_write() {
162//! client.write_tls(&mut socket).unwrap();
163//! }
164//!
165//! socket.wait_for_something_to_happen();
166//! }
167//! ```
168//!
169//! # Examples
170//! `tlsserver` and `tlsclient` are full worked examples. These both use mio.
171//!
172//! # Crate features
173//! Here's a list of what features are exposed by the rustls crate and what
174//! they mean.
175//!
176//! - `logging`: this makes the rustls crate depend on the `log` crate.
177//! rustls outputs interesting protocol-level messages at `trace!` and `debug!`
178//! level, and protocol-level errors at `warn!` and `error!` level. The log
179//! messages do not contain secret key data, and so are safe to archive without
180//! affecting session security. This feature is in the default set.
181//!
182//! - `dangerous_configuration`: this feature enables a `dangerous()` method on
183//! `ClientConfig` and `ServerConfig` that allows setting inadvisable options,
184//! such as replacing the certificate verification process. Applications
185//! requesting this feature should be reviewed carefully.
186//!
187//! - `quic`: this feature exposes additional constructors and functions
188//! for using rustls as a TLS library for QUIC. See the `quic` module for
189//! details of these. You will only need this if you're writing a QUIC
190//! implementation.
191//!
192
193// Require docs for public APIs, deny unsafe code, etc.
194#![forbid(unsafe_code, unused_must_use, unstable_features)]
195#![deny(
196 trivial_casts,
197 trivial_numeric_casts,
198 missing_docs,
199 unused_import_braces,
200 unused_extern_crates,
201 unused_qualifications
202)]
203// Relax these clippy lints:
204// - ptr_arg: this triggers on references to type aliases that are Vec
205// underneath.
206#![cfg_attr(feature = "cargo-clippy", allow(clippy::ptr_arg))]
207// Enable documentation for all features on docs.rs
208#![cfg_attr(docsrs, feature(doc_cfg))]
209
210// log for logging (optional).
211#[cfg(feature = "logging")]
212use log;
213
214#[cfg(not(feature = "logging"))]
215#[macro_use]
216mod log {
217 macro_rules! trace ( ($($tt:tt)*) => {{}} );
218 macro_rules! debug ( ($($tt:tt)*) => {{}} );
219 macro_rules! warn ( ($($tt:tt)*) => {{}} );
220 macro_rules! error ( ($($tt:tt)*) => {{}} );
221}
222
223#[allow(missing_docs)]
224#[macro_use]
225mod msgs;
226mod anchors;
227mod cipher;
228mod error;
229mod hash_hs;
230mod key_schedule;
231mod pemfile;
232mod prf;
233mod rand;
234mod record_layer;
235mod session;
236mod stream;
237mod vecbuf;
238mod verify;
239#[cfg(test)]
240mod verifybench;
241mod x509;
242#[macro_use]
243mod check;
244mod bs_debug;
245mod client;
246mod key;
247mod keylog;
248mod server;
249mod suites;
250mod ticketer;
251
252/// Internal classes which may be useful outside the library.
253/// The contents of this section DO NOT form part of the stable interface.
254pub mod internal {
255 /// Functions for parsing PEM files containing certificates/keys.
256 pub mod pemfile {
257 pub use crate::pemfile::{certs, pkcs8_private_keys, rsa_private_keys};
258 }
259
260 /// Low-level TLS message parsing and encoding functions.
261 pub mod msgs {
262 pub use crate::msgs::*;
263 }
264}
265
266// The public interface is:
267pub use crate::anchors::{DistinguishedNames, OwnedTrustAnchor, RootCertStore};
268pub use crate::client::handy::{ClientSessionMemoryCache, NoClientSessionStorage};
269pub use crate::client::ResolvesClientCert;
270pub use crate::client::StoresClientSessions;
271pub use crate::client::{ClientConfig, ClientSession, WriteEarlyData};
272pub use crate::error::TLSError;
273pub use crate::key::{Certificate, PrivateKey};
274pub use crate::keylog::{KeyLog, KeyLogFile, NoKeyLog};
275pub use crate::msgs::enums::CipherSuite;
276pub use crate::msgs::enums::ProtocolVersion;
277pub use crate::msgs::enums::SignatureScheme;
278pub use crate::server::handy::ResolvesServerCertUsingSNI;
279pub use crate::server::handy::{NoServerSessionStorage, ServerSessionMemoryCache};
280pub use crate::server::StoresServerSessions;
281pub use crate::server::{ClientHello, ProducesTickets, ResolvesServerCert};
282pub use crate::server::{ServerConfig, ServerSession};
283pub use crate::session::Session;
284pub use crate::stream::{Stream, StreamOwned};
285pub use crate::suites::{BulkAlgorithm, SupportedCipherSuite, ALL_CIPHERSUITES};
286pub use crate::ticketer::Ticketer;
287pub use crate::verify::{
288 AllowAnyAnonymousOrAuthenticatedClient, AllowAnyAuthenticatedClient, NoClientAuth,
289};
290
291/// All defined ciphersuites appear in this module.
292///
293/// ALL_CIPHERSUITES is provided an array of all of these values.
294pub mod ciphersuite {
295 pub use crate::suites::TLS13_AES_128_GCM_SHA256;
296 pub use crate::suites::TLS13_AES_256_GCM_SHA384;
297 pub use crate::suites::TLS13_CHACHA20_POLY1305_SHA256;
298 pub use crate::suites::TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256;
299 pub use crate::suites::TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384;
300 pub use crate::suites::TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256;
301 pub use crate::suites::TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256;
302 pub use crate::suites::TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384;
303 pub use crate::suites::TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256;
304}
305
306/// Message signing interfaces and implementations.
307pub mod sign;
308
309#[cfg(feature = "quic")]
310#[cfg_attr(docsrs, doc(cfg(feature = "quic")))]
311/// APIs for implementing QUIC TLS
312pub mod quic;
313
314#[cfg(not(feature = "quic"))]
315// If QUIC support is disabled, just define a private module with an empty
316// trait to allow Session having QuicExt as a trait bound.
317mod quic {
318 pub trait QuicExt {}
319 impl QuicExt for super::ClientSession {}
320 impl QuicExt for super::ServerSession {}
321}
322
323#[cfg(feature = "dangerous_configuration")]
324#[cfg_attr(docsrs, doc(cfg(feature = "dangerous_configuration")))]
325pub use crate::client::danger::DangerousClientConfig;
326#[cfg(feature = "dangerous_configuration")]
327#[cfg_attr(docsrs, doc(cfg(feature = "dangerous_configuration")))]
328pub use crate::verify::{
329 ClientCertVerified, ClientCertVerifier, HandshakeSignatureValid, ServerCertVerified,
330 ServerCertVerifier, WebPKIVerifier,
331};
332
333/// This is the rustls manual.
334pub mod manual;