rustls for Rust: Complete Guide with Examples

1. What It Is and Why You Need It

rustls is a modern, secure, and high-performance implementation of the TLS (Transport Layer Security) protocol in the Rust language. Unlike such behemoths as OpenSSL or native-tls, rustls is written entirely in Rust without bindings to C libraries, making it an ideal choice for projects where memory safety, absence of undefined behavior, and ease of compilation are important.

Why do you need rustls? First, it solves the "dependency hell" problem: you don't need to install OpenSSL on the server or struggle with libssl-dev versions. Second, rustls by default uses only secure cryptographic algorithms (TLS 1.2 and 1.3, excluding obsolete ciphers). Third, it integrates perfectly with the Rust ecosystem through async/await and frameworks such as Tokio and async-std.

Main use cases: creating HTTPS servers and clients, secure WebSocket connections, working with gRPC, as well as any other cases where traffic encryption over TCP is required. rustls is actively used in projects such as curl, Firefox (via Neqo), and many industrial Rust applications.

2. Installation

Add rustls to your project using the Cargo package manager. For basic usage, two dependencies are sufficient:

# Cargo.toml\n[dependencies]\nrustls = "0.23"           # Main library\nwebpki-roots = "0.26"     # Trusted root certificates (for client)\ntokio = { version = "1", features = ["full"] }  # For async example\ntokio-rustls = "0.26"     # Async wrapper for Tokio

If you only need synchronous (blocking) mode, you can do without tokio-rustls. For working with certificates, you may also need rcgen (generating self-signed certificates) and rustls-pemfile (reading PEM files).

# Installation via cargo add (if using cargo-edit)\ncargo add rustls webpki-roots tokio tokio-rustls

3. Quick Start — Minimal Working Example

Let's create a simple HTTPS client that loads a page from example.com. This example demonstrates basic rustls configuration using system root certificates.

// src/main.rs\nuse std::sync::Arc;\nuse tokio::net::TcpStream;\nuse tokio_rustls::TlsConnector;\nuse rustls::pki_types::ServerName;\nuse webpki_roots::TLS_SERVER_ROOTS;\n\n#[tokio::main]\nasync fn main() -> Result<(), Box<dyn std::error::Error>> {\n    // 1. Create client configuration with trusted roots\n    let config = rustls::ClientConfig::builder()\n        .with_root_certificates(TLS_SERVER_ROOTS.clone())\n        .with_no_client_auth();\n\n    // 2. Create TLS connector\n    let connector = TlsConnector::from(Arc::new(config));\n\n    // 3. Establish TCP connection\n    let stream = TcpStream::connect("example.com:443").await?;\n\n    // 4. Wrap in TLS\n    let server_name = ServerName::try_from("example.com")?;\n    let mut tls_stream = connector.connect(server_name, stream).await?;\n\n    // 5. Send HTTP request\n    use tokio::io::AsyncWriteExt;\n    tls_stream.write_all(b"GET / HTTP/1.1\\r\\nHost: example.com\\r\\nConnection: close\\r\\n\\r\\n").await?;\n\n    // 6. Read response\n    use tokio::io::AsyncReadExt;\n    let mut response = String::new();\n    tls_stream.read_to_string(&mut response).await?;\n    println!("Server response:\\n{}", response);\n\n    Ok(())\n}

This code establishes a secure connection to example.com, sends an HTTP request, and prints the response. Note: we use webpki-roots to verify the server certificate — this is secure and does not require installing OpenSSL.

4. Main Methods/Functions/Classes

4.1. rus