Announcement: Changes to the default HTTPS client stack

[aajtodd]

Changes to default HTTPS stack

An upcoming release of the AWS SDK for Rust changes the default HTTP client and TLS provider (and more generally any client generated by smithy-rs).

Release Date

March 10, 2025
March 11, 2025

What's changing

The AWS SDK for Rust currently uses a default HTTPS client based on hyper-0.14.x and rustls (specifically 0.21.x which uses ring as the cryptography provider).

The default HTTPS client is being updated to be based on the 1.x version of hyper.

The default TLS provider is still rustls but the cryptography provider is now based on aws-lc instead of ring. This change also enables support for post-quantum cryptography.

FAQ

Why are you making this change?

The 0.14.x version of hyper receives bug fixes still but is not the currently maintained version of hyper. Similarly rustls has evolved as well (e.g. it now defaults to aws-lc instead of ring in the latest versions). Additionally the future of ring has recently become a point of concern (see the GitHub discussion). We want the default HTTPS stack to be a well maintained and secure default for all users.

What do I need to do?

The SDK ships with a default HTTPS client that works out of the box and this change will be transparent for most users. Certain platforms (e.g. Windows) may have additional build requirements than previously.

If you customize the HTTP client, you can continue to do so. If you utilize the APIs in aws_smithy_runtime::client::http::hyper_014 you may want to check that you are not relying on feature unification to enable the API(s) you depend on as this could break in the future. This can happen if you are relying on one of the AWS SDK crates to enable the connector-hyper-0-14-x feature for example.

How do I revert to defaulting to the legacy HTTPS stack?

We introduced a new BehaviorVersion that can be used to pin to the old HTTPS stack (for now).

// pin to a specific behavior version
let sdk_config = aws_config::defaults(
        aws_config::BehaviorVersion::v2024_03_28()
    )
    .load()
    .await;

let s3 = aws_sdk_s3::Client::new(&sdk_config);

...

For more information in general on behavior versions see the developer guide.

Note

In most cases you should use BehaviorVersion::latest() which represents our most up to date recommended settings. We recommend pinning to a specific version only as long as is required.

Warning

In a future release we will remove the rustls feature (which is what enables the legacy HTTPS stack) from the default features of every SDK crate. This will remove the legacy HTTPS stack from being always compiled by default. In turn this will break behavior versions prior to v2025_01_17 that depend on it for enabling the legacy stack. Users will have to re-enable the rustls feature manually at that time to keep the behavior version working.

How do I disable compiling the legacy hyper + rustls crates?

The SDK crates (e.g. aws-sdk-s3) all have default features that enable both the legacy and new HTTPS stacks. This makes it easier to pin to the old behavior via BehaviorVersion alone at the cost of compiling multiple hyper versions and TLS providers. Users that are sensitive to compile times may wish to disable this.

To disable compiling the now legacy HTTPS stack you need to customize the feature set in your Cargo.toml

# file: Cargo.toml

# disable default features which sets the `rustls` feature that enables the legacy HTTPS stack
aws-sdk-s3 = { version = "1", default-features = false, features = ["behavior-version-latest", "sigv4a", "rt-tokio", "default-https-client"] }

# repeat for each SDK crate consumed
aws-sdk-lambda = { version = "1", default-features = false, features = ["behavior-version-latest", "sigv4a", "rt-tokio", "default-https-client"] }
...

Warning

In a future release we will remove the rustls feature (which is what enables the legacy HTTPS stack) from the default features of every SDK crate. This will remove the legacy HTTPS stack from being always compiled by default.

How do I enable FIPS support?

The aws-smithy-http-client crate provides options to enable a FIPS compliant crypto implementation.

Note

FIPS support requires additional dependencies in your build environment. See the build instructions for the aws-lc crate.

# file: Cargo.toml
aws-smithy-http-client = { version = "1", features = ["rustls-aws-lc-fips"] }
...

// file: main.rs

use aws_smithy_http_client::{
    tls::{self, rustls_provider::CryptoMode},
    Builder,
};

#[tokio::main]
async fn main() {
    let http_client = Builder::new()
        .tls_provider(tls::Provider::Rustls(CryptoMode::AwsLcFips))
        .build_https();

    let sdk_config = aws_config::defaults(
        aws_config::BehaviorVersion::latest()
    )
    .http_client(http_client)
    .load()
    .await;

    // create client(s) using sdk_config
    // e.g. aws_sdk_s3::Client::new(&sdk_config);
}

How do I override the HyperClientBuilder?

In the legacy HTTPS stack the aws-smithy-runtime crate (versions < 1.8) provided a way to override the Hyper client Builder. This allowed customizing the settings used by hyper directly. It also provided a way to build with a custom TCP connector. Users sometimes utilized these APIs to customize specific low level settings for more advanced use cases and deployment scenarios.

Support for this functionality has been removed and is not present in the new HTTP client API provided by the aws-smithy-http-client crate. These APIs now live in the hyper-util crate which is not stable and as such we cannot support the functionality in a backwards compatible way today. The new API does expose ways to customize some of the settings (e.g. setting TCP_NODELAY). We encourage you to open a feature request for any setting you think should be exposed. We will weigh whether or not the setting is both widely applicable AND something we can support in a backwards compatible manner.

If you need to customize these settings or build with a custom TCP connector you can either:

1. Continue to use the legacy client stack at your own discretion. The aws-smithy-http-client crate now contains the entirety of the legacy API behind the hyper-014 and legacy-rustls-ring feature flags.
2. Bring your own HTTP client abstraction configured however you'd like by implementing the appropriate trait(s).

How do I migrate from aws-smithy-experimental?

Early support for hyper 1.x was available through the aws-smithy-experimental crate (0.1.x versions).

This support has been removed starting in 0.2.x. Users can either remove their code enabling this as the default HTTPS
client is now based on hyper 1.x OR they can migrate to the aws-smithy-http-client crate.

How do I enable post-quantum cryptography support?

The default TLS provider is based on rustsl using aws-lc-rs which supports X25519MLKEM768 post-quantum key exchange algorithm. To make X25519MLKEM768 the highest priority you need to add the rustls package to your crate and enable the prefer-post-quantum feature flag. Otherwise, it is available but not the highest priority. See the rustls documentation.

Note

This will become the default in a future release.

[vnghia]

Hello, I am currently using HyperClientBuilder to customize the https connector so I can use openssl/nativessl as a TLS provider. Given that HyperClientBuilder is deprecated, does it mean that I will have to provide a custom implementation to use hyper 1.0 ?
Thank you very much!

[aajtodd]

At the moment yes it sounds like if you would either need to continue using the soon to be deprecated hyper 0.14 APIs or bring your own HTTP client.

[vnghia]

Do you think the tls provider customization will be added anytime in the near future ?

[aajtodd]

We have no plans to support additional TLS providers at this time. Feel free to open a feature request and if there is significant enough interest we may consider it. In general the idea is the SDK ships with a default that will work for most users, if you have specific requirements, features, etc out of your HTTP and/or TLS implementation then you're encouraged to bring your own HTTP client.

[vnghia]

I see. Thank you!

[theli-ua]

March 10, 2025

Doesn't look like this happened today. Is there an updated timeline?

[aajtodd]

The runtime support was released yesterday but the switch over as the default for SDK crates didn't make it in time for release. Apologies, it should go out today.

[nhtyy]

I think this should have actually been considered a breaking change, since features are unified, i'm now getting this error from ring, I haven't narrowed it down to exactly where its coming from, but somewhere is relying on having a default provider set:

no process-level CryptoProvider available -- call CryptoProvider::install_default() before this point

[nhtyy]

Its entirely possible this doesn't actually occur with the AWS ecosystem, however features were "forcibly enabled" on my end unexpectedly, and some crate is not handling this gracefully.

https://doc.rust-lang.org/cargo/reference/semver.html#cargo-change-dep-feature

However typically this should only require a minor.

[nhtyy]

Ahh the reason is that previously, my deps that used rustls enabled the ring feature in my crate, then with this change the aws-lc-rs feature was also enabled, which causes this error here:

https://github.com/rustls/rustls/blob/a209a0e805ed2391eb4e0f3b3ed00b50ed3f4829/rustls/src/crypto/mod.rs#L243-L282