cryptocb: add AES proxy-key support and end-to-end CryptoCB AES-GCM t… #9658

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

…ests

Add CryptoCB-based AES proxy-key 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 proxy-key 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 proxy-key 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 proxy-key handles
Tests use a mock Secure Element that internally performs software AES to validate routing without requiring hardware

This enables dual-mode operation:

Software AES for normal builds and testing
Secure Element–backed AES for TLS and crypto offload use cases

Description

Please describe the scope of the fix or feature addition.

Fixes zd#

Testing

How did you test?

Checklist

added tests
updated/added doxygen
updated appropriate READMEs
Updated manual and documentation

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

…ests Add CryptoCB-based AES proxy-key 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 proxy-key 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 proxy-key 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 proxy-key handles - Tests use a mock Secure Element that internally performs software AES to validate routing without requiring hardware This enables dual-mode operation: - Software AES for normal builds and testing - Secure Element–backed AES for TLS and crypto offload use cases Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>

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);


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.

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

sameehj force-pushed the aes-offload branch from 828a7b3 to b3bcd1c Compare January 15, 2026 10:31

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

julek-wolfssl requested changes Jan 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

cryptocb: add AES proxy-key support and end-to-end CryptoCB AES-GCM t… #9658

cryptocb: add AES proxy-key support and end-to-end CryptoCB AES-GCM t… #9658

sameehj commented Jan 14, 2026

Uh oh!

devin-ai-integration bot commented Jan 14, 2026

Uh oh!

sameehj commented Jan 14, 2026

Uh oh!

julek-wolfssl left a comment

Uh oh!

julek-wolfssl Jan 15, 2026

Uh oh!

julek-wolfssl Jan 15, 2026

Uh oh!

julek-wolfssl Jan 15, 2026

Uh oh!

julek-wolfssl Jan 15, 2026

Uh oh!

julek-wolfssl Jan 15, 2026

Uh oh!

julek-wolfssl Jan 15, 2026

Uh oh!

julek-wolfssl commented Jan 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		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 proxy-key support and end-to-end CryptoCB AES-GCM t… #9658

Are you sure you want to change the base?

cryptocb: add AES proxy-key support and end-to-end CryptoCB AES-GCM t… #9658

Conversation

sameehj commented Jan 14, 2026

Description

Testing

Checklist

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants