Add STM32 DHUK (Device Hardware Unique Key) support via crypto callbacks

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.

Author: dgarske

.wolfssl_known_macro_extras

@@ -531,6 +531,7 @@ RCC_AHB3ENR_HASHEN
 RCC_AHB3ENR_PKAEN
 RCC_AHB3ENR_RNGEN
 RCC_AHB3ENR_SAESEN
+RCC_CR_SHSION
 RCC_MP_AHB5ENSETR_CRYP1EN
 RCC_MP_AHB5ENSETR_HASH1EN
 RCC_MP_AHB5ENSETR_RNG1EN
@@ -599,6 +600,7 @@ STM32F777xx
 STM32G071xx
 STM32G491xx
 STM32H563xx
+STM32H573xx
 STM32H723xx
 STM32H725xx
 STM32H743xx
@@ -971,6 +973,8 @@ WOLFSSL_STM32C5
 WOLFSSL_STM32F3
 WOLFSSL_STM32F427_RNG
 WOLFSSL_STM32U0
+WOLFSSL_STM32_DHUK_UNWRAP
+WOLFSSL_STM32_USE_SAES
 WOLFSSL_STRONGEST_HASH_SIG
 WOLFSSL_STSAFE_TAKES_SLOT
 WOLFSSL_TELIT_M2MB

wolfcrypt/src/aes.c

@@ -4154,6 +4154,14 @@ static WARN_UNUSED_RESULT int wc_AesDecrypt(Aes* aes, const byte* inBlock,
         aes->keylen = keylen;
         aes->rounds = keylen/4 + 6;
         XMEMCPY(rk, userKey, keylen);
+    #ifdef WOLF_CRYPTO_CB
+        /* Keep a raw (non-reversed) copy for crypto-callback offload, e.g. the
+         * DHUK device reads the seed from devKey. Mirrors the generic
+         * wc_AesSetKey cryptocb path. */
+        if (keylen <= sizeof(aes->devKey)) {
+            XMEMCPY(aes->devKey, userKey, keylen);
+        }
+    #endif
     #if !defined(WOLFSSL_STM32_CUBEMX) || defined(STM32_HAL_V2)
         ByteReverseWords(rk, rk, keylen);
     #endif

wolfcrypt/src/ecc.c

@@ -7039,6 +7039,50 @@ int wc_ecc_sign_hash_ex(const byte* in, word32 inlen, WC_RNG* rng,
     return stm32_ecc_sign_hash_ex(in, inlen, rng, key, r, s);
 }
 
+#if defined(WOLFSSL_DHUK) && defined(WOLFSSL_STM32_BARE) && \
+    defined(WC_STM32_HAS_DHUK)
+/* 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
+ * (offline or on-chip) with the device key that the SAES derives from the seed;
+ * at sign time it is decrypted into a short-lived buffer. The devId is NOT set
+ * here -- enable the device by setting devId at init
+ * (wc_ecc_init_ex(&key, heap, WC_DHUK_DEVID)). See ecc.h for the contract. */
+int wc_ecc_import_wrapped_private(ecc_key* key, const byte* seed, word32 seedSz,
+                                  const byte* wrapped, word32 wrappedLen,
+                                  word32 plainLen)
+{
+    if (key == NULL || seed == NULL || wrapped == NULL) {
+        return BAD_FUNC_ARG;
+    }
+    /* Seed is the 256-bit DHUK derivation secret. */
+    if (seedSz != sizeof(key->dhuk_seed)) {
+        return BAD_FUNC_ARG;
+    }
+    /* Wrapped scalar blob must be a non-zero multiple of one AES block. */
+    if (wrappedLen == 0u || (wrappedLen % 16u) != 0u) {
+        return BAD_FUNC_ARG;
+    }
+    if (wrappedLen > sizeof(key->dhuk_wrapped_priv)) {
+        return BAD_FUNC_ARG;
+    }
+    /* Plain length must fit inside the wrapped blob and be non-zero. */
+    if (plainLen == 0u || plainLen > wrappedLen) {
+        return BAD_FUNC_ARG;
+    }
+    /* Wrapped blob must be no larger than the plaintext padded up to a full
+     * AES block; a larger blob is malformed and would overrun the fixed-size
+     * unwrap buffer used during signing. */
+    if (wrappedLen > ((plainLen + 15u) & ~15u)) {
+        return BAD_FUNC_ARG;
+    }
+    XMEMCPY(key->dhuk_wrapped_priv, wrapped, wrappedLen);
+    XMEMCPY(key->dhuk_seed, seed, seedSz);
+    key->dhuk_wrapped_priv_len = wrappedLen;
+    key->dhuk_plain_priv_len   = plainLen;
+    key->dhuk_seed_sz          = seedSz;
+    return 0;
+}
+#endif /* WOLFSSL_DHUK && WOLFSSL_STM32_BARE && WC_STM32_HAS_DHUK */
 
 #elif !defined(WOLFSSL_ATECC508A) && !defined(WOLFSSL_ATECC608A) && \
       !defined(WOLFSSL_MICROCHIP_TA100) && \
@@ -8127,6 +8171,15 @@ int wc_ecc_free(ecc_key* key)
     wc_MAXQ10XX_EccFree(key);
 #endif
 
+#ifdef WOLFSSL_DHUK
+    /* Scrub the DHUK derivation seed and wrapped scalar (both secret). */
+    ForceZero(key->dhuk_seed, sizeof(key->dhuk_seed));
+    ForceZero(key->dhuk_wrapped_priv, sizeof(key->dhuk_wrapped_priv));
+    key->dhuk_seed_sz = 0;
+    key->dhuk_wrapped_priv_len = 0;
+    key->dhuk_plain_priv_len = 0;
+#endif
+
     mp_clear(key->pubkey.x);
     mp_clear(key->pubkey.y);
     mp_clear(key->pubkey.z);

wolfcrypt/src/port/st/README.md

@@ -96,6 +96,54 @@ The STM32 PKA peripheral accelerates ECC scalar multiplication and ECDSA sign/ve
 - BARE-metal V2 PKA ECDSA sign/verify is work-in-progress -- the single-curve P-256 path is functional but multi-curve sweeps in `wolfcrypt_test` hit a -248 result on some boards. Track this in the wolfssl-examples-stm32 STM32_Bare_Test/README.
 
 
+## STM32 DHUK (Device Hardware Unique Key)
+
+Newer STM32 silicon (U3/U5/WBA/H5/C5/N6; the `WC_STM32_HAS_DHUK` family gate) carries a chip-unique 256-bit key (DHUK) burned into the SAES key-derivation path. wolfSSL exposes it through the standard crypto-callback (`WOLF_CRYPTO_CB`) framework: register the STM32 DHUK device once, init a normal `Aes` / `ecc_key` with its `devId`, then perform NORMAL wolfCrypt operations (AES, AES-GCM/GMAC, ECDSA sign) transparently. There is no separate DHUK module -- the STM32 crypto callback lives in `wolfcrypt/src/port/st/stm32.c`.
+
+A DHUK-protected key is driven by a per-key 256-bit seed. The SAES derives the device-bound working key from (seed, DHUK) inside the hardware; for symmetric operations the derived key never appears in software. For ECDSA the derived key decrypts a wrapped private scalar into a short-lived buffer only.
+
+### Enabling
+
+```
+#define WOLFSSL_DHUK         /* enable DHUK */
+#define WOLF_CRYPTO_CB       /* required -- DHUK routes through crypto callbacks */
+```
+
+`WC_STM32_HAS_DHUK` is auto-defined for the SAES+DHUK families when `WOLFSSL_DHUK` is set; other families compile out the DHUK code. `WOLFSSL_STM32_BARE` selects the bare-metal SAES backend.
+
+### API
+
+```c
+/* one-time: register the STM32 DHUK crypto-callback device */
+wc_Stm32_DhukRegister(WC_DHUK_DEVID);
+
+/* AES / GMAC: enable via devId at init, then pass the 256-bit seed as the key */
+Aes aes;
+wc_AesInit(&aes, NULL, WC_DHUK_DEVID);
+wc_AesGcmSetKey(&aes, seed, 32);
+wc_AesGcmEncrypt(&aes, NULL, NULL, 0, iv, ivSz, tag, tagSz, aad, aadSz); /* GMAC */
+wc_AesFree(&aes);
+
+wc_Stm32_DhukUnRegister(WC_DHUK_DEVID);
+```
+
+ECDSA mirrors this: init the key with `wc_ecc_init_ex(&key, NULL, WC_DHUK_DEVID)`, import the wrapped private scalar plus its derivation seed with `wc_ecc_import_wrapped_private(&key, seed, seedSz, wrapped, wrappedLen, plainLen)`, then call the normal `wc_ecc_sign_hash()`; verification uses the in-clear public key unchanged. The seed reaches the device as the AES key bytes (`aes->devKey`, set by the normal `wc_AesSetKey` / `wc_AesGcmSetKey`) or, for ECC, on the `ecc_key`; the STM32 callback reads it and derives the working key inside SAES.
+
+### Provisioning helper
+
+`wc_Stm32_Aes_Wrap()` performs a chip-bound DHUK wrap (KEYSEL=HW, deterministic output) and is retained for provisioning wrapped key material. `WOLFSSL_DHUK_DEVID` (808) / `WOLFSSL_SAES_DEVID` (807) select its wrap-key source.
+
+### Current state
+
+- Validated on STM32U385 (TZEN=0): transparent GMAC, AES-ECB, and ECDSA sign all run through the crypto-callback path; the derived key is deterministic, AES round-trips, and ECDSA verifies with the public counterpart.
+- The SAES key-derivation/unwrap passes complete via `SR.BUSY` clearing plus `SR.KEYVALID`, NOT via `CCF` (which is only raised for data-output passes). Waiting on `CCF` for the key path was the original `WC_TIMEOUT_E`; the BUSY/KEYVALID completion is the fix.
+- STM32U585 under TZEN=1 secure state: the derive currently stalls (`SR.BUSY` does not clear) -- a secure-context concern (SAES RNG / GTZC) that is open work. DHUK does not otherwise require secure state.
+
+### Optional exact-key import (off by default)
+
+`wc_Stm32_Aes_DhukOp[_ex]()` unwraps a previously DHUK-wrapped key into SAES KEYR and runs AES ECB/CBC with it (importing an externally-chosen key, vs deriving one from a seed). It is compiled only with `WOLFSSL_STM32_DHUK_UNWRAP`, is called explicitly (not auto-routed), and is not re-validated on current hardware.
+
+
 ## STM32 BARE-metal port
 
 `WOLFSSL_STM32_BARE` selects a direct-register integration with zero HAL or StdPeriLib dependency. Use this for: