Expand description
§Rustls - a modern TLS library
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.
Rustls implements TLS1.2 and TLS1.3 for both clients and servers. See the full list of protocol features.
§Platform support
While Rustls itself is platform independent, by default it uses aws-lc-rs
for implementing
the cryptography in TLS. See the aws-lc-rs FAQ for more details of the
platform/architecture support constraints in aws-lc-rs.
ring
is also available via the ring
crate feature: see
the supported 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 aws-lc-rs.
Rustls requires Rust 1.63 or later. It has an optional dependency on zlib-rs which requires 1.75 or later.
§Cryptography providers
Since Rustls 0.22 it has been possible to choose the provider of the cryptographic primitives
that Rustls uses. This may be appealing if you have specific platform, compliance or feature
requirements that aren’t met by the default provider, aws-lc-rs
.
Users that wish to customize the provider in use can do so when constructing ClientConfig
and ServerConfig
instances using the with_crypto_provider
method on the respective config
builder types. See the crypto::CryptoProvider
documentation for more details.
§Built-in providers
Rustls ships with two built-in providers controlled with associated feature flags:
aws-lc-rs
- enabled by default, available with theaws_lc_rs
feature flag enabled.ring
- available with thering
feature flag enabled.
See the documentation for crypto::CryptoProvider
for details on how providers are
selected.
§Third-party providers
The community has also started developing third-party providers for Rustls:
rustls-mbedtls-provider
- a provider that usesmbedtls
for cryptography.boring-rustls-provider
- a work-in-progress provider that usesboringssl
for cryptography.rustls-rustcrypto
- an experimental provider that uses the crypto primitives fromRustCrypto
for cryptography.rustls-post-quantum
: an experimental provider that adds support for post-quantum key exchange to the default aws-lc-rs provider.rustls-wolfcrypt-provider
- a work-in-progress provider that useswolfCrypt
for cryptography.
§Custom provider
We also provide a simple example of writing your own provider in the custom-provider
example. This example implements a minimal provider using parts of the RustCrypto
ecosystem.
See the Making a custom CryptoProvider section of the documentation for more information on this topic.
§Design overview
Rustls is a low-level library. If your goal is to make HTTPS connections you may prefer to use a library built on top of Rustls like hyper or ureq.
§Rustls does not take care of network IO
It doesn’t make or accept TCP connections, or do DNS, or read or write files.
Our examples directory contains demos that show how to handle I/O using the
stream::Stream
helper, as well as more complex asynchronous I/O using mio
.
If you’re already using Tokio for an async runtime you may prefer to use tokio-rustls
instead
of interacting with rustls directly.
§Rustls provides encrypted pipes
These are the ServerConnection
and ClientConnection
types. You supply raw TLS traffic
on the left (via the read_tls()
and write_tls()
methods) and then read/write the
plaintext on the right:
TLS Plaintext
=== =========
read_tls() +-----------------------+ reader() as io::Read
| |
+---------> ClientConnection +--------->
| or |
<---------+ ServerConnection <---------+
| |
write_tls() +-----------------------+ writer() as io::Write
§Rustls takes care of server certificate verification
You do not need to provide anything other than a set of root certificates to trust. Certificate verification cannot be turned off or disabled in the main API.
§Getting started
This is the minimum you need to do to make a TLS client connection.
First we load some root certificates. These are used to authenticate the server.
The simplest way is to depend on the webpki_roots
crate which contains
the Mozilla set of root certificates.
let root_store = rustls::RootCertStore::from_iter(
webpki_roots::TLS_SERVER_ROOTS
.iter()
.cloned(),
);
Next, we make a ClientConfig
. You’re likely to make one of these per process,
and use it for all connections made by that process.
let config = rustls::ClientConfig::builder()
.with_root_certificates(root_store)
.with_no_client_auth();
Now we can make a connection. You need to provide the server’s hostname so we know what to expect to find in the server’s certificate.
let rc_config = Arc::new(config);
let example_com = "example.com".try_into().unwrap();
let mut client = rustls::ClientConnection::new(rc_config, example_com);
Now you should do appropriate IO for the client
object. If client.wants_read()
yields
true, you should call client.read_tls()
when the underlying connection has data.
Likewise, if client.wants_write()
yields true, you should call client.write_tls()
when the underlying connection is able to send data. You should continue doing this
as long as the connection is valid.
The return types of read_tls()
and write_tls()
only tell you if the IO worked. No
parsing or processing of the TLS messages is done. After each read_tls()
you should
therefore call client.process_new_packets()
which parses and processes the messages.
Any error returned from process_new_packets
is fatal to the connection, and will tell you
why. For example, if the server’s certificate is expired process_new_packets
will
return Err(InvalidCertificate(Expired))
. From this point on,
process_new_packets
will not do any new work and will return that error continually.
You can extract newly received data by calling client.reader()
(which implements the
io::Read
trait). You can send data to the peer by calling client.writer()
(which
implements io::Write
trait). Note that client.writer().write()
buffers data you
send if the TLS connection is not yet established: this is useful for writing (say) a
HTTP request, but this is buffered so avoid large amounts of data.
The following code uses a fictional socket IO API for illustration, and does not handle errors.
use std::io;
use rustls::Connection;
client.writer().write(b"GET / HTTP/1.0\r\n\r\n").unwrap();
let mut socket = connect("example.com", 443);
loop {
if client.wants_read() && socket.ready_for_read() {
client.read_tls(&mut socket).unwrap();
client.process_new_packets().unwrap();
let mut plaintext = Vec::new();
client.reader().read_to_end(&mut plaintext).unwrap();
io::stdout().write(&plaintext).unwrap();
}
if client.wants_write() && socket.ready_for_write() {
client.write_tls(&mut socket).unwrap();
}
socket.wait_for_something_to_happen();
}
§Examples
You can find several client and server examples of varying complexity in the examples
directory, including tlsserver-mio
and tlsclient-mio
- full worked examples using mio
.
§Crate features
Here’s a list of what features are exposed by the rustls crate and what they mean.
-
aws_lc_rs
(enabled by default): makes the rustls crate depend on theaws-lc-rs
crate. Userustls::crypto::aws_lc_rs::default_provider().install_default()
to use it as the defaultCryptoProvider
, or provide it explicitly when making aClientConfig
orServerConfig
.Note that aws-lc-rs has additional build-time dependencies like cmake. See the documentation for details.
-
ring
: makes the rustls crate depend on the ring crate for cryptography. Userustls::crypto::ring::default_provider().install_default()
to use it as the defaultCryptoProvider
, or provide it explicitly when making aClientConfig
orServerConfig
. -
fips
: enable support for FIPS140-3-approved cryptography, via the aws-lc-rs crate. This feature enables theaws_lc_rs
feature, which makes the rustls crate depend on aws-lc-rs. It also changes the default for [ServerConfig::require_ems
] and [ClientConfig::require_ems
].See manual::_06_fips for more details.
-
custom-provider
: disables implicit use of built-in providers (aws-lc-rs
orring
). This forces applications to manually install one, for instance, when using a customCryptoProvider
. -
tls12
(enabled by default): enable support for TLS version 1.2. Note that, due to the additive nature of Cargo features and because it is enabled by default, other crates in your dependency graph could re-enable it for your application. If you want to disable TLS 1.2 for security reasons, consider explicitly enabling TLS 1.3 only in the config builder API. -
logging
(enabled by default): make the rustls crate depend on thelog
crate. rustls outputs interesting protocol-level messages attrace!
anddebug!
level, and protocol-level errors atwarn!
anderror!
level. The log messages do not contain secret key data, and so are safe to archive without affecting session security. -
read_buf
: when building with Rust Nightly, adds support for the unstablestd::io::ReadBuf
and related APIs. This reduces costs from initializing buffers. Will do nothing on non-Nightly releases. -
brotli
: uses thebrotli
crate for RFC8879 certificate compression support. -
zlib
: uses thezlib-rs
crate for RFC8879 certificate compression support.
Re-exports§
pub use crate::ticketer::TicketSwitcher;
std
orhashbrown
pub use client::ClientConfig;
pub use client::ClientConnection;
std
pub use server::ServerConfig;
pub use server::ServerConnection;
std
Modules§
- Items for use in a client.
- Certificate compression and decompression support
- Crypto provider interface.
- This module contains parameters for FFDHE named groups as defined in RFC 7919 Appendix A.
- APIs abstracting over locking primitives.
- This is the rustls manual.
- Re-exports the contents of the rustls-pki-types crate for easy access
- APIs for implementing QUIC TLS
- Items for use in a server.
- Message signing interfaces.
- ticketer
std
orhashbrown
APIs for implementing TLS tickets - The library’s source of time.
- Unbuffered connection API
- All defined protocol versions appear in this module.
Structs§
- Common state for cipher suites (both for TLS 1.2 and TLS 1.3)
- Connection state common to both client and server connections.
- Interface shared by client and server connections.
- This type combines a
SignatureScheme
and a signature payload produced with that scheme. - A
DistinguishedName
is aVec<u8>
wrapped in internal types. - Secrets for transmitting/receiving data over a TLS session.
- Values of this structure are returned from
Connection::process_new_packets
and tell the caller the current I/O state of the TLS connection. - KeyLog
File std
KeyLog
implementation that opens a file whose name is given by theSSLKEYLOGFILE
environment variable, and writes keys into it. - KeyLog that does exactly nothing.
- Any other error that cannot be expressed by a more specific
Error
variant. - Reader
std
A structure that implementsstd::io::Read
for reading plaintext. - A container for root certificates able to provide a root-of-trust for connection authentication.
- Stream
std
This type implementsio::Read
andio::Write
, encapsulating a ConnectionC
and an underlying transportT
, such as a socket. - Stream
Owned std
This type implementsio::Read
andio::Write
, encapsulating and owning a ConnectionC
and an underlying blocking transportT
, such as a socket. - A TLS protocol version supported by rustls.
- A TLS 1.3 cipher suite supported by rustls.
- Config builder state where the caller must supply a verifier.
- Config builder state where the caller must supply TLS protocol versions.
- Writer
std
A structure that implementsstd::io::Write
for writing plaintext.
Enums§
- The
AlertDescription
TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. TheUnknown
item is used when processing unrecognised ordinals. - The ways in which a certificate revocation list (CRL) can be invalid.
- The “TLS Certificate Compression Algorithm IDs” TLS protocol enum. Values in this enum are taken from RFC8879.
- The ways in which certificate validators can express errors.
- The
CipherSuite
TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. TheUnknown
item is used when processing unrecognised ordinals. - Connection
std
A client or server connection. - Secrets used to encrypt/decrypt data in a TLS session.
- The
ContentType
TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. TheUnknown
item is used when processing unrecognised ordinals. - An error that occurred while handling Encrypted Client Hello (ECH).
- rustls reports protocol errors using this type.
- Describes which sort of handshake happened.
- The
HandshakeType
TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. TheUnknown
item is used when processing unrecognised ordinals. - Specific failure cases from
keys_match
. - A corrupt TLS message payload that resulted in an error.
- The
NamedGroup
TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. TheUnknown
item is used when processing unrecognised ordinals. - The set of cases where we failed to make a connection because a peer doesn’t support a TLS version/feature we require.
- The set of cases where we failed to make a connection because we thought the peer was misbehaving.
- The
ProtocolVersion
TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. TheUnknown
item is used when processing unrecognised ordinals. - Side of the connection.
- The
SignatureAlgorithm
TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. TheUnknown
item is used when processing unrecognised ordinals. - The
SignatureScheme
TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. TheUnknown
item is used when processing unrecognised ordinals. - A cipher suite supported by rustls.
Statics§
- A list of all the protocol versions supported by rustls.
- The version configuration that an application should use by default.
Traits§
- This trait represents the ability to do something useful with key material, such as logging it to a file for debugging.
- Data specific to the peer’s side (client or server).