cryptocb: add AES CryptoCB key import support and tests #9658

sameehj · 2026-01-14T14:34:59Z

Add CryptoCB-based AES key import support to enable Secure Element
offload without exposing raw AES key material to wolfCrypt.

This change introduces a new optional CryptoCB hook
(WOLF_CRYPTO_CB_AES_SETKEY) that allows AES keys to be imported into
external devices (e.g. Secure Elements or HSMs) and referenced via an
opaque handle stored in aes->devCtx. When this mode is active, wolfCrypt
stores only key metadata and routes AES-GCM operations through CryptoCB,
bypassing software key storage and GCM table generation.

Key points:
- Add wc_CryptoCb_AesSetKey() callback for AES key import
- Update AES SetKey paths to support key import mode with graceful
  fallback to software when CryptoCB is unavailable
- Skip GCM H/M table generation when AES-GCM is handled by the device
- Preserve existing software AES behavior when devId is INVALID_DEVID

Testing:
- Add unit test for CryptoCB AES SetKey behavior
- Add end-to-end AES-GCM offload unit test that verifies:
  * SetKey, Encrypt, Decrypt, and Free are routed via CryptoCB
  * Correct ciphertext/auth tag generation
  * Correct plaintext recovery after decrypt
  * Proper lifecycle handling of device context handles
- Tests use a mock Secure Element that internally performs software AES
  to validate routing without requiring hardware

devin-ai-integration · 2026-01-14T14:35:49Z

🛟 Devin Lifeguard found 2 likely issues in this PR

check-all-return-codes snippet snippet: Capture the return value of wc_CryptoCb_UnRegisterDevice() in each test (e.g., ret = wc_CryptoCb_UnRegisterDevice(TEST_CRYPTOCB_AES_DEVID); ExpectIntEQ(ret, 0);) to ensure any error is detected.
limit-stack-usage snippet snippet: Use the WOLFSSL_SMALL_STACK pattern in the two newly added test functions: dynamically allocate the large local objects (Aes aes, the plaintext/ciphertext/authTag buffers, etc.) with XMALLOC/XFREE (guarded by #ifdef WOLFSSL_SMALL_STACK) instead of placing them on the stack.

@sameehj
please take a look at the above issues which Devin flagged. Devin will not fix these issues automatically.

sameehj · 2026-01-14T18:13:13Z

retest this please

julek-wolfssl

I see "proxy-key" appearing multiple times in the PR. What does it mean?
The ORIGINAL: comments should be cleaned up.

julek-wolfssl · 2026-01-15T16:30:13Z

wolfssl/wolfcrypt/cryptocb.h

-WOLFSSL_API void wc_CryptoCb_UnRegisterDevice(int devId);
+WOLFSSL_API int wc_CryptoCb_UnRegisterDevice(int devId);


Mainly to satisfy Devin's comment on the PR, but maybe we shouldn't break the API to do so.
Thank you

julek-wolfssl · 2026-01-15T16:31:53Z

wolfssl/wolfcrypt/cryptocb.h

+/**
+ * \brief Import an AES key into a CryptoCB device (proxy-key mode).
+ *
+ * This function allows AES keys to be handled by an external device
+ * (e.g. Secure Element or HSM) without exposing raw key material to
+ * wolfCrypt. When supported, the device callback stores the key internally
+ * and sets an opaque handle in aes->devCtx.
+ *
+ * When CryptoCB AES SetKey support is enabled
+ * (WOLF_CRYPTO_CB_AES_SETKEY), wolfCrypt will route AES-GCM operations
+ * through the CryptoCB interface and avoid storing key bytes or
+ * generating GCM tables in software.
+ *
+ * \param aes     AES context
+ * \param key     Pointer to raw AES key material
+ * \param keySz   Size of key in bytes
+ *
+ * \return 0 on success
+ * \return CRYPTOCB_UNAVAILABLE if device does not support this operation
+ * \return BAD_FUNC_ARG on invalid parameters
+ */


Wrong place for docs.

julek-wolfssl · 2026-01-15T16:35:04Z

tests/api/test_aes.c

+static int g_ccAesSetKeyCalled = 0;
+static int g_ccAesFreeCalled = 0;


What is this g_ prefix?

julek-wolfssl · 2026-01-15T16:41:59Z

wolfcrypt/src/aes.c

+        #else
+            /* ORIGINAL: Copy key to devKey for existing CryptoCB users */
+            if (keylen > sizeof(aes->devKey)) {
+                return BAD_FUNC_ARG;
+            }
+            XMEMCPY(aes->devKey, userKey, keylen);
+        #endif


Why move this up here instead of allowing aes->devId != INVALID_DEVID section to handle it?

julek-wolfssl · 2026-01-15T16:45:18Z

wolfcrypt/src/aes.c

+            /* ORIGINAL: Copy to devKey */
+            if (len > sizeof(aes->devKey)) {
+                return BAD_FUNC_ARG;
+            }


len is already checked on function entry. Why this check here?

julek-wolfssl · 2026-01-15T16:46:09Z

wolfcrypt/src/aes.c

-        ret = wc_CryptoCb_Free(aes->devId, WC_ALGO_TYPE_CIPHER,
-                         WC_CIPHER_AES, (void*)aes);
-        /* If they want the standard free, they can call it themselves */
-        /* via their callback setting devId to INVALID_DEVID */
-        /* otherwise assume the callback handled it */


Why is this comment being removed?

julek-wolfssl · 2026-01-15T16:53:49Z

Is it possible to setup a gh action that tests this with wolfHSM? At the very least this new config should be added to os-check.yml.

Add CryptoCB-based AES key import support to enable Secure Element offload without exposing raw AES key material to wolfCrypt. This change introduces a new optional CryptoCB hook (WOLF_CRYPTO_CB_AES_SETKEY) that allows AES keys to be imported into external devices (e.g. Secure Elements or HSMs) and referenced via an opaque handle stored in aes->devCtx. When this mode is active, wolfCrypt stores only key metadata and routes AES-GCM operations through CryptoCB, bypassing software key storage and GCM table generation. Key points: - Add wc_CryptoCb_AesSetKey() callback for AES key import - Update AES SetKey paths to support key import mode with graceful fallback to software when CryptoCB is unavailable - Skip GCM H/M table generation when AES-GCM is handled by the device - Preserve existing software AES behavior when devId is INVALID_DEVID Testing: - Add unit test for CryptoCB AES SetKey behavior - Add end-to-end AES-GCM offload unit test that verifies: * SetKey, Encrypt, Decrypt, and Free are routed via CryptoCB * Correct ciphertext/auth tag generation * Correct plaintext recovery after decrypt * Proper lifecycle handling of device context handles - Tests use a mock Secure Element that internally performs software AES to validate routing without requiring hardware Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>

sameehj · 2026-01-16T17:07:57Z

I see "proxy-key" appearing multiple times in the PR. What does it mean? The ORIGINAL: comments should be cleaned up.

Dropped proxy-key terminology
and dropped 'ORIGINAL" comments

sameehj requested a review from douzzer January 14, 2026 14:35

sameehj force-pushed the aes-offload branch 2 times, most recently from b3bcd1c to fd6d469 Compare January 15, 2026 16:17

julek-wolfssl requested changes Jan 15, 2026

View reviewed changes

sameehj force-pushed the aes-offload branch 3 times, most recently from 519cd36 to be96866 Compare January 16, 2026 16:26

sameehj force-pushed the aes-offload branch from be96866 to ea7e61d Compare January 16, 2026 17:05

sameehj changed the title ~~cryptocb: add AES proxy-key support and end-to-end CryptoCB AES-GCM t…~~ cryptocb: add AES CryptoCB key import support and tests Jan 16, 2026

		WOLFSSL_API void wc_CryptoCb_UnRegisterDevice(int devId);
		WOLFSSL_API int wc_CryptoCb_UnRegisterDevice(int devId);

		static int g_ccAesSetKeyCalled = 0;
		static int g_ccAesFreeCalled = 0;

cryptocb: add AES CryptoCB key import support and tests #9658

Are you sure you want to change the base?

cryptocb: add AES CryptoCB key import support and tests #9658

Uh oh!

Conversation

sameehj commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devin-ai-integration bot commented Jan 14, 2026

Uh oh!

sameehj commented Jan 14, 2026

Uh oh!

julek-wolfssl left a comment

Choose a reason for hiding this comment

Uh oh!

julek-wolfssl Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

sameehj Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

julek-wolfssl Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

julek-wolfssl Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

julek-wolfssl Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

julek-wolfssl Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

julek-wolfssl Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

julek-wolfssl commented Jan 15, 2026

Uh oh!

sameehj commented Jan 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sameehj commented Jan 14, 2026 •

edited

Loading