Rustls is a modern TLS library written in Rust.
# Status Rustls is used in production at many organizations and projects. We aim to maintain reasonable API surface stability but the API may evolve as we make changes to accomodate new features or performance improvements. If you'd like to help out, please see [CONTRIBUTING.md](CONTRIBUTING.md). [![Build Status](https://github.com/rustls/rustls/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/rustls/rustls/actions/workflows/build.yml?query=branch%3Amain) [![Coverage Status (codecov.io)](https://codecov.io/gh/rustls/rustls/branch/main/graph/badge.svg)](https://codecov.io/gh/rustls/rustls/) [![Documentation](https://docs.rs/rustls/badge.svg)](https://docs.rs/rustls/) [![Chat](https://img.shields.io/discord/976380008299917365?logo=discord)](https://discord.gg/MCSB76RU96) ## Changelog The detailed list of changes in each release can be found at https://github.com/rustls/rustls/releases. # Documentation https://docs.rs/rustls/ # Approach Rustls is a TLS library that aims to provide a good level of cryptographic security, requires no configuration to achieve that security, and provides no unsafe features or obsolete cryptography by default. ## Current functionality (with default crate features) * TLS1.2 and TLS1.3. * ECDSA, Ed25519 or RSA server authentication by clients. * ECDSA, Ed25519 or RSA server authentication by servers. * Forward secrecy using ECDHE; with curve25519, nistp256 or nistp384 curves. * AES128-GCM and AES256-GCM bulk encryption, with safe nonces. * ChaCha20-Poly1305 bulk encryption ([RFC7905](https://tools.ietf.org/html/rfc7905)). * ALPN support. * SNI support. * Tunable fragment size to make TLS messages match size of underlying transport. * Optional use of vectored IO to minimise system calls. * TLS1.2 session resumption. * TLS1.2 resumption via tickets ([RFC5077](https://tools.ietf.org/html/rfc5077)). * TLS1.3 resumption via tickets or session storage. * TLS1.3 0-RTT data for clients. * TLS1.3 0-RTT data for servers. * Client authentication by clients. * Client authentication by servers. * Extended master secret support ([RFC7627](https://tools.ietf.org/html/rfc7627)). * Exporters ([RFC5705](https://tools.ietf.org/html/rfc5705)). * OCSP stapling by servers. ## Non-features For reasons [explained in the manual](https://docs.rs/rustls/latest/rustls/manual/_02_tls_vulnerabilities/index.html), rustls does not and will not support: * SSL1, SSL2, SSL3, TLS1 or TLS1.1. * RC4. * DES or triple DES. * EXPORT ciphersuites. * MAC-then-encrypt ciphersuites. * Ciphersuites without forward secrecy. * Renegotiation. * Kerberos. * TLS 1.2 protocol compression. * Discrete-log Diffie-Hellman. * Automatic protocol version downgrade. * Using CA certificates directly to authenticate a server/client (often called "self-signed certificates"). _Rustls' default certificate verifier does not support using a trust anchor as both a CA certificate and an end-entity certificate in order to limit complexity and risk in path building. While dangerous, all authentication can be turned off if required -- see the [example code](https://github.com/rustls/rustls/blob/992e2364a006b2e84a8cf6a7c3eaf0bdb773c9de/examples/src/bin/tlsclient-mio.rs#L318)_. There are plenty of other libraries that provide these features should you need them. ### Platform support While Rustls itself is platform independent, by default it uses [`ring`](https://crates.io/crates/ring) for implementing the cryptography in TLS. As a result, rustls only runs on platforms supported by `ring`. At the time of writing, this means 32-bit ARM, Aarch64 (64-bit ARM), x86, x86-64, LoongArch64, 32-bit & 64-bit Little Endian MIPS, 32-bit PowerPC (Big Endian), 64-bit PowerPC (Big and Little Endian), 64-bit RISC-V, and s390x. We do not presently support WebAssembly. For more information, see [the supported `ring` target platforms][ring-target-platforms]. By providing a custom instance of the [`crypto::CryptoProvider`] struct, you can replace all cryptography dependencies of rustls. This is a route to being portable to a wider set of architectures and environments, or compliance requirements. See the [`crypto::CryptoProvider`] documentation for more details. Specifying `default-features = false` when depending on rustls will remove the dependency on *ring*. Rustls requires Rust 1.61 or later. [ring-target-platforms]: https://github.com/briansmith/ring/blob/2e8363b433fa3b3962c877d9ed2e9145612f3160/include/ring-core/target.h#L18-L64 [crypto::CryptoProvider]: https://docs.rs/rustls/latest/rustls/crypto/trait.CryptoProvider.html # Example code There are two example programs which use [mio](https://github.com/carllerche/mio) to do asynchronous IO. ## Client example program The client example program is named `tlsclient-mio`. The interface looks like: ```tlsclient-mio Connects to the TLS server at hostname:PORT. The default PORT is 443. By default, this reads a request from stdin (to EOF) before making the connection. --http replaces this with a basic HTTP GET request for /. If --cafile is not supplied, a built-in set of CA certificates are used from the webpki-roots crate. Usage: tlsclient-mio [options] [--suite SUITE ...] [--proto PROTO ...] [--protover PROTOVER ...]