ESP32_Serial_Swiss_Army_Knife/tools/wolfssh_order/README.md

wolfSSH 1.4.20 restricted ordering correction

Project modification: 2026-09-16. This is a bounded project-profile correction for the CVE-2025-14942 ordering defect, not a complete wolfSSH 1.4.22/1.5.0 backport or general-purpose upstream-fix claim. wolfSSH remains pinned to 1.4.20; wolfSSL and all existing password/parser/crypto protections remain pinned and intact. No managed source is edited.

Inputs and provenance

793.patch, 819.patch, 840.patch, 855.patch, and 921.patch are the exact upstream mail-patch responses fetched on 2026-09-16. provenance.json records URLs, byte SHA-256 hashes, and every embedded full commit ID. PR endpoints can change: the archived bytes and commit identities, not a future PR response, identify this review. Commit pages are recoverable as https://github.com/wolfSSL/wolfssh/commit/<commit>.

delta.json is the authoritative executable consolidated delta, not a claim that all archived hunks apply. Its exact old/new edits are applied before the existing parser/password edits by tools/security_overrides.py; every anchor must occur exactly once. It pins:

Input	Original SHA-256
src/internal.c	81ff1f9166708abd5c2911e9fe57c0aee01c88b5d3f68c909ee8a856d37f36a9
src/ssh.c	a4f479ff87eea0980ec1ebdf2c7dd090da473780181b695a56799cb9611f4366
wolfssh/internal.h	8e417149a68f8a6c0506957adf014b3e6c1727a723536826ce5fb0c9e1f1aba3

Original copyright/license notices remain in each generated file, preceded by project modification/provenance notices. Configuration needs no network, patch(1), Git, or fuzzy matching. All inputs validate before outputs are written.

Prerequisite disposition

• PR793: retain stream/channel read rekey fencing, stream-send fatal/error convention, EOF/window-adjust send checks and send/receive direction constants. Exclude example, SFTP, workflow and upstream-test changes. The intermediate IsMessageAllowedKeying implementation was removed by PR855 itself; it is not resurrected. Local send checks are distinct from receive checks. The follow-up corrects a misapplied EOF hunk: SendChannelEof now checks before lookup, serialization or eofTxd mutation. The extra SendChannelExit guard is retained intentionally as local hardening, using MSGID_CHANNEL_REQUEST (exit-status), not falsely attributed to PR793's EOF hunk. Real shutdown/rekey tests cover both.
• PR819: retain extInfoSent ABI field, but supersede its negotiation/send logic by disabling EXT_INFO uniformly. The field stays zero; no reset-on-rekey or exactly-once extension continuation is needed.
• PR840: initialize keying to zero; maintain independent SELF/PEER bits; reject duplicate peer KEXINIT; respond only if SELF was not already keying; reject peer NEWKEYS while SELF still owes NEWKEYS; clear PEER and release the handshake only after successful incoming key installation.
• PR855: retain expectMsgId, message IDs/ranges, and expected-reply writes before nonblocking sends. Adapt the client DoKexDhReply hunk to 1.4.20's useEccKyber spelling; no PQ algorithm is enabled. Replace permissive range fallthrough with the explicit restricted gates described below. Upstream test-only entry points/build rules are not imported. Its new log macro is local to generated internal.c: the pinned log.h has a different WLOG implementation, so neither log.h nor log.c needs an ABI/source change.
• PR921: set server expectMsgId = MSGID_NEWKEYS before SendNewKeys, including WANT_WRITE. The former post-NEWKEYS EXT_INFO call is deliberately removed.

Local additions also set the server's expected INIT after valid KEXINIT, retain that expectation after skipping a wrong optimistic INIT guess, reject absent expectations instead of accepting arbitrary KEX packets, and only allow client rekey dispatch after successful/queued KEXINIT with a live handshake. Client rekey dispatch includes the final CONNECT_DONE state.

Restricted protocol contract

• Negotiate only the existing project KEX profile: Curve25519-SHA256 and ECDH-P256. A caller trying to widen the algorithm list to DH/GEX/PQ gets a negotiation error. Those continuation paths are not represented as supported.
• Receive transport notifications 1–4 without consuming an expected KEX reply. KEXINIT is legal only before the peer has begun this exchange; other KEX messages require a live handshake and an exact nonzero expectation. Acceptance consumes that expectation once; the handler sets the next expectation.
• Reject authentication/service/connection traffic after peer KEXINIT until peer NEWKEYS. When only SELF has initiated rekey, pre-peer-KEXINIT in-flight traffic remains legal according to the authentication phase (RFC4253).
• Server requires keyed service request, then service acceptance before userauth requests, then completed authentication before connection messages. Reject wrong-direction and repeated authentication/service messages. Client rejects premature auth results/channel messages and accepts auth responses only in its request phase. Keyboard-interactive is outside the project profile and incoming INFO_RESPONSE is rejected before dispatch.
• Send-side EOF/window-adjust checks never mutate receive expectations. Existing channel-data rekey fencing is preserved.

NEWKEYS/backpressure and the EXT_INFO choice

SendNewKeys bundles NEWKEYS with the old sending keys, installs the new sending keys, then calls wolfSSH_SendPacket. WS_WANT_WRITE means that same bundled packet remains in the bounded output buffer. Clear SELF on SUCCESS or WANT_WRITE, retain PEER and the expected peer NEWKEYS. The existing accept/connect/worker flush paths send the remaining bytes; they must not call SendNewKeys again. A fatal send does not clear SELF. Peer NEWKEYS installs the receive keys and releases the handshake once; premature/duplicate NEWKEYS fails.

Previously SendKexDhReply called SendExtInfo only on SUCCESS from NEWKEYS. A partial send skipped it with no continuation. Rather than invent another pending send state and its handshake-lifetime rules, this profile:

1. Does not append ext-info-c to client KEXINIT.
2. Ignores peers' extension willingness; sets sendExtInfo to zero on KEXINIT.
3. Removes the post-NEWKEYS extension send and makes SendExtInfo return WS_NOT_COMPILED even if called directly.
4. Rejects incoming EXT_INFO in every phase, since it was never negotiated.

This follows RFC8308's optional-negotiation model. There is no server-sig-algs advertisement. The existing KeyAccepted setter remains valid but no longer produces that extension on the wire. This matters particularly to RSA-SHA2 discovery: RSA user keys are outside the project's enrolled/advertised profile, and RSA interoperability is not claimed. Host tests establish that OpenSSH 10.2p1 still authenticates using Ed25519, P-256 and passwords with both project KEX algorithms, initial KEX and rekeys, without receiving EXT_INFO. Other clients and hardware remain validation work.

Header overlay and build ownership

The ABI changes require all consumers to use the generated header, not only the relocated C file. cmake/security_overrides.cmake installs security_overrides/wolfssh_include/wolfssh/internal.h with BEFORE PUBLIC include propagation and a PUBLIC forced include. The original header's include guard prevents a later vendor-first include path from defining a stale layout. A dated ABI marker rejects an original header forcibly included before the overlay, rather than silently skipping the corrected layout. Existing unmodified wolfSSH files and transitive application consumers therefore use the same layout. Source properties are retained; header originals, generated header, and delta.json are configure dependencies. Compiler dependencies track the forced header too. There are now eight source overrides plus one header.

Tests intentionally put the original include root before the overlay when compiling full host translation units. The SDK CMake fixture checks PUBLIC propagation to library, direct and transitive consumers. Forced headers use joined -include/path arguments: PlatformIO sorts app flags and deduplicates component flags, which breaks split option/operand pairs. The installed adapter/SCons test compiles a real Xtensa consumer and reproduces the failure with a split-option mutation. The crypto guard remains enabled with its existing joined argument. The obsolete unused EXT_INFO name constant is removed, without relaxing warnings.

Validation and boundaries

Run python3 tests/wolfssh_order_contract/run.py --interop and the related commands listed in that test's README. Tests execute the actual generated full internal.c and ssh.c with real wolfCrypt, bounded host IO, hostile message-ID matrices, partial writes, both roles and all three rekey initiation directions. Guard-removal mutations must fail. The parser/password suites separately preserve prior protections; SDK tests exercise real override/overlay CMake wiring.

Follow-up validation on 2026-09-16: authorized pio run PASS in 21.31 seconds, 94,340 B linked RAM / 1,768,701 B flash. Strict auth, protocol, crypto and SDK override tests against the rebuilt production artifacts PASS. Ordering tests PASS 8,028 checks and seven rejected mutations; parser tests PASS 3,124 cases in each stack mode. No upload, erase, dependency upgrade or device operation. This does not establish stack/heap reserve, timing, arbitrary-algorithm, strict-KEX-extension, full-client compatibility or phase-wide security sign-off.