Add SHE (Secure Hardware Extension) support to wolfCrypt by night1rider · Pull Request #10009 · wolfSSL/wolfssl

night1rider · 2026-03-18T19:05:46Z

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.

bigbrett · 2026-03-24T02:21:23Z

.wolfssl_known_macro_extras

 WOLFSSL_SECURE_RENEGOTIATION_ON_BY_DEFAULT
 WOLFSSL_SERVER_EXAMPLE
 WOLFSSL_SETTINGS_FILE
+WOLFSSL_SH224


This was a copy paste mistake I introduced, removed.

bigbrett · 2026-03-24T02:23:07Z

wolfssl/wolfcrypt/wc_she.h

I'm wondering if she.{c,h} is bound to cause some annoying conflicts in automotive codebases and vendor libs. Perhaps we could namespace it to wc_she.{c,h} just to get ahead of that?

This makes sense since we already have files following this convention (wc_encrypt, wc_lms, wc_mlkem, wc_port, etc.) there's no issue doing it now. Names should be updated now

bigbrett · 2026-03-24T02:33:59Z

wolfssl/wolfcrypt/she.h

+/* Generate M1/M2/M3 for the SHE key update protocol and write to
+ * caller-provided buffers. Callback optional -- if a callback is
+ * registered it is tried first; if it returns CRYPTOCB_UNAVAILABLE
+ * the software path runs. This allows a secure element to generate
+ * M1/M2/M3 when it holds the auth key internally.


I think it is a little confusing to mention the "Callback optional" field here, since the dispatch to cryptoCb is internal and not exposed in this module. For example, we don't say "Callback optional" in our AES API.

Same comment for other functions in this file

I wanted to mention usefulness of the callbacks somewhere, especially for generating M1/M2/M3 or M4/M5 when they need to access a secure element/hardware. This can be covered in the source comments and docs instead of the public header. I removed the callback language from all five API comments in wc_she.h.

bigbrett · 2026-03-24T02:34:39Z

wolfssl/wolfcrypt/wc_she.h

make sure to update the out-of-tree doxygen with your lovely API comments too, so it renders in the website docs!

I will link a PR shortly with the doc update in the main body of the pr description

bigbrett · 2026-03-24T02:36:18Z

wolfssl/wolfcrypt/she.h

+ *   in    - input data (e.g. BaseKey || KDF_Constant, 32 bytes)
+ *   inSz  - length of input in bytes (zero-padded to block boundary)
+ *   out   - output buffer for 16-byte compressed result */
+WOLFSSL_TEST_VIS int wc_She_AesMp16(Aes* aes, const byte* in, word32 inSz,


All the other APIs use wc_SHE but this has wc_She. Unify for consistency

I overlooked this due to it being an internal function, updated the name.

bigbrett · 2026-03-24T02:41:30Z

wolfcrypt/src/she.c

+        return BAD_FUNC_ARG;
+    }
+
+    return wc_CryptoCb_SheSetUid(she, uid, uidSz, ctx);


shouldn't this be "get" UID based on calling function? Though the crypto callbacks do only have a set function. What is the intent here?

This was overlooked. Renamed wc_CryptoCb_SheSetUid to wc_CryptoCb_SheGetUid, WC_SHE_SET_UID to WC_SHE_GET_UID, and the union field setUid to getUid in cryptocb.h and cryptocb.c. The intent is to allow someone to use the same API after implementing the callback across different platforms. This is the same intent for GetCounter as well.

bigbrett · 2026-03-24T02:43:51Z

wolfcrypt/src/wc_she.c

+/* Returns CRYPTOCB_UNAVAILABLE if no callback.                              */
+/* -------------------------------------------------------------------------- */
+#if defined(WOLF_CRYPTO_CB) && !defined(NO_WC_SHE_GETCOUNTER)
+int wc_SHE_GetCounter(wc_SHE* she, word32* counter, const void* ctx)


Same comment here - I wonder if a default software impl with dumb global counter would be worthwhile just to enable testing? Could have a build macro enabling this to prevent inclusion in production builds maybe?

Addressed in my previous comment regarding the "default global "wolfCrypt" UID".

bigbrett · 2026-03-24T02:49:31Z

wolfcrypt/src/cryptocb.c

 #endif /* WOLFSSL_CMAC */

+#ifdef WOLFSSL_SHE
+int wc_CryptoCb_SheSetUid(wc_SHE* she, const byte* uid, word32 uidSz,


I'm confused, can you set the UID? Shouldn't this be "get" UID? Same comment is made in she.c.

Are we setting ID in local wolfCrypt struct or are we getting it from HW?

I just overlooked this, addressed. We are getting the UID from hardware and some hardware supports a challenge to get the UID to prove that the hardware is real, hence the void context parameter. This is just an API to get the UID to then pass to the generate API calls. There is no setting the UID in the structure. The struct is now very basic and holds only M1/M2/M3 if they are imported and the import function is on, plus devId for callbacks, KDF constants, etc.

bigbrett · 2026-03-24T02:53:43Z

wolfcrypt/src/wc_she.c

+        }
+        /* fall-through to software path */
+    }
+#endif


Need to reset ret=0 in fallback case for good measure

Updated, overlooked this.

bigbrett · 2026-03-24T02:56:09Z

wolfcrypt/src/wc_she.c

+        int ret = wc_CryptoCb_Free(she->devId, WC_ALGO_TYPE_SHE,
+                                   0, 0, she);
+        if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE)) {
+            return;


Ever a case where we want to ForceZero here?

We already have a ForceZero on the fall-through path. The person who implements their callback should be allowed to control how free works. If they want our software cleanup, they can clean up what they want and then return CRYPTOCB_UNAVAILABLE to continue to the ForceZero. If they handle everything themselves, they return success and we skip it and the callback implementer assumes the responsibility.

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.

…_she.{c,h}, fix naming consistency, auto-enable CMAC/AES dependencies, add WC_SHE_SW_DEFAULT opt-inAddress PR wolfSSL#10009 review comments from bigbrett and Fenrir

night1rider · 2026-03-24T19:19:21Z

Rebased off current master

night1rider self-assigned this Mar 18, 2026

night1rider force-pushed the SHE-update branch 3 times, most recently from 39d4163 to 54b673a Compare March 22, 2026 02:07

night1rider assigned bigbrett Mar 23, 2026

night1rider marked this pull request as ready for review March 23, 2026 15:38

bigbrett requested changes Mar 24, 2026

View reviewed changes

bigbrett removed their assignment Mar 24, 2026

bigbrett requested a review from wolfSSL-Fenrir-bot March 24, 2026 03:00

wolfSSL-Fenrir-bot reviewed Mar 24, 2026

View reviewed changes

night1rider added 6 commits March 24, 2026 13:18

Add SHE (Secure Hardware Extension) support to wolfCrypt

9906dcb

fix macro guarding in tests/api.c

9b748a2

SHE API: remove key storage from context, add direct output params

c5c8b01

Add more in depth comments in header file for she.h

563dcc3

Address comments from bigbrett and Fenrir bot. Rename she.{c,h} to wc…

6851571

…_she.{c,h}, fix naming consistency, auto-enable CMAC/AES dependencies, add WC_SHE_SW_DEFAULT opt-inAddress PR wolfSSL#10009 review comments from bigbrett and Fenrir

update she union for callback to be getUid not setUid

60368c8

night1rider force-pushed the SHE-update branch from dabe1c7 to 60368c8 Compare March 24, 2026 19:18

Conversation

night1rider commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bigbrett left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

night1rider Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wolfSSL-Fenrir-bot left a comment

Choose a reason for hiding this comment

Fenrir Automated Review — PR #10009

Low (1)

Missing NULL check on id parameter in wc_SHE_Init_Id

Uh oh!

night1rider commented Mar 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

night1rider commented Mar 18, 2026 •

edited

Loading

night1rider Mar 24, 2026 •

edited

Loading

Missing NULL check on `id` parameter in `wc_SHE_Init_Id`