ESP32_Serial_Swiss_Army_Knife/tests/sdk_security_overrides/README.md

Pinned SDK security overrides

The root CMakeLists.txt includes cmake/security_overrides.cmake after project(). No component/vendor file is edited, and no global crypto feature or client ciphersuite setting is changed.

Build contract

tools/security_overrides.py requires the installed ESP-IDF version header to identify 5.5.3, and checks each complete original source against its reviewed SHA256. Every text substitution must match exactly once. The entire input plan is validated before any output is written. A changed SDK, missing source, ambiguous edit, duplicate source, or missing/ambiguous component target fails configuration; there is no unpatched fallback or automatic hash repinning.

Derived full files, retaining the original copyright/license notices, live only at <CMAKE_BINARY_DIR>/security_overrides/<entry-name>/<basename>. Every generated source is centrally prefixed with an explicit Modified by the ESP32_serial_swiss_army_knife project on 2026-09-15 notice. This is separate from, and does not rewrite or replace, upstream notices. The manifest and derived files are atomically replaced only when their bytes change. Output paths cannot escape the binary tree or alias SDK/source files. CMake tracks the generator, version header, originals, and derived sources for reconfiguration. The included CMake file is itself an ordinary CMake input. Requirements: Python 3.9+ and CMake 3.18+ (directory-scoped source properties).

CMake replaces the exact original entry in the existing component's SOURCES; it does not add a second definition or replace the component target. Target compile settings remain intact. Source compile flags/options/definitions, per-configuration definitions, source includes and object dependencies are copied in the target's owning directory. The original C file's directory is prepended to that source's include search path, preserving quoted local headers. Source generator expressions are rejected rather than guessed through.

Current corrections

• esp_https_server:src/https_server.c: delete TLS if post-handshake transport allocation fails; destroy the complete secure context if HTTPD start fails; wipe exactly serverkey_bytes before releasing the raw private-key copy. Failed start restores the original open callback and clears stale transport context/destructor pointers. Failed stop retains live ownership.

• esp_http_server:src/httpd_parse.c: allocate/copy/wipe/free scratch resize, retaining old storage on failure; wipe current scratch on final cleanup. Initial reads avoid null-pointer subtraction and preserve a null parser position until a callback sets it; existing positions relocate with scratch. Existing shrink/grow behavior and bounds remain. Resizing briefly owns old plus new allocations; no persistent maximum-size buffer, socket, task or limit increase. Pending/unread bytes are not erased or drained by the patch.

• esp-tls:esp_tls_mbedtls.c: server-local static-lifetime allowlist of TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 and TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, terminated by zero, configured after server defaults and before setup. Both version limits are TLS 1.2; renegotiation is disabled (or absent at compile time). Required TLS/ECDHE/ ECDSA/AES/GCM/SHA features are compile-guarded. IDF dynamic buffers are rejected because their destructor bypasses the audited upstream record-buffer wipe. set_client_config() and the shared handle/setup path are unchanged.

• wolfssl__wolfssh:src/internal.c: pins wolfSSH 1.4.20's original source SHA256 to 81ff1f9166708abd5c2911e9fe57c0aee01c88b5d3f68c909ee8a856d37f36a9. GetSize() bounds password and new-password fields before authentication; malformed parsing cannot reach the auth callback. The checked packet suffix is wiped before failure responses, preserving the caller's prefix. Pending asynchronous authentication retains the payload for retry; this is not an async secret-lifetime/wipe guarantee. Generated parser/control-flow tests live in tests/wolfssh_auth_contract/.

• lwip:apps/dhcpserver/dhcpserver.c: PAD/END handling, length-byte and declared-payload bounds, minimum message-type/requested-IP lengths, validated advancement. Backport of official d51b1076092487e533eadf8b48c9c8579d3a6712. The only behavioral-code deviation is using equivalent remaining-length comparisons rather than constructing pointers beyond the input object. Original copyright years stay unchanged under the separate modification notice.

• Nested mbedtls:ssl_tls.c: propagate calc_verify() failure immediately, before PRF/master-secret derivation. Exact TLS 1.2 hunk of f595df4569c1a1650ad9d077e2f2e819e9f1dddb. EMS remains enabled. This does not backport that commit's TLS 1.3 hunk.

• Nested mbedx509:x509_create.c: reject known-attribute OID allocation failure before memcpy(), returning MBEDTLS_ERR_X509_ALLOC_FAILED. Exact guard from bfaf4a47fd33da860796feaba6235847acb71127.

These three patches were fetched from the official repositories and compared with the installed pinned sources on 2026-09-15. That original implementation did not change dependency versions or source hashes; the current 5.5.3 rebase has separately reviewed original hashes (see docs/idf_553_rebase_review.md). The optional WS subprotocol backport and separate ASN.1 repeated-OID/empty-value correction are not implemented.

Clients that cannot negotiate this server profile will no longer connect. Live interoperability and resource/latency testing remain hardware gates. These corrections do not claim comprehensive zeroization of every TLS/library copy, compiler spill, accelerator register, browser buffer or allocator region.

Parent extension point

Add an Entry to tools/security_overrides.py:ENTRIES with:

• unique name;
• exact IDF component name (used by idf_component_get_property);
• root="idf" for installed IDF sources, or root="project" for project/vendor sources;
• exact relative source, full reviewed sha256, and a tuple of Edit(old,new) exact-once substitutions;
• optional target for the explicitly supported mbedtls, mbedx509 or mbedcrypto nested library under component mbedtls. Empty selects the component's COMPONENT_LIB as before. CMake validates the nested target exists, is not imported/an alias, and belongs to the installed mbedTLS library directory.

render_entry() validates/patches an entry; generate() accepts an explicit entry tuple as well as the default registry. The manifest maps each entry to its component, optional nested target, original and derived source. CMake's sak_security_replace_source(component original generated nested_target) handles replacement on the actual source owner, not the IDF mbedTLS wrapper. The current registry has seven IDF C sources, two project-managed wolfSSH C sources and one wolfSSH header overlay. Update the corresponding library-specific feature/behavior tests when extending the registry. Multiple sources in the same real component are supported by the replacement function.

Do not change a source hash merely to make a new SDK configure. Re-audit ownership, cleanup, feature resolution and patches against that source revision first.

Validation

python3 tests/sdk_security_overrides/run.py
python3 tests/sdk_security_overrides/run.py --build-dir .pio/build/esp32-s3-devkitc-1-n16r8

Optional --idf-path selects an existing installed SDK. Tests need host cc, CMake and Ninja; they install nothing, use temporary directories under .pio/, and never edit the selected SDK. Run the second command after the parent runs pio run; old generated copies lack the new entries/notice and must not pass. It checks real firmware Ninja registration: exactly one compilation of each derived source, no original compilation, and exact generated bytes. It does not run a firmware build.

Candidate WebSocket receive regression

CCACHE_DISABLE=1 python3 -B tests/sdk_security_overrides/run.py --idf-path .pio/idf-candidate-5.5.3/core/packages/framework-espidf
CCACHE_DISABLE=1 python3 -B tests/web_serial_performance/run.py --idf-path .pio/idf-candidate-5.5.3/core/packages/framework-espidf

Either runner accepts --build-dir .pio/idf-candidate-5.5.3/app/.pio/build/esp32-s3-devkitc-1-n16r8 for strict existing-build evidence. The performance runner otherwise renders the current hash-verified WS override; it never falls back to vendor WS code. Its build mode verifies exactly one generated compilation input, its HTTPD owner, original-source absence and byte equality with the current override. A stale build missing the WS replacement must fail; parent reconfiguration/build is separate.

ws.c executes complete generated httpd_ws_get_frame_type, httpd_ws_recv_frame, unmask/check/send-wrapper functions and complete hash-pinned vendor httpd_recv_with_opt/httpd_recv_pending, not copied conditional snippets. The send endpoint and socket receive callback are bounded doubles. Its 982 cases cover all five header sites (first/second byte, 2/8-byte length, 4-byte mask), negative failure/timeout, EOF, every shorter prefix, split socket reads, pending prefixes plus timeout (positive short returns), successful binary decode, length probe/resume, nontrivial extended lengths, automatic PING/PONG and CLOSE. Input ends at a guard page; output/mask canaries, exact byte consumption and send/callback counts enforce no payload read or output after framing failure. UBSan trap instrumentation is enabled.

The tests deliberately do not assert transactional rollback: failed first-byte reads return ESP_OK with final/CLOSE metadata; other failed reads retain already decoded type/final/length or partially received mask bytes. They assert that exact state and that no automatic reply follows failed control framing. Five individual cast removals must fail strict compilation with sign-compare; five explicit unsigned-promotion equivalents must compile with warnings-as-errors and then fail behavioral assertions. No diagnostic suppression is used for these mutations. This is host framing evidence, not live sockets, target ABI/timing or firmware integration evidence.

Coverage:

• Generator full-source hashes, version, missing/duplicate/ambiguous inputs, exact edit counts, validation-before-output, unchanged-byte/mtime idempotence, unsafe output rejection, centrally applied dated modification notice exactly once on every source, and preserved upstream opening notices.
• Extracted patched actual functions, not reimplemented cleanup logic: HTTPS allocation failure matrix; handshake failure; post-handshake allocation failure; HTTPD start failure; normal close/stop; failed stop preserving ownership. The unmodified installed httpd_stop() is extracted and separately pinned. Allocator doubles assert key bytes are zero before free, with trailing canaries to reject over-wiping, and detect leaks/double frees.
• Actual patched scratch helper/read/cleanup functions: grow, shrink, no-change, null-initial first-read success/failure, nullable parser-position preservation, resize failure preserving the old pointer, receive errors/timeouts, size bounds, final wipe and original right-aligned pending-byte behavior. Installed pending/unrecv functions are separately pinned and executed. This is not a full HTTP parser fuzz test.
• Actual server/client configuration functions with crypto/config doubles: allowlist order/terminator/static lifetime, defaults failure, PKI failure, version limits, renegotiation enabled/compiled-out variants, untouched default and caller-provided client suites. Every required feature is individually removed in compile-failure tests; dynamic-buffer enablement also fails.
• Extracted DHCP parser: 196,623 guard-page cases covering empty/lone-code, every option code/length with truncated and complete payloads, PAD, END, short type/IP, DISCOVER/REQUEST/DECLINE/RELEASE, renew, matching/mismatching IP. Compare the remaining-length variant with upstream pointer-form checks on safely padded backing storage; post-loop state behavior is retained.
• Extracted TLS master calculation: SHA-256/SHA-384-sized transcript doubles, untouched output and no PRF on hash failure (including unchanged length 64), successful EMS, PRF failure, non-EMS and resumed-session behavior. This does not execute actual hashes, the full handshake driver, or its failure destructor.
• Extracted X.509 parser and its actual attribute table/helpers, compiled against installed mbedTLS headers: fault each allocation across separate subject/issuer lists, partial-list cleanup, second-attribute OID failure, and successful retry. Named-data storage/free are allocation-counted doubles; certificate signing, writer destruction, persistence/publication and old-identity retention are not exercised here. The three new C harnesses use UBSan trap instrumentation; this does not require the host UBSan runtime.
• The actual CMake include under fake IDF target discovery, including missing and duplicate sources/targets, nested target owner validation, and exact Ninja compilation registration on both mbedtls and mbedx509 (not their wrapper). A separate real host compile tests the project-root extension, child-directory relative SOURCES, quoted and source-specific includes, source/target flags and per-config source definitions. Changing that fixture's original file makes the next ordinary build reconfigure and reject its hash instead of compiling stale derived code.

No tests here perform real TLS handshakes, network/device operations, allocation failure on the target, or whole-Phase-9 hardware acceptance.