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")] 212 use log; 213 214 #[cfg(not(feature = "logging"))] 215 #[macro_use] 216 mod 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] 225 mod msgs; 226 mod anchors; 227 mod cipher; 228 mod error; 229 mod hash_hs; 230 mod key_schedule; 231 mod pemfile; 232 mod prf; 233 mod rand; 234 mod record_layer; 235 mod session; 236 mod stream; 237 mod vecbuf; 238 mod verify; 239 #[cfg(test)] 240 mod verifybench; 241 mod x509; 242 #[macro_use] 243 mod check; 244 mod bs_debug; 245 mod client; 246 mod key; 247 mod keylog; 248 mod server; 249 mod suites; 250 mod 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. 254 pub 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: 267 pub use crate::anchors::{DistinguishedNames, OwnedTrustAnchor, RootCertStore}; 268 pub use crate::client::handy::{ClientSessionMemoryCache, NoClientSessionStorage}; 269 pub use crate::client::ResolvesClientCert; 270 pub use crate::client::StoresClientSessions; 271 pub use crate::client::{ClientConfig, ClientSession, WriteEarlyData}; 272 pub use crate::error::TLSError; 273 pub use crate::key::{Certificate, PrivateKey}; 274 pub use crate::keylog::{KeyLog, KeyLogFile, NoKeyLog}; 275 pub use crate::msgs::enums::CipherSuite; 276 pub use crate::msgs::enums::ProtocolVersion; 277 pub use crate::msgs::enums::SignatureScheme; 278 pub use crate::server::handy::ResolvesServerCertUsingSNI; 279 pub use crate::server::handy::{NoServerSessionStorage, ServerSessionMemoryCache}; 280 pub use crate::server::StoresServerSessions; 281 pub use crate::server::{ClientHello, ProducesTickets, ResolvesServerCert}; 282 pub use crate::server::{ServerConfig, ServerSession}; 283 pub use crate::session::Session; 284 pub use crate::stream::{Stream, StreamOwned}; 285 pub use crate::suites::{BulkAlgorithm, SupportedCipherSuite, ALL_CIPHERSUITES}; 286 pub use crate::ticketer::Ticketer; 287 pub 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. 294 pub 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. 307 pub mod sign; 308 309 #[cfg(feature = "quic")] 310 #[cfg_attr(docsrs, doc(cfg(feature = "quic")))] 311 /// APIs for implementing QUIC TLS 312 pub 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. 317 mod 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")))] 325 pub use crate::client::danger::DangerousClientConfig; 326 #[cfg(feature = "dangerous_configuration")] 327 #[cfg_attr(docsrs, doc(cfg(feature = "dangerous_configuration")))] 328 pub use crate::verify::{ 329 ClientCertVerified, ClientCertVerifier, HandshakeSignatureValid, ServerCertVerified, 330 ServerCertVerifier, WebPKIVerifier, 331 }; 332 333 /// This is the rustls manual. 334 pub mod manual; 335