Skip to content

TLS Backends

Jump to bottom
Stephen M. Coakley edited this page Nov 29, 2021 · 3 revisions

To make HTTPS requests an HTTP client needs to use an SSL/TLS client to establish secure socket connections with the server and validate server certificates. In Isahc, TLS support is provided by curl, which itself has a pluggable TLS system which supports multiple TLS client implementations, or "backends".

When using a bundled version of curl, a default TLS engine will be compiled in depending on the target platform. For example, when targeting Windows the native "schannel" APIs are used, on macOS Apple's Secure Transport library is used, and on other Unix-like systems OpenSSL is used. This is Isahc's default behavior, but you can also use crate features to change this behavior and select a different TLS backend.

Note: If the static-curl crate feature is disabled, then Isahc will link to the system-provided installation of curl if available. When using the system-provided installation of curl, the TLS engine will be decided for you based on how the system install was configured and cannot be changed.

Rustls

Rustls is a modern alternative TLS library which is written in Rust. You might decide to use Isahc with rustls instead of the system default TLS engine for several reasons:

  • Rustls can easily be compiled for many platforms without any extra configuration. A project using Isahc with rustls might be more portable, and using the same TLS engine across all platforms might make supporting the project easier.
  • Since it is written in Rust, rustls can be easier to compile without dealing with system dependencies.
  • You might want to avoid OpenSSL which sometimes has weird bugs, compilation issues, or security vulnerabilities.

Using rustls is not without its drawbacks and may not be desirable for all cases:

  • Rustls intentionally does not support older, less secure versions of SSL/TLS and certain other TLS features. If for some reason you must support these features in your application then rustls will not work for you.
  • Rustls is always statically linked, so if a security patch needs to be pushed for a TLS vulnerability then you can't rely on your operating system to automatically apply such updates; you'll have to recompile your applications with a newer version of rustls and push application updates individually.

Building with rustls

The rustls feature is not yet stable as the rustls backend implementation in curl has some missing features and known issues. Once available in the upstream Rust bindings for curl, we can merge https://github.com/sagebind/isahc/pull/309 and make rustls available as an unstable crate feature. If you'd like to test out the bleeding edge, you can use Isahc with rustls from Git as follows:

[dependencies.isahc]
git = "https://github.com/sagebind/isahc"
branch = "rustls"
features = "unstable-rustls-tls"

FAQ

  • Q: How can I check if Rustls is being used?
    • The version function returns a string summarizing how Isahc is configured, and will contain the string rustls if Rustls is being used.
  • Q: Will Rustls ever be the default TLS engine?
    • There's no plan to make Rustls the default backend at this time. This may change in the future.
  • Q: Is Rustls statically linked?
    • Yes, when using Rustls the default is for everything within Isahc to be statically linked.
  • Q: Will using Rustls make compiling Isahc for musl easier?
    • Yep, it should! Usually OpenSSL/LibreSSL is the cause of musl difficulties, so using Rustls avoids that issue.
Clone this wiki locally