allow full offload (with GCM)

Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>

Author: sameehj

README.md

@@ -59,15 +59,21 @@ not using TLS cipher suites.
 
 ### AES CryptoCB Key Import Support
 
-wolfSSL supports offloading AES key handling to external devices
-(e.g., Secure Elements or HSMs) using the Crypto Callback (CryptoCB)
-interface - the same mechanism used for RSA, ECC, and other algorithms.
-
-When `WOLF_CRYPTO_CB_AES_SETKEY` is enabled, AES keys can be imported
-into a device via the CryptoCB callback. The device stores the key
-internally and provides an opaque handle via `aes->devCtx`. Subsequent
-AES-GCM operations are routed through CryptoCB, and wolfCrypt does not
-retain the raw key material.
+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.

doc/dox_comments/header_files/cryptocb.h

@@ -187,18 +187,36 @@ void wc_CryptoCb_InfoString(wc_CryptoInfo* info);
     \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) without exposing raw key material to
-    wolfCrypt. When supported, the device callback stores the key internally
-    and sets an opaque handle in aes->devCtx.
+    (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 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
+    (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
@@ -212,20 +230,28 @@ void wc_CryptoCb_InfoString(wc_CryptoInfo* info);
     Aes aes;
     byte key[32] = { /* 256-bit key */ };
     int devId = 1;
+    int capabilities = 0;
 
-    // Register your CryptoCB callback first
+    /* 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_AesGcmSetKey(&aes, key, sizeof(key)) == 0) {
-        // Key successfully imported to device via callback
-        // aes.devCtx now contains device handle
-        // Subsequent AES-GCM operations will use the device
+    /* 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 wc_CryptoCb_AesSetKey(Aes* aes, const byte* key, word32 keySz,
+                          int* capabilities);

doc/dox_comments/header_files/doxygen_pages.h

@@ -79,9 +79,15 @@
 
     When enabled via WOLF_CRYPTO_CB_AES_SETKEY, wolfSSL allows AES keys
     to be imported into external cryptographic devices using the Crypto
-    Callback interface. In key import mode, AES keys are not retained in
-    wolfCrypt memory. Instead, an opaque device handle is used for all
-    subsequent AES-GCM operations.
+    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.