rustls - Rust (original) (raw)

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: seethe 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 thecrypto::CryptoProvider documentation for more details.

Specifying default-features = false when depending on rustls will remove the implicit dependency on aws-lc-rs.

Rustls requires Rust 1.71 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 ClientConfigand 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 by associated crate features:

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:

§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 thestream::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 theio::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 examplesdirectory, including tlsserver-mioand tlsclient-mio- full worked examples using mio.

§Manual

The rustls manual explains design decisions and includes how-to guidance.

§Crate features

Here’s a list of what features are exposed by the rustls crate and what they mean.

pub use crate::ticketer::[TicketRotator](ticketer/struct.TicketRotator.html "struct rustls::ticketer::TicketRotator"); std

pub use crate::ticketer::[TicketSwitcher](ticketer/struct.TicketSwitcher.html "struct rustls::ticketer::TicketSwitcher"); std or hashbrown

pub use client::[ClientConfig](client/struct.ClientConfig.html "struct rustls::client::ClientConfig");

pub use client::[ClientConnection](client/struct.ClientConnection.html "struct rustls::client::ClientConnection"); std

pub use server::[ServerConfig](server/struct.ServerConfig.html "struct rustls::server::ServerConfig");

pub use server::[ServerConnection](server/struct.ServerConnection.html "struct rustls::server::ServerConnection"); std

client

Items for use in a client.

compress

Certificate compression and decompression support

crypto

Crypto provider interface.

ffdhe_groups

This module contains parameters for FFDHE named groups as defined in RFC 7919 Appendix A.

kernel

Kernel connection API.

lock

APIs abstracting over locking primitives.

manual

This is the rustls manual.

pki_types

Re-exports the contents of the rustls-pki-types crate for easy access

quic

APIs for implementing QUIC TLS

server

Items for use in a server.

sign

Message signing interfaces.

ticketerstd or hashbrown

APIs for implementing TLS tickets

time_provider

The library’s source of time.

unbuffered

Unbuffered connection API

version

All defined protocol versions appear in this module.

CipherSuiteCommon

Common state for cipher suites (both for TLS 1.2 and TLS 1.3)

CommonState

Connection state common to both client and server connections.

ConfigBuilder

A builder for ServerConfig or ClientConfig values.

ConnectionCommon

Interface shared by client and server connections.

DigitallySignedStruct

This type combines a SignatureScheme and a signature payload produced with that scheme.

DistinguishedName

A DistinguishedName is a Vec<u8> wrapped in internal types.

ExtractedSecrets

Secrets for transmitting/receiving data over a TLS session.

IoState

Values of this structure are returned from Connection::process_new_packetsand tell the caller the current I/O state of the TLS connection.

KeyLogFilestd

KeyLog implementation that opens a file whose name is given by the SSLKEYLOGFILE environment variable, and writes keys into it.

NoKeyLog

KeyLog that does exactly nothing.

OtherError

Any other error that cannot be expressed by a more specific Error variant.

Readerstd

A structure that implements std::io::Read for reading plaintext.

RootCertStore

A container for root certificates able to provide a root-of-trust for connection authentication.

Streamstd

This type implements io::Read and io::Write, encapsulating a Connection C and an underlying transport T, such as a socket.

StreamOwnedstd

This type implements io::Read and io::Write, encapsulating and owning a Connection C and an underlying transport T, such as a socket.

SupportedProtocolVersion

A TLS protocol version supported by rustls.

Tls12CipherSuitetls12

A TLS 1.2 cipher suite supported by rustls.

Tls13CipherSuite

A TLS 1.3 cipher suite supported by rustls.

WantsVerifier

Config builder state where the caller must supply a verifier.

WantsVersions

Config builder state where the caller must supply TLS protocol versions.

Writerstd

A structure that implements std::io::Write for writing plaintext.

AlertDescription

The AlertDescription TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.

CertRevocationListError

The ways in which a certificate revocation list (CRL) can be invalid.

CertificateCompressionAlgorithm

The “TLS Certificate Compression Algorithm IDs” TLS protocol enum. Values in this enum are taken from RFC8879.

CertificateError

The ways in which certificate validators can express errors.

CipherSuite

The CipherSuite TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.

Connectionstd

A client or server connection.

ConnectionTrafficSecrets

Secrets used to encrypt/decrypt data in a TLS session.

ContentType

The ContentType TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.

EncryptedClientHelloError

An error that occurred while handling Encrypted Client Hello (ECH).

Error

rustls reports protocol errors using this type.

ExtendedKeyPurpose

Extended Key Usage (EKU) purpose values.

HandshakeKind

Describes which sort of handshake happened.

HandshakeType

The HandshakeType TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.

InconsistentKeys

Specific failure cases from keys_match or a crate::crypto::signer::SigningKey that cannot produce a corresponding public key.

InvalidMessage

A corrupt TLS message payload that resulted in an error.

NamedGroup

The NamedGroup TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.

PeerIncompatible

The set of cases where we failed to make a connection because a peer doesn’t support a TLS version/feature we require.

PeerMisbehaved

The set of cases where we failed to make a connection because we thought the peer was misbehaving.

ProtocolVersion

The ProtocolVersion TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.

Side

Side of the connection.

SignatureAlgorithm

The SignatureAlgorithm TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.

SignatureScheme

The SignatureScheme TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.

SupportedCipherSuite

A cipher suite supported by rustls.

ALL_VERSIONS

A list of all the protocol versions supported by rustls.

DEFAULT_VERSIONS

The version configuration that an application should use by default.

ConfigSide

Helper trait to abstract ConfigBuilder over building a ClientConfig or ServerConfig.

KeyLog

This trait represents the ability to do something useful with key material, such as logging it to a file for debugging.

SideData

Data specific to the peer’s side (client or server).