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

.github/workflows/pkg-config.yaml

@@ -20,6 +20,7 @@ jobs:
       matrix:
         cc: [ clang, gcc ]
         os: [ ubuntu-latest, macos-latest ]
+        crypto: [ aws-lc-rs, ring ]
     steps:
       - name: Checkout sources
         uses: actions/checkout@v4
@@ -54,10 +55,10 @@ jobs:
         #       that will complicate setting PKG_CONFIG_PATH/LD_LIBRARY_PATH.
         run: >
           CARGOFLAGS=--libdir=lib
-          make --file=Makefile.pkg-config PREFIX=${PREFIX} install
+          make --file=Makefile.pkg-config PREFIX=${PREFIX} CRYPTO_PROVIDER=${{ matrix.crypto }} install
 
       - name: Build the client/server examples
-        run: PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig make --file=Makefile.pkg-config PROFILE=debug
+        run: PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig make --file=Makefile.pkg-config PROFILE=debug CRYPTO_PROVIDER=${{ matrix.crypto }}
 
       - name: Verify client is dynamically linked (Ubuntu)
         if: matrix.os == 'ubuntu-latest'
@@ -76,4 +77,4 @@ jobs:
         run: LD_LIBRARY_PATH=$PREFIX/lib otool -L target/server | grep "rustls"
 
       - name: Run the integration tests
-        run: LD_LIBRARY_PATH=$PREFIX/lib make --file=Makefile.pkg-config PROFILE=debug integration
+        run: LD_LIBRARY_PATH=$PREFIX/lib make --file=Makefile.pkg-config PROFILE=debug CRYPTO_PROVIDER=${{ matrix.crypto }} integration

.github/workflows/test.yaml

@@ -16,20 +16,22 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        # test a bunch of toolchains on ubuntu
-        cc: [clang, gcc]
+        # test a bunch of toolchain and crypto providers on ubuntu
+        cc: [ clang, gcc ]
+        crypto: [ aws-lc-rs, ring ]
         rust:
           - stable
           - beta
           - nightly
           # MSRV - keep in sync with what rustls and rustls-platform-verifier
           # consider MSRV
           - 1.64.0
-        os: [ubuntu-latest]
-        # but only stable on macos/windows (slower platforms)
+        os: [ ubuntu-latest ]
+        # but only stable, clang, and aws-lc-rs on macos (slower platform)
         include:
           - os: macos-latest
             cc: clang
+            crypto: aws-lc-rs
             rust: stable
     steps:
       - name: Checkout sources
@@ -41,11 +43,19 @@ jobs:
         uses: dtolnay/rust-toolchain@master
         with:
           toolchain: ${{ matrix.rust }}
-      - env:
+      - name: Unit tests
+        env:
           CARGO_UNSTABLE_HTTP_REGISTRY: true
-        run: make CC=${{ matrix.cc }} PROFILE=debug test integration
+        run: make CC=${{ matrix.cc }} PROFILE=debug CRYPTO_PROVIDER=${{ matrix.crypto }} test
       - name: Platform verifier connect test
-        run: make PROFILE=debug connect-test
+        run: make PROFILE=debug CRYPTO_PROVIDER=${{ matrix.crypto }} connect-test
+      - name: Integration tests
+        env:
+          CARGO_UNSTABLE_HTTP_REGISTRY: true
+        # Note: we run this after the connect-tests because the static libs test rebuilds the crate
+        #       squashing whatever RUSTFLAGS the Makefile has set and producing a librustls_ffi.a
+        #       for the default build config.
+        run: make CC=${{ matrix.cc }} PROFILE=debug CRYPTO_PROVIDER=${{ matrix.crypto }} integration
       - name: Verify debug builds were using ASAN
         if: runner.os == 'Linux' # For 'nm'
         run: |
@@ -54,7 +64,7 @@ jobs:
       - name: Build release binaries
         run: |
           make clean
-          make CC=${{ matrix.cc }} PROFILE=release
+          make CC=${{ matrix.cc }} CRYPTO_PROVIDER=${{ matrix.crypto }} PROFILE=release
       - name: Verify release builds were not using ASAN
         if: runner.os == 'Linux' # For 'nm'
         run: |
@@ -75,37 +85,47 @@ jobs:
   test-windows-cmake-debug:
     name: Windows CMake, Debug configuration
     runs-on: windows-latest
+    strategy:
+      matrix:
+        crypto: [ aws-lc-rs, ring ]
     steps:
       - uses: actions/checkout@v4
         with:
           persist-credentials: false
       - name: Install nightly rust toolchain
         uses: dtolnay/rust-toolchain@nightly
+      - name: Install NASM for aws-lc-rs
+        uses: ilammy/setup-nasm@v1
       - name: Configure CMake
-        run: cmake -S . -B build
+        run: cmake -DCRYPTO_PROVIDER="${{ matrix.crypto }}" -S . -B build
       - name: Build, debug configuration
         run: cmake --build build --config Debug
       - name: Integration test, debug configuration
-        run: cargo test --locked --test client_server client_server_integration -- --ignored --exact
+        run: cargo test --no-default-features --features="${{ matrix.crypto }}" --locked --test client_server client_server_integration -- --ignored --exact
         env:
           CLIENT_BINARY: D:\a\rustls-ffi\rustls-ffi\build\tests\Debug\client.exe
           SERVER_BINARY: D:\a\rustls-ffi\rustls-ffi\build\tests\Debug\server.exe
 
   test-windows-cmake-release:
     name: Windows CMake, Release configuration
     runs-on: windows-latest
+    strategy:
+      matrix:
+        crypto: [ aws-lc-rs, ring ]
     steps:
       - uses: actions/checkout@v4
         with:
           persist-credentials: false
       - name: Install nightly rust toolchain
         uses: dtolnay/rust-toolchain@nightly
+      - name: Install NASM for aws-lc-rs
+        uses: ilammy/setup-nasm@v1
       - name: Configure CMake
-        run: cmake -S . -B build
+        run: cmake -DCRYPTO_PROVIDER="${{ matrix.crypto }}" -S . -B build
       - name: Build, release configuration
         run: cmake --build build --config Release
       - name: Integration test, release configuration
-        run: cargo test --locked --test client_server client_server_integration -- --ignored --exact
+        run: cargo test --no-default-features --features="${{ matrix.crypto }}" --locked --test client_server client_server_integration -- --ignored --exact
         env:
           CLIENT_BINARY: D:\a\rustls-ffi\rustls-ffi\build\tests\Release\client.exe
           SERVER_BINARY: D:\a\rustls-ffi\rustls-ffi\build\tests\Release\server.exe
@@ -123,7 +143,7 @@ jobs:
         # reliably matched to CI. There can be non-semantic differences in
         # output between point releases of cbindgen that will fail this check
         # otherwise.
-        run: cargo install cbindgen --force --version 0.24.5
+        run: cargo install cbindgen --force --version 0.27.0
       - run: touch src/lib.rs
       - run: cbindgen --version
       - run: make src/rustls.h
@@ -161,8 +181,11 @@ jobs:
       - name: Build client/server binaries
         run: make target/client target/server
 
-      - name: cargo test (debug; all features; -Z minimal-versions)
-        run: cargo -Z minimal-versions test --all-features --locked
+      - name: cargo test (debug; default features; -Z minimal-versions)
+        run: cargo -Z minimal-versions test --locked
+
+      - name: cargo test (debug; ring; -Z minimal-versions)
+        run: cargo -Z minimal-versions test --no-default-features --features=ring --locked
 
   format:
     name: Format
@@ -200,6 +223,8 @@ jobs:
         # If we suppress (e.g. #![allow(clippy::arc_with_non_send_sync)]),
         # we would get an unknown-lint error from older clippy versions.
         run: cargo clippy --locked --workspace --all-targets -- -D warnings -A unknown-lints
+      - name: Check clippy (ring)
+        run: cargo clippy --locked --workspace --all-targets --no-default-features --features=ring -- -D warnings -A unknown-lints
 
   clippy-nightly-optional:
     name: Clippy nightly (optional)
@@ -215,6 +240,8 @@ jobs:
           components: clippy
       - name: Check clippy (default features)
         run: cargo clippy --locked --workspace --all-targets -- -D warnings
+      - name: Check clippy (ring)
+        run: cargo clippy --locked --workspace --all-targets --no-default-features --features=ring -- -D warnings
       - name: Check clippy (all features)
         # We only test --all-features on nightly, because two of the features
         # (read_buf, core_io_borrowed_buf) require nightly.

CHANGELOG.md

@@ -1,5 +1,137 @@
 # Changelog
 
+## 0.14.0 (2024-08-01)
+
+This release updates to [Rustls 0.23.12][] 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.
+
+[Rustls 0.23.12]: https://github.com/rustls/rustls/releases/tag/v%2F0.23.12
+[`aws-lc-rs`]: https://github.com/aws/aws-lc-rs
+
+### 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 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()`.
+
+* When using `aws-lc-rs` as the crypto provider, NIST P-521 signatures are now
+  supported.
+
+[`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier
+
+### 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

CMakeLists.txt

@@ -1,24 +1,38 @@
 cmake_minimum_required(VERSION 3.15)
 
 project(rustls-ffi)
+
+set(CRYPTO_PROVIDER "aws-lc-rs" CACHE STRING "Crypto provider to use (aws-lc-rs or ring)")
+
+if (NOT (CRYPTO_PROVIDER STREQUAL "aws-lc-rs" OR CRYPTO_PROVIDER STREQUAL "ring"))
+    message(FATAL_ERROR "Invalid crypto provider specified: ${CRYPTO_PROVIDER}. Must be 'aws-lc-rs' or 'ring'.")
+endif ()
+
+set(CARGO_FEATURES --no-default-features)
+if (CRYPTO_PROVIDER STREQUAL "aws-lc-rs")
+    list(APPEND CARGO_FEATURES --features=aws-lc-rs)
+elseif (CRYPTO_PROVIDER STREQUAL "ring")
+    list(APPEND CARGO_FEATURES --features=ring)
+endif ()
+
 add_subdirectory(tests)
 
 include(ExternalProject)
 set_directory_properties(PROPERTIES EP_PREFIX ${CMAKE_BINARY_DIR}/rust)
 
 ExternalProject_Add(
-	rustls-ffi
-	DOWNLOAD_COMMAND ""
-	CONFIGURE_COMMAND ""
-	BUILD_COMMAND ""
-	COMMAND cargo build --locked "$<IF:$<CONFIG:Release>,--release,-->"
-	# Rely on cargo checking timestamps, rather than tell CMake where every
-	# output is.
-	BUILD_ALWAYS true
-	INSTALL_COMMAND ""
-	# Run cargo test with --quiet because msbuild will treat the presence
-	# of "error" in stdout as an error, and we have some test functions that
-	# end in "_error". Quiet mode suppresses test names, so this is a
-	# sufficient workaround.
-	TEST_COMMAND cargo test --locked "$<IF:$<CONFIG:Release>,--release,-->" --quiet
+        rustls-ffi
+        DOWNLOAD_COMMAND ""
+        CONFIGURE_COMMAND ""
+        BUILD_COMMAND ""
+        COMMAND cargo build --locked ${CARGO_FEATURES} "$<IF:$<CONFIG:Release>,--release,-->"
+        # Rely on cargo checking timestamps, rather than tell CMake where every
+        # output is.
+        BUILD_ALWAYS true
+        INSTALL_COMMAND ""
+        # Run cargo test with --quiet because msbuild will treat the presence
+        # of "error" in stdout as an error, and we have some test functions that
+        # end in "_error". Quiet mode suppresses test names, so this is a
+        # sufficient workaround.
+        TEST_COMMAND cargo test --locked ${CARGO_FEATURES} "$<IF:$<CONFIG:Release>,--release,-->" --quiet
 )