SecureClient: hostname verification, verify-failure classification, opt-in fallback, diagnostics

[jpirnay]

Summary

Hardening for SecureClient, ported back from WitchReader (a CrossPoint derivative) where these changes have been running in the field. Five commits, each self-contained and reviewable on its own:

1. Verify the peer hostname against the certificate — the verified path loaded the CA and checked the chain, but never called wolfSSL_check_domain_name(). Chain verification alone accepts any certificate signed by a trusted root for any server, which defeats verification against an active MITM holding a valid cert for a different domain. This commit also checks the previously ignored wolfSSL_CTX_load_verify_buffer() result, so a CA PEM that fails to parse fails the connect with a clear log instead of silently leaving an empty trust store.
2. Skip the TLS 1.2 retry when verification failed — a certificate failure is deterministic; retrying with a TLS 1.2 ClientHello reaches the identical error at the cost of a second full handshake (seconds of latency plus the ECC/RSA bignum heap spike). The failed handshake's wolfSSL_get_error() code is recorded and classified; only transport/protocol failures take the version-intolerance retry. The code is reset per connect so a stale value can't misclassify a later TCP/DNS failure.
3. Opt-in insecure fallback after verify failure — setAllowInsecureFallback(true) retries a verification-class failure once without verification, logging a warning and recording the downgrade in lastConnectWasInsecure(). Rationale: readers syncing against self-hosted servers routinely meet self-signed/lapsed certificates, and without a scoped fallback users end up on permanent setInsecure(). Off by default — security-critical callers (OTA) simply never enable it and keep failing closed. Only verification-class errors (from commit 2) ever trigger it.
4. Weak wolfSSL_Arduino_Serial_Print definition — Arduino-wolfSSL's logging.c references this symbol, but its definition lives in sketch glue that a PlatformIO lib_deps build never compiles, so the documented SecureNet setup fails at link time. A weak default (routing to Serial) makes consumers link out of the box; an application definition overrides it.
5. Handshake heap-trough diagnostics — samples free-heap/largest-block across the handshake retry loop and exposes the minima via handshakeMinFree()/handshakeMinLargest(). On PSRAM-less boards the handshake is typically the heap high-water mark of the whole networking path, and ESP.getMinFreeHeap() can't isolate it. This is how we sized a single pinned root vs. a CA bundle on an ESP32-C3.

Testing

• The behavior of commits 1–3 and 5 is field-tested in WitchReader on ESP32-C3 hardware (X4) against KOSync, OPDS servers, and GitHub OTA; the port to SDK style (Serial logging, freeink namespace, fallback default off) was verified by compilation.
• Flag-on (-DFREEINK_NET_WOLFSSL=1) and flag-off builds both compile clean with -Wall -Wextra.
• Independent of SecureHttpClient: keep-alive sessions, redirects, auth, User-Agent, progress #15 — the two touch different files and merge in either order.

[itsthisjustin]

So this was somewhat purposeful to reduce flash/memory and also not worry about maintaining up to date certs. This whole logic is behind a build flag though? if so, i'm inclined to not worry about it if someone can opt out of it without any regressions?

[obey-agent]

Review (obey-agent)

Clear security/ops hardening of the wolfSSL path: PEM load failure fails closed, hostname check gated with CA verify, verification-class errors skip useless TLS 1.2 retries, opt-in insecure fallback is off by default (OTA-safe), handshake heap trough sampling, and the weak wolfSSL_Arduino_Serial_Print fixes a real PIO link break.

Findings

No high-conviction bugs in the control flow.

Suggestions

1. lastConnectWasInsecure() vs FREEINK_NET_WOLFSSL_CERTS=0 — When certs are compiled out, a connect with a configured CA still runs VERIFY_NONE but leaves _lastWasInsecure == false. Callers using the audit hook as a UI “verified” indicator will be wrong on certs-disabled builds. Consider forcing _lastWasInsecure = true on that path, or documenting that the flag is only meaningful when certs are enabled.
2. isVerificationError coverage — The switch covers the common wolfSSL/ASN cases; if you see ASN_PATHLEN_ERROR / ASN_CRIT_EXT_E in the field, fold them in so fallback/classification stays correct.

Nits

• Header reformatting (pointer style) is noise but consistent; fine.

Verdict: COMMENT only — ship when you’re ready; keep OTA on fail-closed (no insecure fallback).