STM32 Hardware Crypto Port

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:

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:

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:

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:

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:

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.

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