STM32 and RealTek: plaintext-key AES device + hardware AES-GCM/ECDSA via crypto callbacks

[dgarske]

Summary

Hardware AES and ECDSA through the crypto-callback framework for STM32 (CubeMX/HAL and bare-metal) and RealTek RTL8735B, so the code-size WOLF_CRYPTO_CB_ONLY_AES / WOLF_CRYPTO_CB_ONLY_ECC configs run fully on hardware. Adds a plaintext-key AES device that coexists with the existing HUK/DHUK seed-key device (selectable per Aes by devId), full hardware AES-GCM on the bare STM32 and RealTek paths, an explicit-word-order key-wrap API for offline provisioning, and a portable asn.c NULL-guard fix.

Features

• STM32 CubeMX crypto-callback device: hardware AES (ECB, and AES-GCM serviced in-callback on the HAL GCM engine) plus HW ECDSA sign + verify via the PKA and CCB-protected sign via HAL_CCB. One devId serves AES + ECDSA + CCB, making WOLF_CRYPTO_CB_ONLY_AES / WOLF_CRYPTO_CB_ONLY_ECC usable on the HAL build (that macro compiles out the direct ecc.c PKA path, so the callback has to provide HW ECDSA instead).
• Plaintext-key AES device, selectable by devId: a new device (STM32 CubeMX + bare, and RealTek) runs a caller-supplied AES key directly on the HW engine, registered alongside the DHUK/HUK seed-key device. An application picks per Aes whether its key bytes are used verbatim (WOLFSSL_STM32_AES_DEVID, default 806) or as a hardware-unique-key derivation seed (WC_DHUK_DEVID, 808). Same key bytes therefore give a standard AES-GCM result on one device and a device-bound, non-portable result on the other. 128/192/256-bit keys on the plaintext device; the DHUK device remains 256-bit-seed only.
• Full hardware AES-GCM on the bare STM32 (TinyAES peripheral: encrypt + decrypt-verify with AAD and partial blocks; CRYP IP: whole-block enc + dec) and RealTek RTL8735B. Bare TinyAES GCM previously fell back to software. AES peripherals with no GCM mode fall back to a software GHASH whose AES blocks still run on hardware. Only the standard 12-byte GCM IV takes the HW path; other IV lengths fall back to software.
• RealTek RTL8735B plaintext AES device (WOLFSSL_RTL8735B_AES, WC_RTL8735B_AES_DEVID default 811) with 128/192/256-bit keys, coexisting with the HUK device. Shapes the HW engine cannot service (non-block-multiple size, zero-length, oversized AAD) are declined with CRYPTOCB_UNAVAILABLE so software GCM completes them under the same literal key.
• wc_Stm32_Aes_Wrap_ex() with an explicit blob word order (WC_STM32_WRAP_ORDER_RAW / WC_STM32_WRAP_ORDER_LEGACY). Both build paths now share one wrap implementation, but each keeps its historical default so already-provisioned key material stays valid: CubeMX defaults to LEGACY (matching the HAL_CRYPEx_WrapKey behavior shipped in 5.9.0 - 5.9.2), bare-metal to RAW. RAW is recommended for new provisioning - it is the one format both builds agree on and the format the DHUK derive path already uses. WC_STM32_WRAP_DEFAULT_RAW_ORDER changes the plain wc_Stm32_Aes_Wrap() default build-wide. Both orders are documented with an off-target formula and measured vectors, so an offline provisioning tool can reproduce them with any AES library.
• wc_ecc_import_wrapped_private() widened to the CubeMX build: its guard was WOLFSSL_STM32_BARE-only, so the DHUK ECC sign path was unreachable from a HAL build. ecc.h now includes stm32.h under WOLFSSL_DHUK so the prototype and the ecc.c definition are gated identically - previously the guard silently evaluated false in any translation unit that had not already seen stm32.h.

Fixes

• asn.c: guard NULL OidFromId / GetAlgoV2 results in wc_EncryptPKCS8Key_ex - fixes a GCC -Wnonnull break (crypto-callback-only PKCS8 build at -O2 -Werror) and closes a latent NULL-deref on the pbeOidBuf path, matching the existing pattern in the sibling EncryptContentPBES2. No API change. Adds two tests/api.c regression tests (test_wc_EncryptPKCS8Key_ex_badHmac / _goodHmac) covering the bad-hmacOid rejection and a positive encrypt/decrypt round-trip control.
• STM32 PKA sign/verify gating: WC_STM32_PKA_VERIFY_ONLY now also compiles out the ECC scalar-multiply helpers, not just sign. The STM32H563 "light" PKA has no scalar-mul engine, so those helpers were dead weight that would not link on a verify-only part.
• STM32 build-config fixes: add the missing WOLFSSL_STM32U3 PKA include arm; #ifndef-guard the bare HASH-legacy macros so WOLFSSL_STM32_BARE coexists with the ST Cube HAL headers in a single translation unit (e.g. under Zephyr).

Documentation

• wolfcrypt/src/port/st/README.md: new sections on the crypto-callback HW path under WOLF_CRYPTO_CB_ONLY_AES / _ECC, the plaintext-key vs DHUK-seed device split with a worked devId example, and the key-wrap word orders (comparison table, off-target formula, measured NUCLEO-U385RG-Q vectors).
• wolfcrypt/src/port/realtek/README.md: the plaintext-key device, its decline-vs-hard-fail contract, and HUK coexistence.
• doc/dox_comments/header_files/stm32.h: API docs for wc_Stm32_Aes_Wrap_ex and the blob word-order constants.

Testing

Hardware, all Result: 0 (PASS):

• NUCLEO-U385RG-Q (CubeMX + bare): plaintext AES-GCM matches published vectors (encrypt + decrypt + tamper-reject), coexistence with the DHUK device (same key bytes -> distinct ciphertext per devId), CubeMX HW ECDSA sign/verify + CCB, and the RAW / LEGACY wrap-blob vectors quoted in the README.
• NUCLEO-U585 (bare): plaintext AES-GCM and DHUK-device coexistence.
• NUCLEO-F439ZI (CRYP IP): direct-call HW AES-GCM encrypt + decrypt KAT.
• RealTek RTL8735B (AmebaPro2 EVB): 67/67 including plaintext AES-GCM on the HW engine and HUK coexistence.

Host / CI:

• ./configure --enable-rtl8735b compile-test through the HAL shim; testwolfcrypt passes (RTL8735B self-test + crypto-callback test).
• ./configure --enable-all + make check: 17 pass / 6 skip / 0 fail.

Examples and on-target tests: wolfSSL/wolfssl-examples-stm32#16

[Copilot]

Pull request overview

This pull request adds STM32 CubeMX/HAL support for routing AES operations through wolfCrypt’s crypto-callback framework so WOLF_CRYPTO_CB_ONLY_AES can work on HAL-based STM32 builds (notably enabling AES-GCM key setup by providing an AES-ECB callback handler).

Changes:

• Added a CubeMX/HAL AES crypto-callback device (register/unregister + AES-ECB handling) and extended the existing CubeMX CCB crypto-callback device to also dispatch cipher callbacks.
• Fixed STM32U3 CubeMX PKA HAL include selection and improved compatibility when both “bare” STM32 code and Cube HAL HASH headers are present in the same translation unit.
• Documented usage for WOLF_CRYPTO_CB_ONLY_AES on CubeMX/HAL builds in the STM32 port README.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
wolfssl/wolfcrypt/port/st/stm32.h	Avoids HASH macro redefinition conflicts with Cube HAL headers; declares CubeMX AES crypto-callback device APIs.
wolfcrypt/src/port/st/stm32.c	Implements CubeMX AES crypto-callback device (AES-ECB) and routes cipher callbacks through the existing CubeMX CCB device; adds STM32U3 PKA includes.
wolfcrypt/src/port/st/README.md	Adds documentation describing how to enable/register the AES crypto-callback device for WOLF_CRYPTO_CB_ONLY_AES.

---

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

[github-actions]

MemBrowse Memory Report

gcc-arm-cortex-m4-openssl-compat

• FLASH: .text +64 B (+0.0%, 775,612 B / 1,048,576 B, total: 74% used)

stm32-sim-stm32h753

• FLASH: .text +64 B (+0.0%, 186,224 B / 2,097,152 B, total: 9% used)
  No memory changes detected for:
• gcc-arm-cortex-m0plus
• gcc-arm-cortex-m3
• gcc-arm-cortex-m4
• gcc-arm-cortex-m4-baremetal
• gcc-arm-cortex-m4-crypto-only
• gcc-arm-cortex-m4-dtls13
• gcc-arm-cortex-m4-min-ecc
• gcc-arm-cortex-m4-pkcs7
• gcc-arm-cortex-m4-pq
• gcc-arm-cortex-m4-rsa-only
• gcc-arm-cortex-m4-sp-math
• gcc-arm-cortex-m4-tls12
• gcc-arm-cortex-m4-tls13
• gcc-arm-cortex-m7
• gcc-arm-cortex-m7-pq
• gcc-arm-cortex-m7-tls13
• linuxkm-pie
• linuxkm-standard

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

wolfcrypt/src/port/st/README.md:101

• The example snippet always calls wc_Stm32_DhukRegister(devId), but on CubeMX/HAL that symbol is only available when WOLFSSL_STM32_CCB is enabled. For the non-CCB case (described immediately below), the snippet should instead call wc_Stm32_CubeAesRegister(devId) (or show a conditional) to avoid a link/compile mismatch for readers copying the example.

wc_Stm32_DhukRegister(devId);      /* once; serves AES + ECDSA (+ CCB) */

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

wolfcrypt/src/port/realtek/rtl8735b.c:361

• Rtl8735bAes_Gcm() returns early on keyLen > sizeof(keyA) after bounce buffers may have been allocated, which skips the cleanup path and leaks/suppresses scrubbing of the bounce allocations.

    if (keyLen > sizeof(keyA)) {
        return BAD_FUNC_ARG;
    }

wolfcrypt/src/port/st/stm32.c:2552

• TinyAES GCM final-phase length fields are written with MSW=0, which produces an incorrect tag when AAD or payload length exceeds 2^32-1 bits (~512MB). GCM specifies 64-bit bit-lengths, so the high 32 bits should be computed instead of forced to 0.

    aadBits = aadSz * 8u;
    ptBits  = sz * 8u;
    WC_STM32_AES_INST->DINR = 0u;
    WC_STM32_AES_INST->DINR = aadBits;
    WC_STM32_AES_INST->DINR = 0u;

wolfcrypt/src/port/realtek/rtl8735b.c:329

• In the plaintext-key AES device, a non-12-byte IV currently returns BAD_FUNC_ARG, which prevents the intended software fallback described for unsupported cases (and contradicts the later comment that unsupported cases return CRYPTOCB_UNAVAILABLE so callers can fall back with the same plaintext key). Returning CRYPTOCB_UNAVAILABLE here would preserve compatibility for non-96-bit IV usage where software GCM is available.

    if (ivSz != GCM_NONCE_MID_SZ) {
        return BAD_FUNC_ARG;   /* 12-byte IV only; hard error (see comment) */
    }

[dgarske]

Jenkins retest this please

[dgarske]

Jenkins retest this please

[philljj]

First pass. Looks good so far, just a few questions.

[philljj]

Retest this please.

(PRB passed, but results didn't report back).