stm32.h

Functions

	Name
int	wc_Stm32_DhukRegister(int devId) This function registers the STM32 DHUK (Device Hardware Unique Key) crypto-callback device. After registering at WC_DHUK_DEVID, bind an object to the device by setting its devId at init (wc_AesInit / wc_ecc_init_ex) and supply the per-key 256-bit seed as the key (wc_AesGcmSetKey) or via wc_ecc_import_wrapped_private; normal wolfCrypt AES / GMAC / ECDSA calls then run transparently with the working key derived inside the SAES. Available on STM32 builds with WOLFSSL_DHUK, WOLF_CRYPTO_CB, and a DHUK-capable SAES (WC_STM32_HAS_DHUK); on the CubeMX path it is also provided for CCB ECDSA.
void	wc_Stm32_DhukUnRegister(int devId) This function unregisters the STM32 DHUK crypto-callback device that was registered with wc_Stm32_DhukRegister. Call it once transparent DHUK / CCB operations are complete.
int	wc_Stm32_Aes_Wrap(struct Aes * aes, const byte * in, word32 inSz, byte * out, word32 * outSz, const byte * iv, int ivSz) This function performs a chip-bound DHUK AES key-wrap on the SAES (KEYSEL=HW, deterministic output) for provisioning wrapped key material. It is the inverse of the SAES wrapped-key load: the blob unwraps back to the key it wrapped, and matches ST's HAL_CRYPEx_WrapKey() output on the same die. The wrap-key source is selected by aes->devId (WOLFSSL_DHUK_DEVID for the hardware DHUK, otherwise a software key in aes->key; WOLFSSL_SAES_DEVID is a marker for that second case, not a device to register). An optional iv selects CBC instead of ECB. Produces WC_STM32_WRAP_ORDER_RAW on both build paths. Available on STM32 builds with WOLFSSL_DHUK and a DHUK-capable SAES.
int	wc_Stm32_Aes_Wrap_ex(struct Aes * aes, const byte * in, word32 inSz, byte * out, word32 * outSz, const byte * iv, int ivSz, int rawOrder) This function is wc_Stm32_Aes_Wrap() with the blob word order given explicitly. Available on STM32 builds with WOLFSSL_DHUK and a DHUK-capable SAES.
int	wc_Stm32_CcbInit(void ) This function brings up the STM32 CCB (Coupling and Chaining Bridge) peripheral and reports whether it is usable: it enables the CCB / PKA / SAES / RNG clocks, pulse-resets the engines, waits for BUSY to clear, and checks for an operation error. Bare-metal only (WOLFSSL_STM32_BARE). The transparent CCB sign path calls this internally, so most callers do not invoke it directly. Available on STM32 builds with WOLFSSL_STM32_CCB on CCB silicon (STM32U3 or STM32C5).
int	wc_Stm32_Ccb_EccMakeBlob(int curveId, const byte * d, word32 dLen, byte * iv, byte * tag, byte * wrapped, word32 * wrappedSz, byte * pubX, byte * pubY) This function creates an STM32 CCB ECDSA-signature blob from a clear private scalar on-device. The scalar is wrapped under the silicon DHUK; the returned blob (iv[16] + tag[16] + wrapped scalar) and the derived public key (pubX[32] / pubY[32]) can be persisted and later reloaded with wc_ecc_import_wrapped_private_ex. The hardware self-verifies the blob before returning. Currently P-256 (ECC_SECP256R1). Available on STM32 builds with WOLFSSL_STM32_CCB on CCB silicon (STM32U3 or STM32C5).
int	wc_Stm32_Ccb_EccSign(int curveId, const byte * iv, const byte * tag, const byte * wrapped, word32 wrappedSz, const byte * hash, word32 hashSz, byte * r, byte * s) This function signs a hash with an STM32 CCB ECDSA blob. The private scalar is unwrapped inside the hardware (SAES->PKA over the CCB local bus) and never enters software or crosses the system bus. The (r, s) signature is written to the caller's 32-byte buffers. Currently P-256 (ECC_SECP256R1). Available on STM32 builds with WOLFSSL_STM32_CCB on CCB silicon (STM32U3 or STM32C5). Most callers reach this transparently via wc_ecc_sign_hash on a WC_DHUK_DEVID key rather than calling it directly.

Functions Documentation

function wc_Stm32_DhukRegister

int wc_Stm32_DhukRegister(
    int devId
)

This function registers the STM32 DHUK (Device Hardware Unique Key) crypto-callback device. After registering at WC_DHUK_DEVID, bind an object to the device by setting its devId at init (wc_AesInit / wc_ecc_init_ex) and supply the per-key 256-bit seed as the key (wc_AesGcmSetKey) or via wc_ecc_import_wrapped_private; normal wolfCrypt AES / GMAC / ECDSA calls then run transparently with the working key derived inside the SAES. Available on STM32 builds with WOLFSSL_DHUK, WOLF_CRYPTO_CB, and a DHUK-capable SAES (WC_STM32_HAS_DHUK); on the CubeMX path it is also provided for CCB ECDSA.

Parameters:

• devId the crypto-callback device id to register (use WC_DHUK_DEVID).

See:

• wc_Stm32_DhukUnRegister
• wc_ecc_import_wrapped_private

Return:

• 0 Returned on success.
• <0 A negative error code is returned if device registration fails.

Example

Aes aes;
wc_Stm32_DhukRegister(WC_DHUK_DEVID);
wc_AesInit(&aes, NULL, WC_DHUK_DEVID);
wc_AesGcmSetKey(&aes, seed, 32);
wc_AesGcmEncrypt(&aes, NULL, NULL, 0, iv, ivSz, tag, tagSz, aad, aadSz);
wc_AesFree(&aes);
wc_Stm32_DhukUnRegister(WC_DHUK_DEVID);

function wc_Stm32_DhukUnRegister

void wc_Stm32_DhukUnRegister(
    int devId
)

This function unregisters the STM32 DHUK crypto-callback device that was registered with wc_Stm32_DhukRegister. Call it once transparent DHUK / CCB operations are complete.

Parameters:

• devId the crypto-callback device id to unregister (WC_DHUK_DEVID).

See: wc_Stm32_DhukRegister

Return: none No return value.

Example

wc_Stm32_DhukUnRegister(WC_DHUK_DEVID);

function wc_Stm32_Aes_Wrap

int wc_Stm32_Aes_Wrap(
    struct Aes * aes,
    const byte * in,
    word32 inSz,
    byte * out,
    word32 * outSz,
    const byte * iv,
    int ivSz
)

This function performs a chip-bound DHUK AES key-wrap on the SAES (KEYSEL=HW, deterministic output) for provisioning wrapped key material. It is the inverse of the SAES wrapped-key load: the blob unwraps back to the key it wrapped, and matches ST's HAL_CRYPEx_WrapKey() output on the same die. The wrap-key source is selected by aes->devId (WOLFSSL_DHUK_DEVID for the hardware DHUK, otherwise a software key in aes->key; WOLFSSL_SAES_DEVID is a marker for that second case, not a device to register). An optional iv selects CBC instead of ECB. Produces WC_STM32_WRAP_ORDER_RAW on both build paths. Available on STM32 builds with WOLFSSL_DHUK and a DHUK-capable SAES.

Parameters:

• aes pointer to an initialized Aes; aes->devId selects the wrap key.
• in pointer to the input key bytes to wrap.
• inSz length of in in bytes.
• out pointer to the output buffer for the wrapped key.
• outSz on input the size of out; on output the bytes written.
• iv optional 16-byte iv; NULL selects ECB, non-NULL selects CBC.
• ivSz length of iv in bytes when iv is non-NULL; must be 16.

See:

• wc_Stm32_Aes_Wrap_ex
• wc_Stm32_DhukRegister

Return:

• 0 Returned on success.
• BAD_FUNC_ARG Returned if a required pointer is NULL, if inSz is not a supported block size, if the iv is non-NULL with ivSz != 16, or (software-key path) if the wrapping key length is not 16 or 32.
• <0 A negative error code may be returned on a hardware error.

function wc_Stm32_Aes_Wrap_ex

int wc_Stm32_Aes_Wrap_ex(
    struct Aes * aes,
    const byte * in,
    word32 inSz,
    byte * out,
    word32 * outSz,
    const byte * iv,
    int ivSz,
    int rawOrder
)

This function is wc_Stm32_Aes_Wrap() with the blob word order given explicitly. Available on STM32 builds with WOLFSSL_DHUK and a DHUK-capable SAES.

Parameters:

• aes pointer to an initialized Aes; aes->devId selects the wrap key.
• in pointer to the input key bytes to wrap.
• inSz length of in in bytes.
• out pointer to the output buffer for the wrapped key.
• outSz on input the size of out; on output the bytes written.
• iv optional 16-byte iv; NULL selects ECB, non-NULL selects CBC.
• ivSz length of iv in bytes when iv is non-NULL; must be 16.
• rawOrder WC_STM32_WRAP_ORDER_RAW (1) for the shared, round-tripping blob format, or WC_STM32_WRAP_ORDER_LEGACY (0) for the byte-reversed wolfSSL 5.9.0 - 5.9.2 CubeMX format. Define WC_STM32_WRAP_DEFAULT_RAW_ORDER before including the header to change what plain wc_Stm32_Aes_Wrap() passes here.

See:

• wc_Stm32_Aes_Wrap
• wc_Stm32_Aes_DhukOp_ex
• wc_Stm32_DhukRegister

Return:

• 0 Returned on success.
• BAD_FUNC_ARG Returned if a required pointer is NULL, if inSz is not a supported block size, if the iv is non-NULL with ivSz != 16, or (software-key path) if the wrapping key length is not 16 or 32.
• <0 A negative error code may be returned on a hardware error.

WC_STM32_WRAP_ORDER_RAW is the default on both build paths and is the only order that round-trips: it is what wc_Stm32_Aes_DhukOp_ex() and the DHUK crypto-callback derive path consume, so a blob wrapped on one build is usable on the other. Pass WC_STM32_WRAP_ORDER_LEGACY only to regenerate blobs provisioned by the CubeMX HAL_CRYPEx_WrapKey implementation shipped in wolfSSL 5.9.0 - 5.9.2, which byte-reversed its input and output; such a blob does not unwrap back to its key.

function wc_Stm32_CcbInit

int wc_Stm32_CcbInit(
    void 
)

This function brings up the STM32 CCB (Coupling and Chaining Bridge) peripheral and reports whether it is usable: it enables the CCB / PKA / SAES / RNG clocks, pulse-resets the engines, waits for BUSY to clear, and checks for an operation error. Bare-metal only (WOLFSSL_STM32_BARE). The transparent CCB sign path calls this internally, so most callers do not invoke it directly. Available on STM32 builds with WOLFSSL_STM32_CCB on CCB silicon (STM32U3 or STM32C5).

Parameters:

• none This function takes no parameters.

See:

• wc_Stm32_Ccb_EccMakeBlob
• wc_Stm32_Ccb_EccSign

Return:

• 0 Returned when the CCB is up and usable.
• WC_TIMEOUT_E Returned if BUSY does not clear within the timeout.
• <0 A negative error code is returned if the CCB reports an error.

function wc_Stm32_Ccb_EccMakeBlob

int wc_Stm32_Ccb_EccMakeBlob(
    int curveId,
    const byte * d,
    word32 dLen,
    byte * iv,
    byte * tag,
    byte * wrapped,
    word32 * wrappedSz,
    byte * pubX,
    byte * pubY
)

This function creates an STM32 CCB ECDSA-signature blob from a clear private scalar on-device. The scalar is wrapped under the silicon DHUK; the returned blob (iv[16] + tag[16] + wrapped scalar) and the derived public key (pubX[32] / pubY[32]) can be persisted and later reloaded with wc_ecc_import_wrapped_private_ex. The hardware self-verifies the blob before returning. Currently P-256 (ECC_SECP256R1). Available on STM32 builds with WOLFSSL_STM32_CCB on CCB silicon (STM32U3 or STM32C5).

Parameters:

• curveId the ECC curve id; currently ECC_SECP256R1.
• d pointer to the clear private scalar to wrap.
• dLen length of d in bytes.
• iv output buffer for the 16-byte blob iv.
• tag output buffer for the 16-byte blob authentication tag.
• wrapped output buffer for the wrapped scalar.
• wrappedSz on output the length of the wrapped scalar in bytes.
• pubX output buffer for the 32-byte public key X coordinate.
• pubY output buffer for the 32-byte public key Y coordinate.

See:

• wc_Stm32_Ccb_EccSign
• wc_ecc_import_wrapped_private_ex

Return:

• 0 Returned on success.
• NOT_COMPILED_IN Returned if curveId is an unsupported curve.
• BAD_FUNC_ARG Returned if a required pointer is NULL or dLen is wrong.
• WC_TIMEOUT_E Returned if a hardware step times out.

function wc_Stm32_Ccb_EccSign

int wc_Stm32_Ccb_EccSign(
    int curveId,
    const byte * iv,
    const byte * tag,
    const byte * wrapped,
    word32 wrappedSz,
    const byte * hash,
    word32 hashSz,
    byte * r,
    byte * s
)

This function signs a hash with an STM32 CCB ECDSA blob. The private scalar is unwrapped inside the hardware (SAES->PKA over the CCB local bus) and never enters software or crosses the system bus. The (r, s) signature is written to the caller's 32-byte buffers. Currently P-256 (ECC_SECP256R1). Available on STM32 builds with WOLFSSL_STM32_CCB on CCB silicon (STM32U3 or STM32C5). Most callers reach this transparently via wc_ecc_sign_hash on a WC_DHUK_DEVID key rather than calling it directly.

Parameters:

• curveId the ECC curve id; currently ECC_SECP256R1.
• iv pointer to the 16-byte blob iv.
• tag pointer to the 16-byte blob authentication tag.
• wrapped pointer to the wrapped scalar from wc_Stm32_Ccb_EccMakeBlob.
• wrappedSz length of wrapped in bytes.
• hash pointer to the hash to sign.
• hashSz length of hash in bytes.
• r output buffer for the 32-byte signature r value.
• s output buffer for the 32-byte signature s value.

See:

• wc_Stm32_Ccb_EccMakeBlob
• wc_ecc_sign_hash

Return:

• 0 Returned on success.
• NOT_COMPILED_IN Returned if curveId is an unsupported curve.
• BAD_FUNC_ARG Returned if a required pointer is NULL.
• WC_TIMEOUT_E Returned if a hardware step times out.

Source code

int wc_Stm32_DhukRegister(int devId);

void wc_Stm32_DhukUnRegister(int devId);

int wc_Stm32_Aes_Wrap(struct Aes* aes, const byte* in, word32 inSz, byte* out,
    word32* outSz, const byte* iv, int ivSz);

int wc_Stm32_Aes_Wrap_ex(struct Aes* aes, const byte* in, word32 inSz,
    byte* out, word32* outSz, const byte* iv, int ivSz, int rawOrder);

int wc_Stm32_CcbInit(void);

int wc_Stm32_Ccb_EccMakeBlob(int curveId, const byte* d, word32 dLen,
    byte* iv, byte* tag, byte* wrapped, word32* wrappedSz,
    byte* pubX, byte* pubY);

int wc_Stm32_Ccb_EccSign(int curveId, const byte* iv, const byte* tag,
    const byte* wrapped, word32 wrappedSz, const byte* hash, word32 hashSz,
    byte* r, byte* s);

---

Updated on 2026-11-13 at 01:20:07 +0000