0.14.0-rc1: Adopt crypto provider API, use aws-lc-rs as default provider #441

Prev. we pinned cbindgen to 0.24.5. I've been using 0.27.0 (the latest available release) locally without spurious diffs. Let's update CI to match. Minor reformatting of YAML comes along for the ride.

"Within the import blocks we prefer to separate imports that don't share a parent module."[0] [0]: https://github.com/rustls/rustls/blob/main/CONTRIBUTING.md#imports

Offer an `unsafe` route for Rust code to translate a `rustls_str` to a `&str`.

Previously the `rustls_connection_get_negotiated_ciphersuite` function returned a pointer to a `rustls_supported_ciphersuite`. This commit changes that function to only return the identifier int. A new `rustls_connection_get_negotiated_ciphersuite_name` function is added for getting the negotiated ciphersuite name as a `rustls_str`. We want to avoid returning a `rustls_supported_ciphersuite` here because this type is both the _implementation_ of a ciphersuite, and metadata such as the name/ID. Getting a handle to the implementation for a given connection requires iterating the `ALL_CIPHER_SUITES` array to find the matching ciphersuite impl, and this is only workable when the available ciphersuites is a fixed quantity. Soon we will support customizing the cryptography provider, complicating this design greatly. Functionally, the only thing a caller wants to do in this circumstance is find the negotiated ciphersuite ID or name. To avoid the complication discussed above we can simply return this information directly and avoid the need to find the full fledged ciphersuite implementation at connection time.

Previously the `rustls_client_config_builder_build` function was infallible and returned a `rustls_client_config` instance without any chance to communicate errors. This commit updates this function to instead return `rustls_result` and use an out parameter for the `rustls_client_config`. Having this function unable to return a detailed error has a number of knock-on effects we want to address: * If no server certificate verifier has been configured the previous implementation isn't able to communicate that and instead configures a `NoneVerifier` - this ends up pushing failures to the time of certificate verification, making for a subpar user experience. If the user intended to disable certificate validation they need to do so with a verifier that won't error on use. If the user intended to configure certificate validation but something went wrong, we've made debugging harder. * Shortly we will allow customizing the crypto provider used for the configuration and may need to error if no suitable provider has been configured. The `client.c` example and `client.rs` unit tests are both updated to use the new out-parameter based API.

Now that the `rustls_client_config_builder_build()` fn is fallible it makes more sense to return an error (`RUSTLS_RESULT_NO_SERVER_CERT_VERIFIER`) when the required server certificate verifier hasn't been set instead of using `NoneVerifier` and failing all certificate validations. This commit removes the `NoneVerifier` and updates the tests that were building a client config without specifying a verifier to use the platform verifier instead. A new unit test is added that ensures the correct error is returned when a config is built without a verifier.

* Adds a `rustls_crypto_provider` type for representing a `rustls::crypto::CryptoProvider`. * The `*ring*` specific provider can be retrieved with `rustls_ring_crypto_provider()`. * The process-wide default crypto provider (if any) can be retrieved with `rustls_crypto_provider_default()`. * `rustls_crypto_provider_ciphersuites_len()` and `rustls_crypto_provider_ciphersuites_get()` can be used to fetch `rustls_supported_ciphersuite` instances the provider supports. * `rustls_default_crypto_provider_ciphersuites_len()` and `rustls_default_crypto_provider_ciphersuites_get()` can be used to fetch `rustls_supported_ciphersuite` instances the _default_ provider supports. * Adds a `rustls_crypto_provider_builder` that can be constructed based on the process default (`rustls_crypto_provider_builder_new()`) or a specific `rustls_crypto_provider` (`rustls_crypto_provider_builder_new_with_base()`). * The builder's supported ciphersuites can be customized with `rustls_crypto_provider_builder_set_cipher_suites()` * The builder can be turned into a `rustls_crypto_provider` with `rustls_crypto_provider_builder_build()`, or it can be built and installed as the process-wide default using `rustls_crypto_provider_builder_build_as_default()`. For the functions that assume a default (e.g. `rustls_default_supported_ciphersuites_len/get()`, and `rustls_crypto_provider_builder_new()`) we make an attempt to install a default based on unambiguous feature state if none has been explicitly set at the time of use. This matches the upstream Rustls behaviour using a function like `ClientConfig::builder()` and makes life easier for existing applications. The existing rustls-ffi code is not yet updated to use these abstractions. Similarly, the `*ring*` backend is unconditionally offered, but will become optional in subsequent commits.

* `rustls_server_config_builder_new()` now uses the process default crypto provider instead of being hardcoded to `*ring*`. We defer constructing the `ServerConfig` to avoid a panic in the event the process default isn't constructed. This will be surfaced as an error at build time instead. Like the upstream `ServerConfig::builder()` we make an attempt to install a process default provider from `rustls_server_config_builder_new()` if one has not been set and a clear choice is available based on crate features. * `rustls_server_config_builder_new_custom()` now takes a `rustls_crypto_provider` as an argument in place of the list of custom ciphersuites. The ciphersuites can be customized when the provider is constructed. * `rustls_server_config_builder_build()` now uses an out param for the `ServerConfig` so we can return a suitable error if there is no crypto provider (e.g. because `rustls_server_config_builder_new()` was used but the process default wasn't set and couldn't be guessed by crate features). * The `server.c` test code is updated to account for the breaking change in the builder out param.

* `rustls_client_config_builder_new()` now uses the process default crypto provider instead of being hardcoded to `*ring*`. We defer constructing the `ClientConfig` to avoid a panic in the event the process default isn't constructed. This will be surfaced as an error at build time instead. Like the upstream `ClientConfig::builder()` if no process default provider has been set when `rustls_client_config_builder_new()` is called we try to set one based on an unambiguous default implied by crate features. * `rustls_client_config_builder_new_custom()` now takes a `rustls_crypto_provider` as an argument in place of the list of custom ciphersuites. The ciphersuites can be customized when the provider is constructed. * `rustls_client_config_builder_build()` now uses an out param for the `ClientConfig` so we can return a suitable error if there is no crypto provider (e.g. because `rustls_client_config_builder_new()` was used but the process default wasn't set and couldn't be inferred from crate features). * The `client.c` test binary is updated to account for the breaking change in the client config builder out-param.

The provider model replaces these.

The `Verifier` type previously had an unconditional dependency on the `*ring*` crypto provider. This commit converts it to use the crypto provider set up by the client config builder as appropriate.

This commit adds a new type, `rustls_signing_key`, that represents a `&dyn SigningKey` loaded by a `rustls_crypto_provider`. A new `rustls_crypto_provider_load_key` fn is added to create a `rustls_signing_key` from a pointer to a `rustls_crypto_provider`, and PEM content in-memory. Wiring this up will be done in a subsequent commit.

This breaks an unconditional dependency on `*ring*` for loading certified key private keys. The existing `rustls_certified_key_build()` fn is converted to use the process-default crypto provider for this purpose. Like other functions that use the implied default if we find no default has been set yet and a clear default is available based on crate features this function will install & use it. For more control over which crypto provider is used to load a private key a new `rustls_certified_key_build_with_signing_key()` fn is added that allows specifying a `rustls_crypto_provider` to use.

This breaks an unconditional dep on `*ring*` for both verifiers. The client/server test binaries do not require any update in this case since they are using the APIs that assume a process-wide default crypto provider has been set.

This breaks an unconditional dep on `*ring*` for the `rustls_platform_verifier` verifier. The `client.c` test binary is updated to use the fallible form of the verifier constructor that uses the default crypto provider.

My IDE (clion) wants to do this automatically and I agree with its choices w.r.t removing hard tabs and adding some more consistent whitespace.

This commit: * Makes the `*ring*` dep optional, behind a `ring` feature flag * Adds an optional (but default) dep on `aws-lc-rs` behind a `aws-lc-rs` feature flag. * Adds `nasm` to the Windows build runners for the `aws-lc-rs` default crypto provider. This build requirement may be relaxed in the future depending on whether the upstream project chooses to take a ring-like strategy of distributing pre-built content. * Updates the cbindgen config to respect these new features. * Updates Makefile/Makefile.pkg-config and CMake build systems to support specifying which crypto provider to use, piping through the correct Rust features and C defines to make it all work. * One acceptor unit test is updated: the list of expected supported ciphersuites differs between `ring` and `aws-lc-rs`, with the latter also offering a P-521 suite that isn't present in `*ring*`. * The client/server examples use the implied default and so require no adjustments.

Rather than using decimal constants, rely on the rustls `SignatureScheme` enum.

This commit updates the `test` and `pkg-config` CI workflows to take into account the variable `CRYPTO_PROVIDER` support.

This commit updates both `client.c` and `server.c` to respect a new `RUSTLS_CIPHERSUITE` env var. When set, the process-default cryptography provider's supported ciphersuites will be reduced to _just_ the one specified by name in the env var. The `client_server.rs` integration test is then updated to start a server that only supports one ciphersuite. Two clients are created, one with a matching ciphersuite and one without. We use each client to connect to the server and assert only the expected one with matching ciphersuite support works.

* Mentions which providers we support, and explicitly that we do not encourage/support building with both providers enabled. * Mentions how to select a provider with the supported build systems (Make, cmake, cargo-c). * Mentions the build requirements/supported platforms of the upstream providers. For e.g. on Windows aws-lc-rs presently requires nasm because at present it (sensibly) does not ship pre-generated binaries.

There are no breaking changes to account for.

Keeping as a release candidate while we debug one remaining issue with a downstream HTTPD mod_tls update.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

0.14.0-rc1: Adopt crypto provider API, use aws-lc-rs as default provider #441

0.14.0-rc1: Adopt crypto provider API, use aws-lc-rs as default provider #441

Commits on Sep 9, 2024