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

README.md

@@ -57,6 +57,21 @@ 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 Secure Element / CryptoCB Proxy-Key Support
+
+wolfSSL supports offloading AES key handling to external devices
+(e.g. Secure Elements or HSMs) using the Crypto Callback (CryptoCB)
+interface.
+
+When `WOLF_CRYPTO_CB_AES_SETKEY` is enabled, AES keys can be imported
+into a device and referenced via opaque handles, preventing raw key
+material from being stored in wolfCrypt memory. AES-GCM encryption and
+decryption operations are routed through CryptoCB when a valid device
+ID is set. The device callback must handle these operations.
+
+This feature is commonly used for TLS 1.3 traffic key protection on
+embedded platforms.
+
 ### 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-ja/cryptocb.h

@@ -103,4 +103,4 @@ int  wc_CryptoCb_RegisterDevice(int devId, CryptoDevCallbackFunc cb, void* ctx);
     \sa wolfSSL_SetDevId
     \sa wolfSSL_CTX_SetDevId
 */
-void wc_CryptoCb_UnRegisterDevice(int devId);
+int wc_CryptoCb_UnRegisterDevice(int devId);

doc/dox_comments/header_files/cryptocb.h

@@ -108,7 +108,7 @@ int  wc_CryptoCb_RegisterDevice(int devId, CryptoDevCallbackFunc cb, void* ctx);
     \sa wolfSSL_SetDevId
     \sa wolfSSL_CTX_SetDevId
 */
-void wc_CryptoCb_UnRegisterDevice(int devId);
+int wc_CryptoCb_UnRegisterDevice(int devId);
 
 /*!
     \ingroup CryptoCb
@@ -180,3 +180,52 @@ 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 (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
+
+    _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_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
+    }
+    \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,24 @@
     - \ref SAKKE_RSK
     - \ref SAKKE_Operations
 */
+/*!
+    \page AES_CryptoCB_ProxyKey AES CryptoCB Proxy-Key Mode
+
+    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 this mode, AES keys are not retained in
+    wolfCrypt memory. Instead, an opaque device handle is used for all
+    subsequent AES-GCM operations.
+
+    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
+*/