Merge pull request #9658 from sameehj/aes-offload

   cryptocb: add AES CryptoCB key import support and tests

Author: douzzer

.github/workflows/os-check.yml

@@ -70,6 +70,9 @@ 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"',
+          '--disable-tls --enable-cryptocb --enable-aesgcm CPPFLAGS="-DWOLF_CRYPTO_CB_AES_SETKEY -DWOLF_CRYPTO_CB_FREE"',
+          '--enable-cryptocb --enable-aesgcm CPPFLAGS="-DWOLF_CRYPTO_CB_AES_SETKEY"',
           '--disable-examples CPPFLAGS=-DWOLFSSL_NO_MALLOC',
           'CPPFLAGS=-DNO_WOLFSSL_CLIENT',
           'CPPFLAGS=-DNO_WOLFSSL_SERVER',

README.md

@@ -57,6 +57,29 @@ 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.
+
+When `WOLF_CRYPTO_CB_AES_SETKEY` is defined, wolfSSL invokes a CryptoCB
+callback during AES key setup. The callback behavior determines the mode:
+
+**If callback returns 0 (success):**
+- Key is imported to Secure Element/HSM
+- Key is NOT copied to wolfSSL RAM (true key isolation)
+- GCM tables are NOT generated (full hardware offload)
+- All subsequent AES operations route through CryptoCB
+
+**If callback returns CRYPTOCB_UNAVAILABLE:**
+- SE doesn't support key import
+- Normal software AES path is used
+- Key is copied to devKey for CryptoCB encrypt/decrypt acceleration
+
+This feature enables TLS 1.3 traffic key protection on embedded platforms
+where symmetric keys must never exist in main RAM.
+
+Enable with: `CPPFLAGS="-DWOLF_CRYPTO_CB_AES_SETKEY -DWOLF_CRYPTO_CB_FREE"`
+
 ### 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,63 @@ 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 (devKey) for fallback
+    - GCM tables ARE generated for software fallback
+    - Provides hardware acceleration with automatic fallback
+
+    **Crypto-Only Builds (--disable-tls):**
+    - Key bytes NOT stored in wolfCrypt memory (true key isolation)
+    - GCM tables skipped (true hardware offload)
+    - Callback must handle all GCM operations (SetKey, Encrypt, Decrypt, Free)
+
+    If the callback returns success (0), full AES-GCM offload is assumed.
+    The callback must handle SetKey, Encrypt, Decrypt, and Free operations.
+
+    \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
+
+    _Example_
+    \code
+    #include <wolfssl/wolfcrypt/cryptocb.h>
+    #include <wolfssl/wolfcrypt/aes.h>
+
+    Aes aes;
+    byte key[32] = { /* 256-bit key */ };
+    int devId = 1;
+
+    /* 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)) == 0) {
+        /* Key successfully imported to device via callback */
+        /* aes.devCtx now contains device handle */
+        /* Full GCM offload is assumed - callback must handle all operations */
+    }
+    \endcode
+
+    \sa wc_CryptoCb_RegisterDevice
+    \sa wc_AesInit
+*/
+int wc_CryptoCb_AesSetKey(Aes* aes, const byte* key, word32 keySz);

doc/dox_comments/header_files/doxygen_pages.h

@@ -74,4 +74,27 @@
     - \ref SAKKE_RSK
     - \ref SAKKE_Operations
 */
+/*!
+    \page AES_CryptoCB_KeyImport AES CryptoCB Key Import
+
+    When enabled via WOLF_CRYPTO_CB_AES_SETKEY, wolfSSL invokes a CryptoCB
+    callback during AES key setup. The callback behavior determines the mode:
+
+    **If callback returns 0 (success):**
+    - Key is imported to Secure Element/HSM
+    - Key is NOT copied to wolfSSL RAM (true key isolation)
+    - GCM tables are NOT generated (full hardware offload)
+    - All subsequent AES operations route through CryptoCB
+
+    **If callback returns CRYPTOCB_UNAVAILABLE:**
+    - SE doesn't support key import
+    - Normal software AES path is used
+    - Key is copied to devKey for CryptoCB encrypt/decrypt acceleration
+
+    This mode is compatible with Secure Elements and hardware-backed
+    key storage and is intended for protecting TLS traffic keys.
+
+    \sa wc_CryptoCb_AesSetKey
+    \sa \ref Crypto Callbacks
+*/