Add SHE (Secure Hardware Extension) support to wolfCrypt

[night1rider]

Implements software-only SHE CMD_LOAD_KEY message generation (M1/M2/M3)
and verification message computation (M4/M5) with optional crypto
callback support for hardware offload.

New files:

• wolfssl/wolfcrypt/she.h: API declarations, constants, wc_SHE context
• wolfcrypt/src/she.c: Miyaguchi-Preneel KDF, message generation,
  verification computation, and crypto callback integration
• tests/api/test_she.c/h: API tests with 97% line / 100% function coverage

API:

• wc_SHE_Init/Free, Init_Id, Init_Label (lifecycle)
• wc_SHE_GenerateM1M2M3 (generate M1/M2/M3 to caller buffers, callback optional)
• wc_SHE_GenerateM4M5 (generate M4/M5 to caller buffers, independent of
  M1/M2/M3, callback optional)
• wc_SHE_ImportM1M2M3 (import external M1/M2/M3 into context)
• wc_SHE_GetUID (callback required, fetches UID from hardware)
• wc_SHE_GetCounter (callback required, reads monotonic counter from hardware)
• wc_SHE_ExportKey (callback required, exports key slot as M1-M5 from hardware)
• wc_SHE_SetKdfConstants (callback optional, WOLFSSL_SHE_EXTENDED only)
• wc_SHE_SetM2Header (callback optional, WOLFSSL_SHE_EXTENDED only)
• wc_SHE_SetM4Header (callback optional, WOLFSSL_SHE_EXTENDED only)
• No key material stored in the context; all inputs passed at generation time

Crypto callback integration:

• WC_ALGO_TYPE_SHE added to wc_AlgoType enum
• Callback sub-types: WC_SHE_SET_UID, WC_SHE_GET_COUNTER,
  WC_SHE_GENERATE_M1M2M3, WC_SHE_GENERATE_M4M5, WC_SHE_EXPORT_KEY
• Per-operation structs in wc_CryptoInfo union with full parameter passthrough
• Dispatch functions in cryptocb.c
• Optional features: NO_WC_SHE_GETUID, NO_WC_SHE_GETCOUNTER,
  NO_WC_SHE_EXPORTKEY, NO_WC_SHE_IMPORT_M123

Build system:

• configure.ac: --enable-she=standard|extended
• CMakeLists.txt: WOLFSSL_SHE standard|extended|no
• src/include.am: she.c compilation
• .github/workflows/os-check.yml: CI configs for standard, extended,
  and NO_* disable flag combinations

Ported from wolfHSM wh_she_crypto.c.

[bigbrett]

Absolutely fantastic work @night1rider. A few issues to address but overall looks great.

[wolfSSL-Fenrir-bot]

Fenrir Automated Review — PR #10009

Scan targets checked: wolfcrypt-bugs, wolfcrypt-src
Findings: 1

Low (1)

Missing NULL check on id parameter in wc_SHE_Init_Id

File: wolfcrypt/src/she.c:155-157
Function: wc_SHE_Init_Id
Category: NULL pointer dereference

The function wc_SHE_Init_Id validates she == NULL and checks that len is within bounds (0 to WC_SHE_MAX_ID_LEN), but does not check whether id is NULL before calling XMEMCPY(she->id, id, (size_t)len). If a caller passes id = NULL with len > 0, this results in a NULL pointer dereference. By contrast, the sibling function wc_SHE_Init_Label correctly validates label == NULL before use. The impact is limited because this requires caller misuse and would crash immediately (no memory corruption beyond the dereference), but it is inconsistent with the defensive validation pattern used throughout the rest of the SHE API.

if (len < 0 || len > WC_SHE_MAX_ID_LEN) {
        return BUFFER_E;
    }

    XMEMCPY(she->id, id, (size_t)len);

Recommendation: Add a NULL check for id when len > 0, consistent with the pattern in wc_SHE_Init_Label: if (id == NULL && len > 0) { return BAD_FUNC_ARG; } or simply if (id == NULL) { return BAD_FUNC_ARG; } before the length check.

---

This review was generated automatically by Fenrir. Findings are non-blocking.

[night1rider]

Rebased off current master

[night1rider]

Added wc_SHE_LoadKey, wc_SHE_LoadKey_Id, wc_SHE_LoadKey_Label and their verify counterparts.

These wrap Init, ImportM1M2M3, GenerateM4M5, and Free into a single call for hardware crypto callback usage. Verify variants compare returned M4/M5 against expected values using ConstantCompare.

All functions require a valid devId and can be compiled out with NO_WC_SHE_LOADKEY.

[night1rider]

Jenkins retest this please

[night1rider]

Rebased to fix merge conflict

[dgarske]

skoll review

[night1rider]

Had to rebase and force push due to merge conflict with .github/workflows/os-check.yml.

[night1rider]

Jenkins retest this please

[night1rider]

Rebased and fixed merge conflict of wolfssl/wolfcrypt/types.h caused by merging #9851

[github-actions]

MemBrowse Memory Report

gcc-arm-cortex-m4

• FLASH: .text +64 B (+0.0%, 195,275 B / 262,144 B, total: 74% used)

gcc-arm-cortex-m4-baremetal

• FLASH: .text +64 B (+0.1%, 63,539 B / 262,144 B, total: 24% used)

gcc-arm-cortex-m4-min-ecc

• FLASH: .text +64 B (+0.1%, 59,125 B / 262,144 B, total: 23% used)

gcc-arm-cortex-m4-tls12

• FLASH: .text +64 B (+0.1%, 119,418 B / 262,144 B, total: 46% used)

[dgarske]

Could this be in wc_she.c?

[night1rider]

The existing convention in wolfSSL is that all wc_CryptoCb_* wrapper functions live in cryptocb.c. wc_CryptoCb_AesCbcEncrypt, wc_CryptoCb_Rsa, wc_CryptoCb_EccSign, wc_CryptoCb_Sha256Hash, wc_CryptoCb_Cmac, etc. live in cryptocb.c, not in aes.c / rsa.c / ecc.c / sha256.c / cmac.c.

I had SHE wrappers follow that same pattern so the callback dispatching logic stays in one file and wc_she.c does not have to pull in cryptocb.h / the dispatch plumbing.

I could look at moving them to wc_she.c if that is preferred, but it would be the first deviation from the current pattern.

[dgarske]

Do we really have to customize cryptocb to add this SHE support? Are the existing ones not enough + the keyCtx that each has?

[night1rider]

The she union exists to carry the arguments of the public SHE API across the callback. Each SHE API function has a distinct argument list that needs to reach the callback unchanged.

wc_SHE_GenerateM1M2M3 takes {wc_SHE*, uid, uidSz, authKeyId, authKey, authKeySz, targetKeyId, newKey, newKeySz, counter, flags, m1, m1Sz, m2, m2Sz, m3, m3Sz}, and the other SHE calls each have their own shape.

The she sub structs were added to mirror each SHE API call's argument list 1:1 so the callback receives exactly what the caller passed in without any repacking.

I can restructure if you have a specific layout in mind, or suggestion for how to pass the API parameters.

[dgarske]

Where is the README.md for SHE? What hardware platform does this run on? How does someone test it?

[night1rider]

I just put the PR for the manual chapter for SHE in wolfSSL/documentation#263, and a follow up commit that adds the doxygen for the public SHE API at 85423cd. I can add that doxygen commit into this PR if you would like it here instead of as a separate change.

This only implements the software M1 through M5 generation path (wc_SHE_Init, wc_SHE_GenerateM1M2M3, wc_SHE_GenerateM4M5, wc_SHE_VerifyM4M5, wc_SHE_Free).

To load a SHE key on a device or use ImportM1M2M3 / GetUID / GetCounter / LoadKey / LoadKey_Verify / ExportKey, pair this PR with a crypto callback (our NXP S32K3 HSE port is an example) or use wolfHSM instead. LoadKey returns BAD_FUNC_ARG on INVALID_DEVID. GetUID / GetCounter have a WC_SHE_SW_DEFAULT stub, off by default and labeled example only (dummy UID, incrementing static counter).

Nothing special is required to test. Any build with WOLFSSL_CMAC and WOLFSSL_SHE enabled runs the software path via she_test() in ./wolfcrypt/test/testwolfcrypt. Test vectors come from https://github.com/wolfSSL/wolfHSM/blob/main/test/wh_test_she.c so results line up with wolfHSM.

Two common uses: (1) provisioning / key manager server tooling, where a cloud backend generates M1-M5 to push to devices and a source side callback handles counter tracking or protocol header packing; (2) vendor extended SHE specs with custom KDF constants or header layouts.