Skip to content

Conversation

CarolYeh910
Copy link
Contributor

@CarolYeh910 CarolYeh910 commented Aug 20, 2025

Release Summary:

Adds async public key support: s2n_pkey_verify() can be performed asynchronously through the async offloading callback.

Description of changes:

To improve the performance of CPU-expensive operations such as s2n_pkey_verify(), this PR implements a generic async callback to offload handshake operations that do not require user input. To execute in the async mode, applications should spawn a separate thread to invoke s2n_async_op_perform() and return success from the async offloading callback directly.

Since this async callback is expected to support more operation types in the future, we added an allow list field for users to explicitly declare the operations they want to offload. This eliminates the risk of breaking existing users when we add support for a new op type later.

Below is an overview of the code changes:

  1. Define the async offloading callback interface s2n_async_offload_cb and relevant data types.
  2. Expose the s2n_async_op_perform() function to perform the operation and update async status. If this function is invoked inside the offloading callback, it is equivalent to a synchronous use case.
  3. Add an API s2n_config_set_async_offload_callback() for users to configure their callback and the type of operations they want to execute in async mode. The default allow list is S2N_ASYNC_OP_NONE: no op type is async.
  4. Replace s2n_pkey_verify() with s2n_async_pkey_verify() to support the async functionality. s2n_pkey_verify() was invoked by s2n_server_key_recv() and s2n_client_cert_verify_recv() in TLS 1.2, as well as s2n_tls13_cert_verify_recv() in TLS 1.3.
  5. Refactor these 3 functions calling s2n_async_pkey_verify() to incorporate the re-entry logic based on the value of handshake.async_state.
  6. Create unit tests with different use cases (sync v.s. async), allow list settings, protocol versions, client auth, etc.

Call-outs:

To prevent users from accessing invalid memory accidentally, the s2n_async_op object is allocated on stack (in s2n_connection) rather than on heap. This increased the connection size by ~100 bytes and caused the s2n_connection_size_test to fail in the CI FreeBSD job:

s2n_connection size (4352) no longer in (3915, 4350). Please verify that this change was intentional and 
then update this test. (/home/runner/work/s2n-tls/s2n-tls/tests/unit/s2n_connection_size_test.c:59)

I updated max_connection_size to 4360. Open to other suggestions.

Testing:

Added a unit test for this feature and confirmed it passed.

$ cmake --build build/ --target test -- ARGS="-L unit -R s2n_async_offload_cb_test --output-on-failure"
Running tests...
Test project /home/ubuntu/s2n-tls/build
    Start 9: s2n_async_offload_cb_test
1/1 Test #9: s2n_async_offload_cb_test ........   Passed    0.26 sec

100% tests passed, 0 tests failed out of 1

Label Time Summary:
unit    =   0.26 sec*proc (1 test)

Total Test time (real) =   0.27 sec

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@github-actions github-actions bot added the s2n-core team label Aug 20, 2025
@CarolYeh910 CarolYeh910 marked this pull request as ready for review August 22, 2025 22:54
@CarolYeh910 CarolYeh910 requested a review from goatgoose August 27, 2025 18:41
@CarolYeh910 CarolYeh910 requested a review from goatgoose August 28, 2025 23:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants