ESP32_Serial_Swiss_Army_Knife/tests/wolf_crypto_policy/README.md

Bounded wolf crypto compile policy

Project-owned configuration for pinned wolfSSL 5.8.2~1 / wolfSSH 1.4.20; no installed vendor edits, dependency upgrades, generated override edits or blanket security clearance. See the key-validation review for exact source hashes, applicability, upstream guidance and remaining gaps.

Policy

• Existing root definitions CURVE25519_SMALL / ED25519_SMALL follow PR9275's Xtensa mitigation. Small math is incompatible with this version's X25519 blinding; do not mix ABI-sensitive library and consumer settings. Curve448/Ed448 require review.
• cmake/wolf_crypto_policy.cmake now PUBLIC-defines WOLFSSL_VALIDATE_ECC_IMPORT and WOLFSSL_ECDHX_SHARED_NOT_ZERO, enabling existing upstream P256 import and X25519 result checks. The root already includes this module; no root edit is needed.
• The PUBLIC forced-include guard checks resolved settings and rejects missing requirements and known ECC validator-disabling/hardware-stub configurations. Existing RNG callback and software AES/SHA controls are unchanged.

Commands

# Offline host subset; no target compiler/database required:
python3 tests/wolf_crypto_policy/run.py --host-only

# Explicit candidate replay before production reconfiguration:
python3 tests/wolf_crypto_policy/run.py --candidate

# Strict production evidence after the parent reconfigures/builds:
python3 tests/wolf_crypto_policy/run.py

Optional database argument:

python3 tests/wolf_crypto_policy/run.py --compile-commands .pio/build/esp32-s3-devkitc-1-n16r8/compile_commands.json

Candidate mode injects all four policy definitions and the guard into saved commands. It is not production configuration/build evidence. Strict mode injects nothing, and must fail with stale commands lacking the new flags. No mode runs PlatformIO, regenerates overrides or communicates with a device.

Coverage

All modes:

• 20 fail-closed guard matrix cases.
• A temporary CMake project includes the actual production policy module and verifies PUBLIC definitions/guard across wolf library → SSH → app targets. This is a stand-in graph, not an ESP-IDF build.
• Compile installed small implementations and run RFC7748 X25519 and RFC8032 Ed25519 vectors plus corrupted-signature rejection. Check two nontrivial low-order X25519 points that pass the vendor public precheck but must fail shared-secret calculation without copying output; also reject zero/one inputs.
• Compile installed TFM ECC, ASN template, signature and supporting primitives. Test explicit/inferred P256 import of valid G and rejection of off-curve, infinity, out-of-range, truncated and wrong-tag inputs; valid ECDH; raw and DER-wrapper ECDSA valid/invalid verification; valid SEC1 private DER decoding without a pre-attached RNG and rejection of an invalid embedded public point. Test scalar/nonce values are deliberately public test values, never real keys.

Target modes additionally:

• Pin original wolfSSH internal.c and wolfCrypt ecc.c, curve25519.c, signature.c; locate the actual generated wolfSSH compile input and compare seven complete audited crypto/auth/hash function bodies: five must remain identical, while ECC/Ed25519 authentication must match independently specified exact label/framing deltas reconstructed from the hash-pinned original, with exact anchor counts. Expectations are not imported from the generator. Any additional change requires re-audit, not repinning or skipping a body. This does not validate the entire override generator. Generated hash is printed.
• Replay actual Xtensa compiler/includes for macro and syntax checks of twelve translation units: ECC, signature wrapper, Curve25519, Ed25519, fast/small field/group math, wolfSSH ssh.c, generated internal.c, application SSH transport and security. Confirm internal HAVE_ECC_CHECK_PUBKEY_ORDER in ECC.
• Four negative actual-settings tests remove one policy flag at a time.

Requirements: Python 3, CMake, host cc/linker, installed managed sources; target modes also require the existing Xtensa toolchain, generated headers and compilation database. Subprocesses have time bounds and temporary artifacts are removed. No replacement crypto implementation or crypto success double is used.

Evidence and remaining gates — 2026-09-15

Follow-up strict production run PASS without candidate injection, including all host tests (20 guard cases, three-target CMake propagation, real crypto and ASN vectors), seven complete source-body comparisons with reviewed exact parser deltas, twelve target macro/syntax checks and four negative target-settings cases. Earlier candidate and host-only runs also passed; the final ASN-decode cases passed in candidate and strict runs. Earlier development runs required correcting fixture settings/linkage; they are not additional production failures. Host settings retain TFM, timing resistance and small-stack allocation for ECC, but differ in word size, allocator, OS entropy and hardware/compiler configuration. No sanitizer, exhaustive fuzzing, allocation-failure injection or timing result is claimed.

The parent reports pio run PASS: 94,340 B linked RAM / 1,768,949 B flash. This agent did not run PlatformIO or devices; local strict checks validate the saved production compile profile, not a flashed image. Hardware tests remain necessary for both KEX algorithms, P256/Ed25519 authentication, host-key loading, rekey, malformed-key failure/cleanup, combined load, stack/heap reserves and handshake deadlines. Extra import validation has real CPU/allocation cost.

The parser owner separately fixed ECC/Ed25519 labels, ECC nested exact bounds and Ed25519 outer consumption in the generated input. Those changes are checked by this suite's exact source contract, not supplied by crypto compile flags. The parser suite was reviewed, not rerun in this follow-up; its crypto doubles establish parser gating, not real signature arithmetic. Broader ordering/state review, standalone ECC key-blob semantics outside application checks, generic wolfSSL digest/OID API hardening as applicable, and hardware gates remain open; see the review for evidence and limits.