Enhancement (ECH): Trial decryption and ECH connection status

[sebastian-carpenter]

Description

1. ECH trial decryption (server) — src/tls.c, src/ssl_ech.c, wolfssl/internal.h

• Previously, the server always fell back to trying every config when the configId didn't match. Now that fallback is opt-in via a new enableEchTrialDecrypt flag (off by default, matching RFC guidance).
• New API: wolfSSL_CTX_SetEchEnableTrialDecrypt() / wolfSSL_SetEchEnableTrialDecrypt().
• Also tightens TLSX_ECH_Parse rejection logic so a config lookup miss (vs. a decrypt failure) is treated as rejection cleanly.

2. ECH connection-status API — src/ssl_ech.c, wolfssl/ssl.h

• New wolfSSL_GetEchStatus() returning one of WOLFSSL_ECH_STATUS_{NOT_OFFERED, GREASE, REJECTED, ACCEPTED} for both client and server.
• Related Feature request: server-side option to require ECH (reject non-ECH clients) #10082

Testing

• test_wolfSSL_Tls13_ECH_trial_decrypt — mangles the client's configId to test trial decryption.
• Existing ECH tests (_all_algos, _no_private_name, _bad_configs, _retry_configs, _retry_configs_bad, _new_config, _GREASE, _disable_conn, _HRR_rejection, _ch2_no_ech, _ch2_decrypt_error, _rejected_cert_valid, _rejected_empty_client_cert) were updated to assert wolfSSL_GetEchStatus() on both client and server in place of the internal options.echAccepted check, covering all four status values (NOT_OFFERED, GREASE, REJECTED, ACCEPTED) including the asymmetric cases (e.g. GREASE: server NOT_OFFERED/REJECTED, client GREASE; SNI-reject: server ACCEPTED, client REJECTED).

Checklist

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

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds opt-in ECH trial decryption on the server and introduces a public API to query ECH connection status, updating tests accordingly.

Changes:

• Add CTX/SSL APIs to enable/disable ECH trial decryption (default off) and plumb the option from WOLFSSL_CTX into WOLFSSL.
• Introduce wolfSSL_GetEchStatus() + public status constants and migrate tests to assert status instead of internal flags.
• Adjust server ECH parsing logic to avoid unconditional “try every config” behavior unless trial decryption is enabled.

Reviewed changes

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

Show a summary per file

File	Description
wolfssl/ssl.h	Declares new public APIs and ECH status constants.
wolfssl/internal.h	Adds bitfields for the trial-decrypt option on ctx/options.
src/internal.c	Copies trial-decrypt option from ctx into per-SSL options at init.
src/tls.c	Changes ECH config selection + opt-in trial decryption behavior and acceptance/rejection handling.
src/ssl_ech.c	Implements trial-decrypt setters and wolfSSL_GetEchStatus().
tests/api.c	Updates ECH tests to assert wolfSSL_GetEchStatus() and adds trial-decrypt test.

---

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

[sebastian-carpenter]

Jenkins retest this please.

[github-actions]

MemBrowse Memory Report

No memory changes detected for:

• gcc-arm-cortex-m4
• gcc-arm-cortex-m4-baremetal
• gcc-arm-cortex-m4-min-ecc
• gcc-arm-cortex-m4-tls12