TLS ECH Testing Improvements

[sebastian-carpenter]

Description

Original issue stems from wolfssl-examples/tls/client-ech not working. This issue was a confirmation value mismatch between Cloudflare and our ECH client implementation. The confirmation value is present in the HelloRetryRequest's encrypted_client_hello extension.

• Confirmation mismatch cause:
  • HRR requires a synthetic client hello to be hashed (as in normal TLS transcript) -> ECH transcript hash was not handling the synthetic hash correctly.
  • Random value used for HKDF was incorrect.
• Confirmation mismatch was resolved by refactoring most of the transcript code for ECH.
  • Managed to remove a transcript hash that seemed unecessary. (hsHashesEchInner)
  • Merged most of the client and server calculation for ECH transcript into similar functions.
  • Random value only copied into client hello inner once now
• Fixed segfault when server does not respond with a confirmation value
• Added OuterExtensions extension support to the server to allow testing against openssl s_client (second confirmation that transcript hash is now correct)
  • OuterExtensions will copy extensions from the outer hello into the inner hello.
  • Purpose is to have the client send less stuff over the wire.

Issues fixed when writing tests:

• ssl->options.useEch got out of sync with whether echConfigs is actually a NULL pointer. Removed it.
  • This option was not always combined with echDisabled too, so updated relevant areas.
• When generating a config the item is appended to the end of the LL of ech Configs. Seems inefficient so changed it to insert at the beginning.
• Private SNI was never verified and, in fact, the server's private SNI was replaced by the public SNI. Added field in WOLFSSL_ECH struct to store the private SNI and an enum to keep track of when to verify the public vs the private SNI.
  • Tried to preserve the SNI verification procedure regardless of if outer or inner SNI is processed.
• A wolfssl server with ECH enabled and echConfigs generated would expect ECH connections. Therefore, a client connecting without ECH would fail.
• Some tests were not checking all return values or did not test distinct issues.

Fixed some non-compliance with the ECH spec here and there too.

Based fixes off of esni draft 25 (https://www.ietf.org/archive/id/draft-ietf-tls-esni-25.html)

Addresses github issue #6925

Testing

Tested the client against a 'wild' ECH server (Cloudflare). This test is part of a wolfssl-example PR (wolfSSL/wolfssl-examples#556).

Added a github workflow to test OpenSSL interoperability. It tests a basic ECH connection between wolf client -> ossl server and ossl client -> wolf server.

Added extra tests to more strenuously test ECH:

• test_wolfSSL_SubTls13_ECH
  • Verify that ECH does not work below TLS 1.3
• test_wolfSSL_Tls13_ECH_no_private_name
  • Test what happens when wolfSSL_UseSNI() is never called on either the client or server and a connection is started.
• test_wolfSSL_Tls13_ECH_bad_configs
  • Make sure neither server nor client will connect when ech configs are incorrect. Mainly a check that SNI's match.
• test_wolfSSL_Tls13_ECH_new_config
  • Check that the server tries more than just the first config.
• test_wolfSSL_Tls13_ECH_GREASE
  • End to end test of GREASE ECH: checks that a server supports ECH / retrieves ECH configs from a server
• test_wolfSSL_Tls13_ECH_disable_conn
  • Test if a mismatch in ECH support between server / client does not cause failures. Additionally, that ECH can even be turned off. It also tests public/private SNI verification through a callback.
• test_wolfSSL_Tls13_ECH_enable_disable
  • Stress the enable/disable API for ECH

Checklist

• [X ] added tests
• updated/added doxygen
• updated appropriate READMEs
• Updated manual and documentation

[dgarske]

Code looks good. I'd like this PR to include testing as well. I don't see any. Thanks

[sebastian-carpenter]

Code looks good. I'd like this PR to include testing as well. I don't see any. Thanks

I've added testing in api.c. Let me know if there's any tests you disagree with or which I should add.

I'll be making the github workflow to test against ECH enabled openssl s_client in the meantime.

[dgarske]

Jenkins retest this please. Appears all passed, but FIPS 140-3 test reports failed. I don't think its an issue with this PR

[Copilot]

Pull request overview

This PR implements significant improvements to TLS 1.3 Encrypted Client Hello (ECH) functionality in wolfSSL. The changes address a confirmation value mismatch issue when connecting to Cloudflare's ECH implementation and add extensive testing infrastructure.

Changes:

• Refactored ECH transcript hash handling to fix HelloRetryRequest confirmation calculation
• Added support for OuterExtensions extension to enable OpenSSL s_client interoperability
• Removed ssl->options.useEch flag in favor of checking ssl->echConfigs != NULL
• Implemented private SNI verification with new state machine tracking
• Added comprehensive test suite including GitHub Actions workflow for OpenSSL ECH interoperability
• Fixed multiple spec compliance issues and improved config management

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
wolfssl/ssl.h	Changed echConfigs64 parameter to const char* for const-correctness
wolfssl/internal.h	Added TLSXT_ECH_OUTER_EXTENSIONS constant, EchStateSNI enum, privateName field to WOLFSSL_ECH struct, removed useEch option and hsHashesEchInner
tests/api/test_pkcs7.c	Initialized ret variable to prevent potential uninitialized use
tests/api.c	Added extensive ECH test coverage including parameter validation, bad configs, GREASE, enable/disable, and interop tests
src/tls13.c	Major refactoring of ECH transcript hash calculation, added EchHashHelloInner and EchCalcAcceptance functions, fixed client random handling for HRR
src/tls.c	Implemented OuterExtensions support, added SNI state machine for ECH, improved error handling and validation
src/ssl_ech.c	Changed config insertion to prepend instead of append, made echConfigs64 parameter const
src/internal.c	Removed hsHashesEchInner cleanup, updated useEch checks to echConfigs NULL checks
examples/server/server.c	Added --ech command line option and ECH config generation/display
examples/client/client.c	Added --ech command line option for setting ECH configs from base64
.github/workflows/openssl-ech.yml	New comprehensive interoperability testing workflow with OpenSSL ECH

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.