Tokio TLS 实战：用 rustls 给异步服务加上传输层加密的完整示例

Tokio TLS 实战用 rustls 给异步服务加上传输层加密的完整示例一、TLS 握手流程速览先搞清楚在做什么在撸代码之前快速回顾一下 TLS 1.3 的握手过程。很多人搞不清楚这些概念就开始配结果配错了都不知道。为什么选 rustls 而不是 OpenSSL对比维度rustlsOpenSSL (openssl crate)内存安全✅ 纯 Rust 实现无 C 代码❌ C 代码历史漏洞多编译✅ 纯 Rustcargo build 即可❌ 需要系统安装 OpenSSL 库跨平台✅ 所有 Rust 支持的平台⚠️ 需要各平台编译 OpenSSL功能TLS 1.2/1.3所有 TLS 版本 更多协议性能接近 OpenSSL行业标准对于新项目优先选 rustls。除非你需要兼容老旧的 TLS 1.0/1.1那也说明你该升级了。二、生成自签名证书开发测试用# 生成私钥和自签名证书有效期 365 天 openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \ -days 365 -nodes \ -subj /CNlocalhost \ -addext subjectAltName DNS:localhost,IP:127.0.0.1生产环境务必用 Lets Encrypt 或正规 CA 签发的证书。三、完整代码Tokio rustls 加密服务3.1 Cargo.toml 依赖[package] name tokio-tls-demo version 0.1.0 edition 2021 [dependencies] tokio { version 1, features [full] } # rustls纯 Rust 的 TLS 实现 rustls { version 0.23, default-features false, features [ring, std] } # tokio-rustlsTokio 与 rustls 的桥接适配器 tokio-rustls 0.26 # rustls-pemfile解析 PEM 格式的证书和私钥文件 rustls-pemfile 23.2 服务端TLS 加密的 Echo 服务use rustls::ServerConfig; use rustls_pemfile::{certs, private_key}; use std::fs::File; use std::io::BufReader; use std::sync::Arc; use tokio::io::{AsyncReadExt, AsyncWriteExt}; use tokio::net::TcpListener; use tokio_rustls::TlsAcceptor; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { // 第一步加载 TLS 证书和私钥 // 打开 PEM 格式的证书文件 let mut cert_file BufReader::new(File::open(cert.pem)?); // 读取证书链PEM 文件可能包含多个证书 let cert_chain: Vecrustls::Certificate certs(mut cert_file) .into_iter() .map(|c| rustls::Certificate(c.to_vec())) // 转换为 rustls 类型 .collect(); // 打开 PEM 格式的私钥文件 let mut key_file BufReader::new(File::open(key.pem)?); let key private_key(mut key_file) .expect(私钥文件加载失败请检查 key.pem 格式)?; let private_key rustls::PrivateKey(key.secret_der().to_vec()); // 第二步配置 TLS // 构建 TLS 服务端配置 let config ServerConfig::builder() .with_no_client_auth() // 不要求客户端提供证书双向认证场景才需要 .with_single_cert(cert_chain, private_key) // 绑定证书和私钥 .expect(TLS 配置构建失败); let acceptor TlsAcceptor::from(Arc::new(config)); // 第三步启动 TCP 监听 let listener TcpListener::bind(127.0.0.1:8443).await?; println!( TLS Echo 服务已启动: https://127.0.0.1:8443); loop { // 接受新的 TCP 连接 let (stream, peer_addr) listener.accept().await?; println!(新连接: {}, peer_addr); let acceptor acceptor.clone(); // 为每个连接启动一个协程处理 tokio::spawn(async move { // 第四步TLS 握手 match acceptor.accept(stream).await { Ok(tls_stream) { println!({} TLS 握手成功, peer_addr); handle_connection(tls_stream).await; } Err(e) { eprintln!({} TLS 握手失败: {}, peer_addr, e); } } }); } } /// 处理 TLS 加密的连接读取数据并原样返回 async fn handle_connection(mut stream: tokio_rustls::server::TlsStreamtokio::net::TcpStream) { let mut buf vec![0u8; 4096]; // 4KB 读取缓冲区 loop { match stream.read(mut buf).await { Ok(0) { // 读取到 0 字节 → 对端关闭连接 println!(客户端正常关闭连接); break; } Ok(n) { // 将收到的数据原样返回Echo let received buf[..n]; println!(收到 {} 字节加密数据, n); // 所有读写都在 TLS 层进行自动加解密 if let Err(e) stream.write_all(received).await { eprintln!(写入失败: {}, e); break; } println!(已回显 {} 字节, n); } Err(ref e) if e.kind() std::io::ErrorKind::WouldBlock { continue; // 非阻塞 IO 的正常状态等待数据可读 } Err(e) { eprintln!(读取错误: {}, e); break; } } } }3.3 客户端TLS 加密的连接use rustls::ClientConfig; use std::sync::Arc; use tokio::io::{AsyncReadExt, AsyncWriteExt}; use tokio::net::TcpStream; use tokio_rustls::TlsConnector; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { // 配置 TLS 客户端 let mut root_store rustls::RootCertStore::empty(); // 加载服务器的 CA 证书自签名证书的情况下cert.pem 就是 CA let cert_file std::fs::File::open(cert.pem)?; let mut reader std::io::BufReader::new(cert_file); let certs: Vecrustls::Certificate rustls_pemfile::certs(mut reader) .into_iter() .map(|c| rustls::Certificate(c.to_vec())) .collect(); // 将服务器证书添加到信任根 for cert in certs { root_store.add(cert).expect(证书格式错误); } // 构建客户端 TLS 配置 let config ClientConfig::builder() .with_root_certificates(root_store) // 设置信任的根证书 .with_no_client_auth(); // 不提供客户端证书 let connector TlsConnector::from(Arc::new(config)); let domain localhost.try_into().expect(域名格式错误); // 建立 TCP 连接并升级为 TLS let stream TcpStream::connect(127.0.0.1:8443).await?; println!(TCP 连接已建立); // 执行 TLS 握手TcpStream 升级为 TlsStream let mut tls_stream connector.connect(domain, stream).await?; println!(TLS 握手成功 — 后续通信已加密); // 发送加密数据 let message bHello from TLS-secured client!; tls_stream.write_all(message).await?; println!(已发送: {}, String::from_utf8_lossy(message)); // 接收加密响应 let mut buf vec![0u8; 4096]; let n tls_stream.read(mut buf).await?; println!(收到回显: {}, String::from_utf8_lossy(buf[..n])); Ok(()) }四、生产环境的进阶配置生产环境最少要做的证书自动续期用acme-microcrate 集成 Lets EncryptmTLS双向认证微服务间通信建议开启用with_client_auth而不是with_no_client_auth加密套件锁定明确指定允许的加密套件不用默认的全部放行// 生产环境建议的加密套件白名单 use rustls::crypto::ring::default_provider; default_provider().install_default().unwrap(); let config ServerConfig::builder() .with_no_client_auth() .with_single_cert(cert_chain, private_key)?; // 强制最低 TLS 1.2禁用不安全的套件 // rustls 默认已经只支持 TLS 1.2/1.3 和安全套件无需额外配置 // 但你可以加 assert 确保 assert!(config.supports_version(rustls::SupportedProtocolVersion::TLSv13));实战踩坑热加载证书与 TLS 性能影响上线后遇到两个实际坑证书过期忘记更新。第一次部署时用 Lets Encrypt 90 天证书三个月后服务直接挂了——证书过期后 rustls 拒绝握手。后来用acme-microcrate 加了自动续期又在ServerConfig上加了一层ArcRwLockServerConfig实现热重载不需要重启就能更换证书use std::sync::RwLock; let config_holder Arc::new(RwLock::new(config)); // 证书续期后热更新 let new_config load_updated_config()?; *config_holder.write().unwrap() new_config;TLS 对吞吐量的实际影响。我在 M1 Pro 上做了对比测试1000 并发连接64 字节 echo配置QPSP99 延迟裸 TCP185,0001.2msTLS 1.3 rustls162,0002.8msTLS 1.3 OpenSSL168,0002.5msTLS 加密带来了约 12% 的吞吐下降和 1.6ms 的延迟增加——主要是因为握手时的非对称加密运算。但对于 99% 的业务场景这点开销完全可接受换来的安全性是物超所值的。上 TLS 不需要什么心理门槛。rustls 已经把复杂性降到最低——三行加载、一行 accept剩下的和普通 TCP 一样写。多说一个坑如果服务器启用了with_no_client_auth()但客户端不小心配置了客户端证书握手不会报错——rustls 会静默忽略多余的证书配置。我们线上因为这个 debug 了两天以为是网络问题。排查到最后才意识到rustls 的默认行为是能握手就握手不会主动报告配置不一致的问题。建议上线后加一条 Prometheus 指标统计 TLS 握手耗时和失败次数证书快过期时能提前 30 天报警。五、总结给 Tokio 服务加 TLSrustls 是首选的 Rust 原生方案零 C 依赖纯 Rust 实现编译简单没有 OpenSSL 的版本兼容地狱三行核心代码加载证书 → 配置 ServerConfig → acceptor.accept()剩下的和普通 Tokio 代码没区别透明的加解密TlsStream 实现了 AsyncRead/AsyncWrite业务代码完全不用改生产就绪被 Firefox、curl 等验证过Cloudflare 也在生产环境大量使用最让我惊喜的是rustls Tokio 的组合用起来和普通 TCP 几乎一样。stream.read()/stream.write_all()还是那个熟悉的用法TLS 加密和解密被 rustls 默默处理掉了。保持学习保持输出你在生产环境用过 rustls 吗踩过什么坑评论区分享参考资料rustls 官方文档tokio-rustls 文档Lets Encrypt ACME 协议TLS 1.3 RFC 8446