cryptocb: add AES CryptoCB key import support and tests

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>

Author: sameehj

.github/workflows/os-check.yml

@@ -70,6 +70,7 @@ jobs:
           '--enable-all --enable-certgencache',
           '--enable-sessionexport --enable-dtls --enable-dtls13',
           '--enable-sessionexport',
+          '--enable-cryptocb --enable-aesgcm CPPFLAGS="-DWOLF_CRYPTO_CB_AES_SETKEY -DWOLF_CRYPTO_CB_FREE"',
         ]
     name: make check
     if: github.repository_owner == 'wolfssl'

README.md

@@ -57,6 +57,27 @@ suites are available. You can remove this error by defining
 `WOLFSSL_ALLOW_NO_SUITES` in the event that you desire that, i.e., you're
 not using TLS cipher suites.
 
+### AES CryptoCB Key Import Support
+
+wolfSSL supports hardware-accelerated AES operations via CryptoCB.
+
+**TLS Builds (Default):**
+- Provides hardware **acceleration** with automatic software fallback
+- Key material IS copied to wolfSSL memory for fallback capability
+- Safe for production TLS servers
+- HSMs/SEs accelerate crypto but don't provide key isolation
+
+**Crypto-Only Builds (--disable-tls):**
+- Provides true hardware **offload**
+- Key material NOT copied to wolfSSL memory
+- Requires robust error handling in callbacks
+- Suitable for embedded crypto-only applications
+
+Enable with: `CPPFLAGS="-DWOLF_CRYPTO_CB_AES_SETKEY"`
+
+This feature is commonly used for TLS 1.3 traffic key protection on
+embedded platforms with hardware security modules.
+
 ### Note 2
 wolfSSL takes a different approach to certificate verification than OpenSSL
 does. The default policy for the client is to verify the server, this means

doc/dox_comments/header_files/cryptocb.h

@@ -180,3 +180,78 @@ void wc_CryptoCb_SetDeviceFindCb(CryptoDevCallbackFind cb);
     \sa wc_CryptoCb_RegisterDevice
 */
 void wc_CryptoCb_InfoString(wc_CryptoInfo* info);
+
+/*!
+    \ingroup CryptoCb
+
+    \brief Import an AES key into a CryptoCB device for hardware offload.
+
+    This function allows AES keys to be handled by an external device
+    (e.g. Secure Element or HSM). 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 routes AES-GCM operations
+    through the CryptoCB interface.
+
+    **TLS Builds (Default):**
+    - Key bytes ARE stored in wolfCrypt memory for fallback
+    - GCM tables ARE generated for software fallback
+    - Provides hardware acceleration with automatic fallback
+
+    **Crypto-Only Builds (--disable-tls):**
+    - Key bytes NOT stored (true key isolation)
+    - GCM tables skipped when WC_CRYPTOCB_AES_GCM is set
+    - True hardware offload
+
+    The callback declares its capabilities by setting flags in the
+    capabilities parameter. If WC_CRYPTOCB_AES_GCM is set, the callback
+    supports AES-GCM acceleration. In TLS builds, tables are still generated
+    for fallback. In crypto-only builds, tables are skipped for true offload.
+    If not set, wolfCrypt generates tables for software fallback.
+
+    \param aes          AES context
+    \param key          Pointer to raw AES key material
+    \param keySz        Size of key in bytes
+    \param capabilities Output parameter receiving capability flags set by
+                        callback. May be NULL if capabilities are not needed.
+                        Callback sets WC_CRYPTOCB_AES_GCM to indicate full
+                        GCM offload support.
+
+    \return 0 on success
+    \return CRYPTOCB_UNAVAILABLE if device does not support this operation
+    \return BAD_FUNC_ARG on invalid parameters
+
+    _Example_
+    \code
+    #include <wolfssl/wolfcrypt/cryptocb.h>
+    #include <wolfssl/wolfcrypt/aes.h>
+
+    Aes aes;
+    byte key[32] = { /* 256-bit key */ };
+    int devId = 1;
+    int capabilities = 0;
+
+    /* Register your CryptoCB callback first */
+    wc_CryptoCb_RegisterDevice(devId, myCryptoCallback, NULL);
+
+    wc_AesInit(&aes, NULL, devId);
+    /* wc_AesGcmSetKey internally calls wc_CryptoCb_AesSetKey */
+    if (wc_CryptoCb_AesSetKey(&aes, key, sizeof(key), &capabilities) == 0) {
+        /* Key successfully imported to device via callback */
+        /* aes.devCtx now contains device handle */
+        /* Check if GCM acceleration is supported */
+        if (capabilities & WC_CRYPTOCB_AES_GCM) {
+            /* GCM acceleration active */
+            /* Note: In TLS builds, tables still generated for fallback */
+            /* In crypto-only builds, tables skipped (true offload) */
+        }
+    }
+    \endcode
+
+    \sa wc_CryptoCb_RegisterDevice
+    \sa wc_AesInit
+    \sa WC_CRYPTOCB_AES_GCM
+*/
+int wc_CryptoCb_AesSetKey(Aes* aes, const byte* key, word32 keySz,
+                          int* capabilities);

doc/dox_comments/header_files/doxygen_pages.h

@@ -74,4 +74,30 @@
     - \ref SAKKE_RSK
     - \ref SAKKE_Operations
 */
+/*!
+    \page AES_CryptoCB_KeyImport AES CryptoCB Key Import
+
+    When enabled via WOLF_CRYPTO_CB_AES_SETKEY, wolfSSL allows AES keys
+    to be imported into external cryptographic devices using the Crypto
+    Callback interface.
+
+    **TLS Builds (Default):**
+    - Keys ARE retained in memory for fallback.
+    - Provides acceleration, not key isolation.
+
+    **Crypto-Only Builds (--disable-tls):**
+    - Keys NOT retained in memory.
+    - Provides true offload with key isolation.
+
+    This mode is compatible with Secure Elements and hardware-backed
+    key storage and is intended for protecting TLS traffic keys.
+
+    Software fallback to the standard AES implementation occurs
+    automatically during key setup if the device does not handle the
+    SetKey operation. However, once a key is imported (devCtx is set),
+    AES-GCM operations are expected to be handled by the device.
+
+    \sa wc_CryptoCb_AesSetKey
+    \sa \ref Crypto Callbacks
+*/