RFC: Reorganize `rustls` Features

Background

When we first created SQLx, RusTLS had a hardcoded dependency on ring. There was no such thing as pluggable crypto providers.

Additionally, RusTLS comes with no TLS roots by default. We were mainly deploying containerized applications on Linux, where the base images generally don't come with the ca-certificates or openssl packages installed by default. Since no one (that I know of, anyway) ever runs in-place updates inside a container, updating ca-certificates or webpki-roots has to be done during the build process anyway, so they were effectively the same to us. It made the most sense to target rustls using webpki-roots, which simplifies the image build significantly.

Of course, later on, RusTLS introduced pluggable crypto providers with the move toward defaulting to aws-lc-rs. And users wanted support for rustls-native-certs as well, so we ended up with a jagged matrix of TLS features:

https://github.com/transact-rs/sqlx/blob/b54008a329541c0ce230d8b203e0c00fc8e8ea48/Cargo.toml#L104-L108

Since we want to make sure everything builds and works right, we end up needing a CI pass to test each of these features, for all of MariaDB, MySQL, and Postgres, plus additional passes testing client certificate authentication for each backend.

I'm not particularly comfortable with this situation, as it makes CI take longer, requires more review effort when multiple passes fail at once, and is super annoying to test locally.

Open Feature Requests

And naturally, users have come along wanting more options as new features:

• https://github.com/transact-rs/sqlx/issues/960 (partially implemented as tls-rustls-ring-native-roots)
• https://github.com/transact-rs/sqlx/issues/4033
• https://github.com/transact-rs/sqlx/issues/4044
• https://github.com/transact-rs/sqlx/issues/4213

While this isn't the thread to argue about the value of each of these requests, this situation as a whole doesn't seem tenable or scalable.

The Plan: One Convenient Default + Support for Custom Providers

The original design was meant to cater to users who just want a default that works out of the box and does the right things, without having to become an expert in TLS or cryptography or the RusTLS ecosystem. There's an argument to be made that users should make an effort to understand the choices they make in this regard, but that ideal unfortunately clashes with the ugly reality, especially in this brave new world of LLMs and vibe-coding.

I've tried to operate with the philosophy that defaults in a library should be relatively foolproof, because even a normally careful user is bound to make mistakes in areas where they don't know what they don't know. I've certainly been that user many times before.

That means we should provide at least one TLS feature that we can tell users to choose if they don't know any better, so they can trust that it'll do the right thing on supported platforms.

Default Crypto Provider: aws-lc-rs (?)

This is the default that RusTLS themselves recommend, so it would seem to be a no-brainer: https://docs.rs/rustls/0.23.45/rustls/#built-in-providers

The problem I have is that it requires installing third-party software (or trusting pre-built binary objects) on Windows. This means that a dev with a minimal dev setup on Windows (assuming they only have msvc) can't just clone and build the project. I'd argue that this makes it a bad default for a "batteries-included" config, since it's very much not batteries-included.

Updated versions are available on chocolatey, but the package on nuget hasn't been updated since 2018, which means most people will probably have to download the installer directly from the website and run it manually. Veteran Windows devs are generally going to be used to just grabbing installer .exes from sketchy-looking websites anyway, but it doesn't exactly make for the best DX regardless.

Ultimately though, I don't know what I would recommend instead. ring is apparently still maintained, but its README clearly states it is and always has been experimental software, so it's hard to recommend in this day and age for production use-cases. And I don't think any other crypto provider backend is considered production-ready yet, either.

This makes aws-lc-rs the only viable choice.

Default TLS Roots Implementation: TBD

I don't know what I want to do here, which is the main reason I'm opening this RFC. The seemingly obvious choice would be rustls-platform-verifier since it purports to do the right thing for each platform, but there's some things that bug me about it:

1. The main argument for rustls-platform-verifier is support for OS CA constraints and revocation lists, but on Linux, arguably the most popular platform for the kind of applications SQLx would generally be used in, it offers very little over our existing default of webpki-roots (or changing the default to rustls-native-certs).
   • In fact, it pulls in webpki-roots, webpki and rustls-native-roots anyway, as platform-dependencies because of the need for a fallback, which has the possibility of further exacerbating #3211.
   • Fun fact: at least on Debian, the ca-certificates package is just a copy of Mozilla's trust store anyway, so the contents should be more or less identical to webpki-roots, just with differing paths for getting updates. native-certs does give the option for the sysadmin or image builder to override the certificate store, which is something that comes up occasionally.
2. The reliance on OS-level APIs generally written in memory-unsafe languages would seem to defeat the purpose of choosing RusTLS in the first place. The docs argue that this is still a net positive because using only the certificate verification APIs is exposing a smaller attack surface than using the full TLS implementation. I do have to concede that this is a fair point.

Still, the guarantees offered by rustls-platform-verifier are highly conditional on the platform, and that makes me somewhat uncomfortable. It seems to be the preferred choice, though.

Otherwise, the alternative I would go with is webpki-roots for consistency across platforms.

For Everything Else...

We require users to set a rustls::ClientConfig on *ConnectOptions. This makes ssl-mode/sslMode a no-op.

If the config doesn't set a crypto provider, a process-global provider is required.

This allows maximum flexibility and links in nothing but rustls itself.