Add RealTek AmebaPro2 (RTL8735B) HUK crypto-callback port#10677
Draft
dgarske wants to merge 4 commits into
Draft
Add RealTek AmebaPro2 (RTL8735B) HUK crypto-callback port#10677dgarske wants to merge 4 commits into
dgarske wants to merge 4 commits into
Conversation
Direct-register (WOLFSSL_STM32_BARE) wolfCrypt port -- no HAL/StdPeriph -- covering HASH, CRYP/TinyAES/SAES, PKA (V1 + V2) and RNG across the STM32 families (F2/F3/F4/F7/H5/H7/H7RS/L4/L5/G0/G4/U0/U3/U5/WB/WL/WBA/C0/C5/N6/ MP13). Per-family clock-enable macros are centralized via WC_STM32_CLK_EN/ WC_STM32_CLK_DIS. Includes STM32H563 'light' PKA support: H563 can ECDSA-verify in HW but not sign, so WC_STM32_PKA_VERIFY_ONLY (auto-enabled for STM32H563xx) routes sign to software while verify stays on the HW PKA; H573 keeps full PKA.
A vendor-neutral DHUK crypto-callback device (wc_Stm32_DhukRegister) that binds keys to the silicon's hardware-unique key via SAES: GMAC, AES-ECB/CBC and ECDSA-sign run with a key derived from a seed inside SAES (the key never enters software); wc_ecc_import_wrapped_private carries a wrapped scalar + seed on the ecc_key. Gated behind WOLFSSL_DHUK + WOLF_CRYPTO_CB. Includes the SAES kernel-clock fix this depends on: on STM32U5/U3 the SAES runs from the SHSI (secure HSI), which the bare driver now enables in Stm32SaesEnsureRng -- without it the wrapped-key derive never completes (CCF never asserts) and DHUK returned WC_TIMEOUT_E. Also factors the repeated SAES push/wait-CCF/read/clear idiom into Stm32SaesEcbBlock. Validated on NUCLEO-U545RE-Q and B-U585I-IOT02A (TZEN=1): all DHUK stages pass, with device-unique tags.
Binds wolfCrypt AES (GCM/ECB/CBC/CTR) to the RTL8735B silicon Hardware Unique Key via the crypto-callback (CryptoCb) framework, reusing the vendor-neutral WOLFSSL_DHUK plumbing the STM32 DHUK port introduced. A 256-bit seed is run through the HAL secure HKDF key-ladder against the HUK to land a device-bound working key in a secure key-storage slot; the working key never enters software. Enabled with WOLFSSL_REALTEK_HUK + WOLF_CRYPTO_CB. --enable-amebapro2 builds a host compile-test against a HAL shim (no silicon needed). Validated on RTL8735B silicon (FreeRTOS SDK app and Zephyr): full wolfcrypt_test PASS plus the HUK AES modes; see wolfcrypt/src/port/realtek/README.md for setup, options and benchmarks.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a new wolfCrypt crypto-callback device port for the RealTek AmebaPro2 (RTL8735B) Hardware Unique Key (HUK), enabling hardware-bound AES operations by deriving per-purpose working keys inside the SoC. It also extends shared DHUK (Device Hardware Unique Key) plumbing and improves STM32 bare-metal integration and robustness in related crypto paths.
Changes:
- Add RealTek AmebaPro2 (RTL8735B) HUK CryptoCb device (AES-GCM/ECB/CBC/CTR) plus host compile-test shim and documentation.
- Extend shared DHUK/CCB plumbing (ECC wrapped-private import API, key struct fields, scrubbing) and tighten STM32 family/build-path configuration.
- Improve STM32 bare-metal support (headers/clock macros) and harden STM32 RNG polling/recovery to avoid infinite loops.
Reviewed changes
Copilot reviewed 17 out of 18 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| zephyr/CMakeLists.txt | Adds the AmebaPro2 port source to Zephyr module build. |
| wolfssl/wolfcrypt/settings.h | Adds STM32 family/build-path gating and implies WOLFSSL_DHUK for RealTek HUK builds. |
| wolfssl/wolfcrypt/port/st/stm32.h | Expands STM32 bare-metal support macros, DHUK/CCB gating, and related prototypes. |
| wolfssl/wolfcrypt/port/realtek/amebapro2.h | Public header for registering/unregistering the AmebaPro2 HUK CryptoCb device and config macros. |
| wolfssl/wolfcrypt/include.am | Registers the new RealTek port header for distribution. |
| wolfssl/wolfcrypt/ecc.h | Adds DHUK-related fields to ecc_key and declares wrapped-private import APIs. |
| wolfssl/wolfcrypt/aes.h | Removes legacy STM32U5 DHUK fields and makes devId/devCtx purely CryptoCb-based. |
| wolfcrypt/src/random.c | Adds bounded polling + recovery for STM32 RNG and pulls in STM32 bare clock-enable macros. |
| wolfcrypt/src/port/st/README.md | Updates STM32 port documentation (families, BARE/CubeMX, DHUK, CCB). |
| wolfcrypt/src/port/realtek/README.md | Documents AmebaPro2 HUK port, build options, API usage, and limitations. |
| wolfcrypt/src/port/realtek/amebapro2.c | Implements the AmebaPro2 HUK CryptoCb device (AES paths; ECDSA sign stub). |
| wolfcrypt/src/port/realtek/amebapro2_shim.h | Host compile-test HAL shim for --enable-amebapro2. |
| wolfcrypt/src/include.am | Wires RealTek port sources/docs into the autotools build and distribution lists. |
| wolfcrypt/src/ecc.c | Adds DHUK/CCB key import helpers, scrubbing, and STM32 PKA input-validation parity. |
| wolfcrypt/src/aes.c | Routes STM32 bare AES ops through the bare driver, removes legacy DHUK flow, and stages devKey for CryptoCb. |
| configure.ac | Adds --enable-amebapro2 host compile-test option and wires it to CryptoCb enablement. |
| .wolfssl_known_macro_extras | Adds additional known macros for tooling/source checks related to new ports/STM32 work. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+7042
to
+7046
| #if defined(WOLFSSL_DHUK) && \ | ||
| ((defined(WOLFSSL_STM32_BARE) && defined(WC_STM32_HAS_DHUK)) || \ | ||
| defined(WOLFSSL_REALTEK_HUK)) | ||
| /* Import a hardware-wrapped ECC private scalar + its derivation seed onto the | ||
| * ecc_key for the DHUK crypto-callback sign path. The scalar is AES-encrypted |
Comment on lines
+164
to
+183
| if (aadSz > 0 && !WC_AMEBAPRO2_IS_ALIGNED32(aad)) { | ||
| aadBounce = (byte*)XMALLOC(aadSz, NULL, DYNAMIC_TYPE_TMP_BUFFER); | ||
| if (aadBounce == NULL) { | ||
| return MEMORY_E; | ||
| } | ||
| XMEMCPY(aadBounce, aad, aadSz); | ||
| aadA = aadBounce; | ||
| } | ||
| if (sz > 0 && !WC_AMEBAPRO2_IS_ALIGNED32(in)) { | ||
| inBounce = (byte*)XMALLOC(sz, NULL, DYNAMIC_TYPE_TMP_BUFFER); | ||
| if (inBounce == NULL) { | ||
| ret = MEMORY_E; | ||
| goto cleanup; | ||
| } | ||
| XMEMCPY(inBounce, in, sz); | ||
| inA = inBounce; | ||
| } | ||
| if (sz > 0 && !WC_AMEBAPRO2_IS_ALIGNED32(out)) { | ||
| outBounce = (byte*)XMALLOC(sz, NULL, DYNAMIC_TYPE_TMP_BUFFER); | ||
| if (outBounce == NULL) { |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Relies on #10395 which should get merged first.
Adds a wolfCrypt port that binds keys to the RealTek RTL8735B (AmebaPro2) silicon Hardware Unique Key (HUK) through the crypto-callback (CryptoCb) framework. A 256-bit seed is run through the AmebaPro2 HAL secure HKDF key-ladder against the HUK to derive a per-purpose working key in a secure key-storage slot; the working key never enters software. Applications set the seed as the AES key and use the normal wolfCrypt AES APIs.
Reuses the vendor-neutral
WOLFSSL_DHUKplumbing the STM32 DHUK port introduced (the only shared-core change is widening onewc_ecc_import_wrapped_privateguard to also recognizeWOLFSSL_REALTEK_HUK).Features
Aes' owndevKeyseed under the crypto mutex (no shared port global).NOT_COMPILED_IN).Build options
WOLFSSL_REALTEK_HUK(impliesWOLFSSL_DHUK) +WOLF_CRYPTO_CBto enable the device.--enable-amebapro2builds a host compile-test against a HAL shim (amebapro2_shim.h) so the dispatch and wiring build without the vendor SDK.WC_HUK_DEVID,WC_AMEBAPRO2_HUK_SK_IDX,WC_AMEBAPRO2_HKDF_PRK_IDX,WC_AMEBAPRO2_DERIVED_WB_IDX,WC_AMEBAPRO2_HKDF_CRYPTO_SEL) are overridable fromuser_settings.h.sp_cortexm.c(WOLFSSL_SP_ARM_CORTEX_M_ASM) for RSA/ECC/DH, and the Thumb-2 asm (WOLFSSL_ARMASM_THUMB2) for AES/SHA/ChaCha.Testing
--enable-amebapro2host compile-test builds clean; default build unaffected.wolfcrypt_testPASS, plus the HUK AES-GCM/ECB/CBC/CTR checks (deterministic tag, decrypt-verify, round-trip, wrong-seed ->AES_GCM_AUTH_E) and an explicitly-unaligned GCM check, all PASS.Documentation
wolfcrypt/src/port/realtek/README.md-- hardware, enabling, API, the key-ladder, benchmarks, optimizations, and notes/limitations.wolfssl/wolfcrypt/port/realtek/amebapro2.h-- public API and config macros.wolfssl-examplesAmebaPro2/(SDK integration + flash).