v0.15.0

This release updates to Rustls 0.23.25 and increases the project minimum supported rust version (MSRV) from 1.71 to 1.74 to avoid a Rust compiler bug provoked by the ECH support in Rustls.

Added

• Binary releases:

  • Starting with the 0.15.0 release we now publish pre-built .zips for: Windows (x86_64 MSVC), Linux (x86_64 GNU libc), and Apple (ARM64 and x86_64) and a .deb for Debian/Ubuntu x86_64. These can be used to build software using rustls-ffi without needing cargo/cargo-c/rustc.

• API documentation is now available online at https://ffi.rustls.dev

• Post-quantum key exchange with X25519MLKEM768.

  • Enabled by default at a low priority. See the prefer-post-quantum feature flag to change this behavior.

• New opt-in feature flags:

  • Optional support for making the post-quantum key exchange X25519MLKEM768 the most-preferred key exchange by enabling the prefer-post-quantum feature flag. Requires the aws-lc-rs crypto provider.
  • Optional support for RFC 8879 certificate compression by enabling the cert_compression feature when building rustls-ffi. When enabled connections will transparently use certificate compression with Brotli or ZLib based on peer compatibility.
  • Optional FIPS-140-3 support using the aws-lc-rs provider. Enabled with the fips feature when building rustls-ffi. When enabled the aws-lc-rs crypto provider is used in its FIPS compatible mode. See the Rustls project documentation for more information on FIPS status.

• Encrypted Client Hello (ECH) support for client connections.

  • rustls_hpke struct for representing supported HPKE suites.
  • rustls_supported_hpke() function for returning a const pointer to a rustls_hpke instance if available. Only the aws-lc-rs backend returns a non-NULL value at this time.
  • rustls_client_config_builder_enable_ech_grease() client config builder function for configuring ECH GREASE using a rustls_hpke. This chooses a supported HPKE suite at random and is an anti-ossification measure clients may opt-in to when not performing "real" ECH.
  • rustls_client_config_builder_enable_ech() client config builder function for configuring ECH using a rustls_hpke and a TLS encoded ECH config list. The encoded ECH config list should be retrieved from DNS using a secure transport, such as DNS-over-HTTPS. See the librustls/tests/client.c example, and the ech-fetch.rs tool, for example usage.

• Additional connection information APIs:

  • Negotiated key exchange group, using rustls_connection_get_negotiated_key_exchange_group() for the IANA registered identifier, and rustls_connection_get_negotiated_key_exchange_group_name() for the name as a rustls_str.
  • Determining whether the handshake was a full TLS handshake, a full TLS handshake with an extra hello retry request (HRR) round-trip, a resumed TLS or a handshake, using rustls_connection_handshake_kind(). This returns a rustls_handshake_kind enum variant, which can be translated to a rustls_str using rustls_handshake_kind_str().

• Support for checking whether a rustls_certified_key's certificate matches the corresponding private key using rustls_certified_key_keys_match().

• Support for queuing TLS 1.3 key updates using rustls_connection_refresh_traffic_keys().

• Support for strict handling of CRL expiry using rustls_web_pki_server_cert_verifier_enforce_revocation_expiry() to customize a rustls_web_pki_server_cert_verifier_builder builder instance to reject CRLs with a next update in the past.

• Support for building rustls-ffi without any built in cryptography providers. This is mainly helpful for users that don't intend to use aws-lc-rs or *ring* but instead will bring their own FFI-ready rustls_crypto_provider.

• SSLKEYLOG support:

  • For simple logging to a file, use rustls_server_config_builder_set_key_log_file() or rustls_client_config_builder_set_key_log_file() with a client/server config builder to have the SSLKEYLOGFILE env var used to log an NSS formatted key log file appropriate for use with Wireshark and other tools.
  • For deeper integration, use rustls_server_config_builder_set_key_log() or rustls_client_config_builder_set_key_log() to configure C callbacks to be invoked to decide which secrets are logged and to do the logging.
  • See librustls/tests/client.c and librustls/tests/server.c for example usage.

• FIPS-140-3 APIs:

  • rustls_default_fips_provider() for instantiating a FIPS compatible rustls_crypto_provider (requires "fips" feature enabled).
  • rustls_crypto_provider_fips() for determining if a rustls_crypto_provider is FIPS compatible or not.
  • rustls_client_config_fips() for determining if a rustls_client_config was built with a FIPS compatible rustls_crypto_provider.
  • rustls_server_config_fips() for determining if a rustls_server_config was built with a FIPS compatible rustls_crypto_provider.
  • rustls_connection_fips() for determining if a rustls_connection was created from a rustls_client_config or rustls_server_config that was built with a FIPS compatible rustls_crypto_provider.

• Additional rustls_result error variants:

  • RUSTLS_RESULT_CERT_EXPIRED_REVOCATION_LIST, RUSTLS_RESULT_MESSAGE_CERTIFICATE_PAYLOAD_TOO_LARGE, RUSTLS_RESULT_INCONSISTENT_KEYS_KEYS_MISMATCH, RUSTLS_RESULT_INCONSISTENT_KEYS_UNKNOWN, RUSTLS_RESULT_INVALID_ENCRYPTED_CLIENT_HELLO_INVALID_CONFIG_LIST, RUSTLS_RESULT_INVALID_ENCRYPTED_CLIENT_HELLO_NO_COMPATIBLE_CONFIG, RUSTLS_RESULT_INVALID_ENCRYPTED_CLIENT_HELLO_SNI_REQUIRED.

Changed

• Calling rustls_server_config_builder_build() with no certificate/key configured previously returned RUSTLS_RESULT_GENERAL, it now returns RUSTLS_RESULT_NO_CERT_RESOLVER.

• The rustls_server_connection_get_server_name() function now returns a rustls_str instead of writing to a user provided buffer with out
  parameters.

• The rustls_server_config_builder_set_persistence() function is now void instead of returning a rustls_error.

• cargo-c is now the only supported method for building rustls-ffi. It supports building both static and shared libraries as well as making .pc pkg-config files per-platform. The pre-existing GNU Makefile has been removed in favour of cargo-c. See our README for more information.

• Building the client/server examples now requires cmake. The GNU Makefile has been removed in favour of unifying the example build system with cmake. Users only interested in building rustls-ffi (not the example applications) do not require cmake unless it is a requirement of their chosen cryptography provider (e.g. aws-lc-rs in fips mode).

Removed

• N/A

What's Changed

• build(deps): bump libc from 0.2.158 to 0.2.159 by @dependabot in #466
• client/server: support for KeyLog trait, SSLKEYLOGFILE by @cpu in #465
• tests: fix clippy::zombie_processes finding by @cpu in #467
• build(deps): bump rustls-pemfile from 2.1.3 to 2.2.0 by @dependabot in #469
• server: specific err for config w/o cert resolver by @cpu in #472
• error: sync with upstream Rustls error changes by @cpu in #471
• fix needless lifetimes clippy findings by @cpu in #474
• 0.23.x API gap reduction by @cpu in #470
• Makefile: adjust default target, broaden all target by @cpu in #473
• Migrate to pki-types PEM decoder by @cpu in #476
• build(deps): bump libc from 0.2.159 to 0.2.161 by @dependabot in #477
• update rustls 0.23.13 -> 0.23.15 by @cpu in #479
• Cargo: update rustls 0.23.15 -> 0.23.16 by @cpu in #481
• Add Windows ASAN testing by @cpu in #482
• build(deps): bump rustls-platform-verifier from 0.3.4 to 0.4.0 by @dependabot in #483
• build(deps): bump libc from 0.2.161 to 0.2.162 by @dependabot in #486
• crypto_provider: fix clippy::question_mark finding by @cpu in #488
• build(deps): bump libc from 0.2.162 to 0.2.164 by @dependabot in #487
• 0.14.1 backports for main, rustls 0.23.18 by @cpu in #491
• opt-in rustls-ffi FIPS support, Linux CI coverage by @cpu in #478
• build(deps): bump libc from 0.2.164 to 0.2.165 by @dependabot in #492
• build(deps): bump libc from 0.2.165 to 0.2.166 by @dependabot in #494
• build(deps): bump libc from 0.2.166 to 0.2.167 by @dependabot in #495
• build(deps): bump libc from 0.2.167 to 0.2.168 by @dependabot in #499
• Standardize on cargo-c for building rustls-ffi, CMake for building test programs by @cpu in #493
• docs: fix cargo c links in README by @cpu in #500
• client-side encrypted client hello (ECH) ...

v0.14.1

This release updates to Rustls 0.23.18 and increases the project MSRV from 1.64 to 1.71, matching the upstream Rustls MSRV.

Notably this brings in a fix for an availability issue for servers using the rustls_acceptor type and associated APIs. See the upstream 0.23.18 release notes for more information.

What's Changed

• 0.14.1 release preparation by @cpu in #490

Full Changelog: v0.14.0...v0.14.1

0.14.0

This release updates to Rustls 0.23.13 and changes the rustls-ffi API to allow choosing a cryptography provider to use with Rustls. See the Rustls CryptoProvider for more information on this model.

The default provider has been changed to match the Rustls default, aws-lc-rs. Users that wish to continue using *ring* as the provider may opt-in. See the README for more detail on supported platforms and build requirements.

Added

• A new rustls_crypto_provider type has been added to represent rustls::CryptoProvider instances.

  • The current process-wide default crypto provider (if any) can be retrieved with rustls_crypto_provider_default().
  • If rustls-ffi was built with aws-lc-rs, (DEFINE_AWS_LC_RS is true), then rustls_aws_lc_rs_crypto_provider() can be used to retrieve the aws-lc-rs provider.
  • If rustls-ffi was built with ring, (DEFINE_RING is true), then rustls_ring_crypto_provider() can be used to retrieve the aws-lc-rs provider.
  • Ciphersuites supported by a specific rustls_crypto_provider can be retrieved with rustls_crypto_provider_ciphersuites_len() and rustls_crypto_provider_ciphersuites_get().
  • Ciphersuites supported by the current process-wide default crypto provider (if any) can be retrieved with rustls_default_crypto_provider_ciphersuites_len() and rustls_default_crypto_provider_ciphersuites_get().
  • A buffer can be filled with cryptographically secure random data from a specific rustls_crypto_provider using rustls_crypto_provider_random(), or the process-wide default provider using rustls_default_crypto_provider_random().

• A new RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER rustls_result was added to indicate when an operation that requires a process-wide default crypto provider fails because no provider has been installed as the default, or the default was not implicit based on supported provider.

• A new rustls_crypto_provider_builder type has been added to customize, or install, a crypto provider.

  • rustls_crypto_provider_builder_new_from_default will construct a builder based on the current process-wide default.
  • rustls_crypto_provider_builder_new_with_base will construct a builder based on a specified rustls_crypto_provider.
  • Customization of supported ciphersuites can be achieved with rustls_crypto_provider_builder_set_cipher_suites().
  • The default process-wide provider can be installed from a builder using rustls_crypto_provider_builder_build_as_default(), if it has not already been done.
  • Or, a new rustls_crypto_provider instance built with rustls_crypto_provider_builder_build().
  • See the function documentation for more information on recommended workflows.

• A new rustls_signing_key type has been added to represent a private key that has been parsed by a rustls_crypto_provider and is ready to use for cryptographic operations.

  • Use rustls_crypto_provider_load_key() to load a signing_key from a buffer of PEM data using a rustls_crypto_provider.
  • Use rustls_certified_key_build_with_signing_key() to build a rustls_certified_key with a PEM cert chain and a rustls_signing_key.

• New rustls_web_pki_client_cert_verifier_builder_new_with_provider() and rustls_web_pki_server_cert_verifier_builder_new_with_provider() functions have been added to construct rustls_client_cert_verifier or rustls_server_cert_verifier instances that use a specified rustls_crypto_provider.

• Support for constructing a rustls_server_cert_verifier that uses the platform operating system's native certificate verification functionality was added. See the rustls-platform-verifier crate docs for more information on supported platforms.

  • Use rustls_platform_server_cert_verifier() to construct a platform verifier that uses the default crypto provider.
  • Use rustls_platform_server_cert_verifier_with_provider() to construct a platform verifier that uses the specified rustls_crypto_provider.
  • The returned rustls_server_cert_verifier can be used with a rustls_client_config_builder with rustls_client_config_builder_set_server_verifier().

• A new rustls_supported_ciphersuite_protocol_version() function was added for getting the rustls_tls_version IANA registered protocol version identifier supported by a given rustls_supported_ciphersuite.

• When using aws-lc-rs as the crypto provider, NIST P-521 signatures are now supported.

Changed

• rustls_server_config_builder_new(), rustls_client_config_builder_new(), rustls_web_pki_client_cert_verifier_builder_new(), and rustls_web_pki_server_cert_verifier_builder_new(), and rustls_certified_key_build functions now use the process default crypto provider instead of being hardcoded to use ring.

• rustls_server_config_builder_new_custom() and rustls_client_config_builder_new_custom() no longer take custom ciphersuites as an argument. Instead they require providing a rustls_crypto_provider.

  • Customizing ciphersuite support is now done at the provider level using rustls_crypto_provider_builder and rustls_crypto_provider_builder_set_cipher_suites().

• rustls_server_config_builder_build() and rustls_client_config_builder_build() now use out-parameters for the rustls_server_config or rustls_client_config, and return a rustls_result. This allows returning an error if the build operation fails because a suitable crypto provider was not available.

• rustls_client_config_builder_build() now returns a RUSTLS_RESULT_NO_SERVER_CERT_VERIFIER rustls_result error if a server certificate verifier was not set instead of falling back to a verifier that would fail all certificate validation attempts.

• The NoneVerifier used if a rustls_client_config is constructed by a rustls_client_config_builder without a verifier configured has been changed to return an unknown issuer error instead of a bad signature error when asked to verify a server certificate.

• Error specificity for revoked certificates was improved.

Removed

• The ALL_CIPHER_SUITES and DEFAULT_CIPHER_SUITES constants and associated functions (rustls_all_ciphersuites_len(), rustls_all_ciphersuites_get_entry(), rustls_default_ciphersuites_len() and rustls_default_ciphersuites_get_entry()) have been removed. Ciphersuite support is dictated by the rustls_crypto_provider.
  • Use rustls_default_supported_ciphersuites() to retrieve a rustls_supported_ciphersuites for the default rustls_crypto_provider.
  • Use rustls_crypto_provider_ciphersuites() to retrieve a rustls_supported_ciphersuites for a given rustls_crypto_provider.
  • Use rustls_supported_ciphersuites_len() and rustls_supported_ciphersuites_get() to iterate the rustls_supported_ciphersuites.

What's Changed

• docs: add 0.12.2 release to CHANGELOG by @cpu in #403
• docs: fix mod_tls link in README by @cpu in #410
• NULL safe set_boxed_mut_ptr/set_arc_mut_ptr by @cpu in #402
• README: Add packaging status badge by @kpcyrd in #411
• Fix valgrind job by @ctz in #413
• Makefile: limit scope of format/format-check by @cpu in #415
• Fix valgrind warning in server.c by @ctz in #414
• build(deps): bump rustls-pemfile from 2.1.1 to 2.1.2 by @dependabot in #418
• Fix two incompatible types warnings in example code by @cpu in #405
• client: NoneVerifier UnknownIssuer instead of BadSignature by @cpu in #421
• run clippy on tests, fix findings by @cpu in #416
• cmake: don't run cbindgen for build by @cpu in #408
• ci: add Linux pkg-config/.so test coverage by @cpu in #412
• Add rustls-platform-verifier binding by @amesgen in #419
• arc_castable!, box_castable!, ref_castable! macros by @cpu in #404
• Avoid ASAN for release builds, use w/ GCC or clang in debug builds by @cpu in #425
• build(deps): bump libc from 0.2.153 to 0.2.154 by @dependabot in #426
• lib: whitespace around Userdata invariants list by @cpu in #429
• build(deps): bump libc from 0.2.154 to 0.2.155 by @dependabot in #428
• connection: more docs for rustls_connection_is_handshaking by @cpu in #430
• ci: test pkg-config workflow on macOS by @cpu in #431
• chore: update to use spdx license identifier by @chenrui333 in #433
• project-wide tidying, style updates by @cpu in #432
• ci: pin cargo-c version in pkg-config workflow by @cpu in #435
• ci: revert cargo-c pin, set libdir explicitly by @cpu in #436
• rustls_version() integration test by @cpu in #434
• build(deps): bump rustls-platform-verifier from 0.3.1 to 0.3.2 by @dependabot in https:/...

0.13.0

This release updates to Rustls 0.23.4 and continues to use *ring* as the only cryptographic provider.

Added

• A new rustls_accepted_alert type is added. Calling rustls_accepted_alert_bytes on this type produces TLS data to write in the case where a server acceptor encountered an error accepting a client. The returned TLS data should be written to the connection before freeing the rustls_accepted_alert by calling rustls_accepted_alert_write_tls with a rustls_write_callback implementation.

Changed

• The rustls_acceptor_accept and rustls_accepted_into_connection API functions now require an extra rustls_accepted_alert out parameter. This parameter will only be set when an error occurs accepting a client connection and can be used to write any generated alerts to the connection to signal the accept error to the peer.

• The experimental cargo-c build support has been updated to use a vendored header file. This avoids the need for nightly rust or cbindgen when using this build method.

What's Changed

• server: fix clippy::manual_unwrap_or_default finding by @cpu in #399
• Prepare 0.13.0 release with Rustls 0.23 by @cpu in #389
• Cargo: configure cargo-c to use vendored .h by @cpu in #398
• proj: remove Makefile.Windows by @cpu in #396
• 0.13 prep (cont'd) by @cpu in #400

Full Changelog: v0.12.1...v0.13.0

v0.12.2

Changed

• The experimental cargo-c build support has been updated to use a vendored header file. This avoids the need for nightly rust or cbindgen when using this build method.

Changelog

• server: fix clippy::manual_unwrap_or_default finding by @cpu in #399
• 0.12.2 release preparation by @cpu in #401

Full Changelog: v0.12.1...v0.12.2

0.12.1

Added

• Initial support for building with cargo-c.
• Experimental support for building rustls-ffi as a dynamic library (cdylib).

What's Changed

• docs: document the opaque struct pattern in one place by @cpu in #374
• build(deps): bump libc from 0.2.150 to 0.2.151 by @dependabot in #376
• CI: restore integration tests, fixup MacOS/Windows expected linker parts by @cpu in #373
• build(deps): bump libc from 0.2.151 to 0.2.152 by @dependabot in #378
• tests: update Windows expected linker parts by @cpu in #379
• Minor github actions updates by @ctz in #382
• cargo fmt inside of ffi_panic_boundary! invocations by @ctz in #383
• tests: fix maybe-uninitialized warning by @cpu in #386
• build(deps): bump libc from 0.2.152 to 0.2.153 by @dependabot in #385
• lib: fix false positive dead_code trait by @cpu in #387
• cargo-c support by @lu-zero in #274
• 0.12.1 prep by @cpu in #395

New Contributors

• @lu-zero made their first contribution in #274

Full Changelog: v0.12.0...v0.12.1

0.12.0

This release updates to Rustls 0.22, but does not yet expose support for customizing the cryptographic provider. This will be added in a future release, and 0.12.0 continues to use *ring* as the only cryptographic provider.

Added

• RUSTLS_RESULT_CLIENT_CERT_VERIFIER_BUILDER_NO_ROOT_ANCHORS error code, returned when a client cert verifier is being built that hasn't provided any root trust anchors.
• The server certificate verifier now supports CRL revocation checking through policy and CRLs provided to the server certificate verifier builder.
• Client certificate verifier builder now supports controlling CRL revocation status check depth and unknown revocation policy.

Changed

• The root certificate store constructor (rustls_root_cert_store_new) and the function to add PEM content (rustls_root_cert_store_add_pem) have been replaced with a new rustls_root_cert_store_builder type, constructed with rustls_root_cert_store_builder_new. PEM content can be added with rustls_root_cert_store_builder_add_pem and rustls_root_cert_store_builder_load_roots_from_file.
• The client verifier builders (rustls_allow_any_anonymous_or_authenticated_client_builder, and rustls_allow_any_authenticated_client_builder) as well as the client verifier types (rustls_allow_any_anonymous_or_authenticated_client_verifier, rustls_allow_any_authenticated_client_verifier) have been replaced with rustls_web_pki_client_cert_verifier_builder and rustls_client_cert_verifier.
• The server config client verifier setters (rustls_server_config_builder_set_client_verifier and rustls_server_config_builder_set_client_verifier_optional) have been replaced with rustls_server_config_builder_set_client_verifier.
• The client config builder functions for specifying root trust anchors (rustls_client_config_builder_use_roots and rustls_client_config_builder_load_roots_from_file) have been replaced with a server certificate verifier builder (rustls_web_pki_server_cert_verifier_builder) constructed with rustls_web_pki_server_cert_verifier_builder_new and a rustls_root_cert_store. The built rustls_web_pki_server_cert_verifier can be provided to a client config builder with
  rustls_client_config_builder_set_server_verifier.
• CRL validation defaults to checking the full certificate chain, and treating unknown revocation status as an error condition.

Removed

• RUSTLS_RESULT_CERT_SCT_* error codes have been removed.

What's Changed

• cipher: fix unneeded return statements. by @cpu in #339
• tests: improve readability of output by @jsha in #337
• Nightly clippy fixes. by @cpu in #340
• Shrink unsafe block by @cactter in #271
• Attempt to fix occasional CI client/server test flakes. by @cpu in #343
• build(deps): bump actions/checkout from 3 to 4 by @dependabot in #344
• Commit Cargo.lock to repository by @kpcyrd in #346
• small test and documentation fixes by @cpu in #347
• Rewrite Python test helpers in Rust by @cpu in #348
• build(deps): bump libc from 0.2.148 to 0.2.149 by @dependabot in #351
• rework CastPtr, CastConstPtr, BoxCastPtr, ArcCastPtr by @cpu in #353
• docs: various small fixes to the README documentation by @cpu in #355
• fix build: pin a specific nightly by @jsha in #361
• Use rustls 0.21.9, revert nightly pin, update version to 0.11.1 by @cpu in #362
• lib: add try_take! macro, handling AlreadyUsed Options by @cpu in #360
• rename to_arc to clone_arc by @jsha in #363
• doc: document handling of dynamically sized types by @jsha in #364
• track upstream Rustls 0.22.x alpha changes. by @cpu in #341
• Document helper macros by @jsha in #365
• track rustls alpha.6 by @cpu in #368
• v0.12.0: update to rustls 0.22, address breaking changes by @cpu in #371
• docs: update changelog by @cpu in #372

New Contributors

• @cactter made their first contribution in #271
• @dependabot made their first contribution in #344
• @kpcyrd made their first contribution in #346

Full Changelog: v0.11.0...v/0.12.0

v0.11.0

Added

• Added support for providing certificate revocation lists (CRLs) to client certificate verifiers via the new builder types. (#324).
• Some new certificate revocation list related error codes starting with RUSTLS_RESULT_CERT_REVOCATION_LIST. (#324).

Changed

• rustls_client_cert_verifier became rustls_allow_any_authenticated_client_verifier and must be constructed from a rustls_allow_any_authenticated_client_builder.
• rustls_client_cert_verifier_optional became rustls_allow_any_anonymous_or_authenticated_client_verifier and must be constructed from a rustls_allow_any_anonymous_or_authenticated_client_builder.

v0.10.0

Added

• Some new certificate-related error codes starting with RUSTLS_RESULT_CERT_.
  Some new message-related error codes starting with RUSTLS_RESULT_MESSAGE_ (#303).
• Support for IP addresses in server names (#302).

Removed

• RUSTLS_CERT_INVALID_{ENCODING,SIGNATURE_TYPE,SIGNATURE,DATA}. Replaced by
  other RUSTLS_CERT_RESULT_ errors to match upstream rustls (#303).
• Old "crustls.h" and "libcrustls.a" symlinks to the current "rustls.h" and
  "librustls.a" names (#289).

Changed

• rustls_verify_server_cert_params->dns_name became server_name (#303).
• rustls_server_connection_get_sni_hostname became
  rustls_server_connection_get_server_name (#298).
• Give a better error message for UnexpectedEof (#284).

v0.8.2

Changed

• Add a feature, no_log_capture, which inhibits rustls from taking the global
  logger. Useful when built as a Rust dependency.