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

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.

[sebastian-carpenter]

Jenkins retest this please. This passed previously and my changes to server.c only concern ech which isn't tested by the failing openssl test.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

tests/api.c:1

• Add a comment explaining the source of these base64 ECH configs (cloudflare-ech.com) and their purpose in the test to make it clearer why this specific value is used.
  tests/api.c:1
• Corrected comment on line 14035 from 'th' to 'the'.

---

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

[douzzer]

some automated test results to resolve:

[all-gcc-latest-c99-smallstack] [23 of 55] [c44ab82806]
    configure...   real 0m9.130s  user 0m5.686s  sys 0m4.471s
    build...In file included from ./wolfssl/wolfcrypt/libwolfssl_sources.h:46,
                 from src/tls.c:22:
src/tls.c: In function ‘TLSX_SNI_Parse’:
83207fc6a9 (<sebastian@wolfssl.com> 2026-02-12 10:50:45 -0700 2389)         matched = cacheOnly || (XSTRLEN(sni->data.host_name) == size &&
src/tls.c:2389:50: error: potential null pointer dereference [-Werror=null-dereference]
 2389 |         matched = cacheOnly || (XSTRLEN(sni->data.host_name) == size &&
760178c7dc (<david@wolfssl.com> 2025-05-06 12:08:35 -0700 975)     #define XSTRLEN(s1)       strlen((s1))
./wolfssl/wolfcrypt/types.h:975:39: note: in definition of macro ‘XSTRLEN’
  975 |     #define XSTRLEN(s1)       strlen((s1))
      |                                       ^~
83207fc6a9 (<sebastian@wolfssl.com> 2026-02-12 10:50:45 -0700 2389)         matched = cacheOnly || (XSTRLEN(sni->data.host_name) == size &&
src/tls.c:2389:50: error: potential null pointer dereference [-Werror=null-dereference]
760178c7dc (<david@wolfssl.com> 2025-05-06 12:08:35 -0700 975)     #define XSTRLEN(s1)       strlen((s1))
./wolfssl/wolfcrypt/types.h:975:39: note: in definition of macro ‘XSTRLEN’
  975 |     #define XSTRLEN(s1)       strlen((s1))
      |                                       ^~
83207fc6a9 (<sebastian@wolfssl.com> 2026-02-12 10:50:45 -0700 2376)     if (!cacheOnly && sni->status != WOLFSSL_SNI_NO_MATCH)
src/tls.c:2376:26: error: null pointer dereference [-Werror=null-dereference]
 2376 |     if (!cacheOnly && sni->status != WOLFSSL_SNI_NO_MATCH)
      |                       ~~~^~~~~~~~
cc1: all warnings being treated as errors
make[2]: *** [Makefile:9414: src/libwolfssl_la-tls.lo] Error 1
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [Makefile:11309: all-recursive] Error 1
make: *** [Makefile:6202: all] Error 2
   real 0m17.039s  user 3m8.865s  sys 0m5.250s
    scenario started 2026-03-06T04:23:25.795541Z, real elapsed 0m26.179175s
    all-gcc-latest-c99-smallstack fail_build
    failed config: 'EXTRA_CPPFLAGS=-Werror' '--srcdir' '.' '--disable-jobserver' '--enable-option-checking=fatal' '--enable-all' '--enable-acert' '--enable-dtls13' '--enable-dtls-mtu' '--enable-dtls-frag-ch' '--enable-dtlscid' '--enable-quic' '--with-sys-crypto-policy' '--enable-smallstack' '--enable-smallstackcache' '--enable-sp-math-all' '--enable-asn=template' 'CC=gcc-16' 'CFLAGS=-DTEST_ALWAYS_RUN_TO_END' 'CPPFLAGS=-std=c99 -pedantic -Wdeclaration-after-statement -Wnull-dereference -DTEST_LIBWOLFSSL_SOURCES_INCLUSION_SEQUENCE -Wdeclaration-after-statement -DNO_WOLFSSL_CIPHER_SUITE_TEST -DWOLFSSL_OLD_PRIME_CHECK'
    RUN_ENV: 'LD_LIBRARY_PATH=/tmp/tmp.4346_28411/wolfssl_test_workdir.10738/wolfssl/src/.libs:/usr/lib/gcc/x86_64-pc-linux-gnu/16:/usr/lib/gcc/x86_64-pc-linux-gnu/16/32'

[sebastian-carpenter]

Not in description but commit 56e877f [corrections for ECH specification] fixes F-27.

For the purpose of cutting down on PR's I have also pulled in some extra ECH changes into this PR:

• Fixes related to F-292, F-28. Related to above mentioned commit.
• And F-293, F-201, F-358, F-203