CHANGELOG.md

Changelog

0.14.0 (2024-09-12)

This release updates to Rustls 0.23.13 and changes the rustls-ffi API to allow choosing a cryptography provider to use with Rustls.

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.

0.13.0 (2024-03-28)

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.

0.12.2 (2024-03-28)

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.

0.12.1 (2024-03-21)

Added

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

0.12.0 (2023-12-03)

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.

0.11.0 (2023-07-14)

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.

0.10.0 (2023-03-29)

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).

0.9.2 (2023-02-17)

Added

• Added support for Acceptor, allowing more flexible server-side handshake handling (#243).

Fixed

• Fixed violation of stacked borrows when freeing Arcs, detected by Miri (#283).

Changed

• Update minimum supported Rust version to 1.57.0, following rustls (#276).
• Update rustls (#279).
• Update list of libraries required to link against (#281).

0.9.1 (2022-06-10)

Fixed

• rustls_server_config_builder_set_client_verifier and rustls_server_config_builder_set_client_verifier_optional: fix a double free (#263).
• rustls_server_connection_get_sni_hostname: actually set *out_n when SNI unavailable (#262).
• rustls_client_cert_verifier_new and rustls_client_cert_verifier_optional_new: change to const and fix some lifecycle comments (#260).
• Fixed documentation for rustls_certified_key_build (#257).

0.9.0 (2022-05-12)

Added

• Add ciphersuite and version arrays (#242).
• Add method to get ciphersuite name (#147).
• Add static libs on Windows (#249).
• Added arrays ALL_CIPHER_SUITES, DEFAULT_CIPHER_SUITES, ALL_VERSIONS, and DEFAULT_VERSIONS as more convenient alternatives to rustls_default_ciphersuites_get_entry(), etc.
• Add CMake build system (with Windows support) (#253).
• Add feature for early testing of feature(read_buf) (#248).

Fixed

• rustls_is_cert_error now returns true for invalid certificate data (this was broken by v0.8.0). It also takes unsigned int as its input parameter instead of rustls_result (#227).
• Avoid creating references to out params (#256).

Changed

• rustls_verify_server_cert_callback now returns uint32_t instead of rustls_result (#227).
• rustls_session_store_get_callback and rustls_session_store_put_callback now return uint32_t (#227).
• Update rustls dependency to 0.20.4.

0.8.2 (2021-11-13)

Changed

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

0.8.1 (2021-11-12)

Changed

• Setting of ALPN protocols for client configs was broken in the 0.8.0 release. This release fixes it.

0.8.0 (2021-11-08)

The package name has changed to "rustls-ffi" (from "crustls"). The header file (as installed by make DESTDIR=/path/ install) is now rustls.h and the library is librustls.a. The old library and header names are symlinked as part of the install process, to simplify upgrading to the new version.

If you are importing this as a library from other Rust code, you should import rustls_ffi.

Added

• rustls_client_config_builder_new_custom and rustls_server_config_builder_new_custom: start building a config, with ciphersuites and TLS versions set at initial construction.
• rustls_default_ciphersuites_get_entry() and rustls_default_ciphersuites_len(): get default ciphersuites as opposed to all ciphersuites (these happen to be the same today but might not always be).

Changed

• rustls-ffi now imports rustls version 0.20, up from rustls 0.19. View the changelog.
• Configuring ciphersuites and TLS versions. Previously these could be set using setter methods on the builder object. Now they have to be set at the beginning of the config builder process, by calling rustls_client_config_builder_new_custom().
• Reading of plaintext from a rustls_connection. When the internal plaintext buffer is empty, rustls_connection_read will return RUSTLS_RESULT_PLAINTEXT_EMPTY. That means no more plaintext can be read until additional TLS bytes are ingested via rustls_connection_read_tls, and rustls_connection_process_new_packets is called. Previously this condition was indicated by returning RUSTLS_RESULT_OK with out_n set to 0.
• Handling of unclean close and the close_notify TLS alert. Mirroring upstream changes, a rustls_connection now tracks TCP closed state like so: rustls_connection_read_tls considers a 0-length read from its callback to mean "TCP stream was closed by peer." If that happens before the peer sent close_notify, rustls_connection_read will return RUSTLS_RESULT_UNEXPECTED_EOF once the available plaintext bytes are exhausted. This is useful to protect against truncation attacks. Note: some TLS implementations don't send close_notify. If you are already getting length information from your protocol (e.g. Content-Length in HTTP) you may choose to ignore UNEXPECTED_EOF so long as the number of plaintext bytes was as expected.
• rustls_version returns a rustls_str that points to a static string in memory, and the function no longer accepts a character buffer or length.
• rustls_error now takes a unsigned int instead of rustls_result directly. This is necessary to avoid undefined behavior if an invalid enum value is passed.
• Some errors starting with RUSTLS_RESULT_CERT_ have been removed, and some renamed.
• rustls_client_config_builder_set_protocols is now rustls_client_config_builder_set_alpn_protocols.
• rustls_server_config_builder_set_protocols is now rustls_server_config_builder_set_alpn_protocols.
• rustls_server_config_builder_with_client_verifier and rustls_server_config_builder_with_client_verifier_optional are replaced by rustls_server_config_builder_set_client_verifier and rustls_server_config_builder_set_client_verifier_optional, which are setters rather than constructors.
• The documented lifetime for pointers returned by rustls_connection_get_peer_certificate and rustls_connection_get_alpn_protocol has been fixed - the pointers those functions provide are valid until the next mutating function call on that connection.

Removed

• rustls_client_config_builder_from_config and rustls_server_config_builder_from_config have been removed. These were incompatible with the changes to config builders. Previously the notion of "config builder" in this library simply meant "A ClientConfig that hasn't yet been wrapped in an Arc," so we could use Clone to get a copy of one. Now "config builder" corresponds to the underlying ConfigBuilder in rustls (plus some rustls-ffi internal state), so we can't use Clone on a ClientConfig to get one. And we can't manually copy fields from a ClientConfig, since some of the necessary fields are private.
• rustls_client_config_builder_set_versions and rustls_client_config_builder_set_ciphersuites are gone - for equivalent functionality, use rustls_client_config_builder_new_custom and rustls_server_config_builder_new_custom.

0.7.2 - 2021-07-06

Added

• Adds support for TLS client certificates (servers authenticating clients), using the new rustls_client_config_builder_set_certified_key API. (#128)

0.7.1 - 2021-06-29

Changed

• Fix msvc build (#119, #120)
• Add licensing information (#117)
• Silence compiler warning in test client (#124, 125)

0.7.0 - 2021-06-24

Added

• rustls_connection_write_tls_vectored (#112)
• rustls_connection_set_log_callback (#107)
• rustls_client_config_builder methods (#108):
  • _from_config _free _use_roots _set_versions _set_ciphersuites

Changed

• make produces optimized builds by default (#114). Use PROFILE=debug for debug builds.
• As part of supporting logging, this library now has to be built with custom RUSTFLAGS. Those flags are provided when built with make.

Removed

• rustls_client_config_builder_load_native_roots (#110). This removes some linking requirements, e.g. for Security.framework on macOS.

0.6.1 - 2021-06-04

Added

• rustls_certificate_get_der to get bytes of certificate (#103)

Fixed

• rustls_connection_get_peer_certificate was returning a dangling pointer. This is now fixed by having it return a reference that lives as long as the connection does. (#103)

0.6.0 - 2021-05-20

Added

• Add clone with OCSP for certified key (#85)
• Make userdata a per-session config (#86). This makes it so callbacks can receive data associated with a specific TLS connection, whereas before they would receive data associated with a connection config (which might be shared across multiple connections).

Changed

• The separate rustls_client_session and rustls_server_session types have been merged into a single rustls_connection type. Merging these reduces duplication in both the API and the implementation, and better reflects how the underlying rustls library works. The name change, from session to connection, reflects an upcoming change in the rustls library.
• The read_tls and write_tls methods now take a callback rather than copying bytes into a buffer. This can simplify user code significantly and in particular makes it harder for user code to accidentally drop bytes from the buffer. This introduces a new rustls_io_error type that is an alias for c_int. It wraps a value from errno. Both the updated read/write functions and the callbacks they receive return rustls_io_error.

0.5.0 - 2021-04-29

Added

• ALPN support for clients (#84)
• Enumeration of ciphersuites (#79)

0.4.0 - 2021-03-18

Added

• Session storage (#64)
• TLS version numbers (#65)

Changed

• Reading plaintext can now return RUSTLS_RESULT_ALERT_CLOSE_NOTIFY. (#67)

Removed

• The rustls_cipher_signature_scheme name lookup. (#66)

0.3.0 - 2021-03-11

Added

• Expanded error handling: rustls_result has more variants. (#13)
• Allow configuring custom trusted roots. (#16)
• Use catch_unwind to prevent panicking across FFI. (#25)
• Support for TLS servers. (#30)
• Slice types: rustls_str, rustls_slice_bytes, rustls_slice_str, rustls_slice_slice_bytes, and rustls_slice_u16. (#54)
• Callback for custom certificate verifier. (#51)
• Callback for client hello inspection. (#50)

Changed

• By default, a rustls_client_config trusts no roots. (#13)

Removed

• Dependencies on webpki-roots and env_logger
• Defensive zeroing when receiving write buffers from C. C code needs to ensure write buffers are initialized before handing to crustls. (#57)