From ca9ac5d2cbeaf7a63b7407230f4c94a982fca3fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Frauenschl=C3=A4ger?= Date: Thu, 22 Oct 2026 23:17:31 +0200 Subject: [PATCH] Document device-owned keys for wc_AesSetKey and wc_AesCcmSetKey wc_AesSetKey now says that a mode the callback does not handle returns MISSING_KEY once a device claims the key, and that a device error can be returned. wc_AesCcmSetKey says a cached CCM nonce is kept and lists its real return values instead of "none". The SETKEY callback contract also says that a WOLF_CRYPTO_CB_SETKEY callback must release its key and clear aes->devCtx before returning an error, because wolfCrypt clears devCtx itself only after an AES_SETKEY error. --- doc/dox_comments/header_files/aes.h | 13 +++++++++++-- doc/dox_comments/header_files/cryptocb.h | 4 +++- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/doc/dox_comments/header_files/aes.h b/doc/dox_comments/header_files/aes.h index 7b243f70e3..f39d1c5ee6 100644 --- a/doc/dox_comments/header_files/aes.h +++ b/doc/dox_comments/header_files/aes.h @@ -3,8 +3,13 @@ \brief This function initializes an AES structure by setting the key and then setting the initialization vector. + If a crypto callback device claims the key without a software key + schedule, a mode the callback does not handle returns MISSING_KEY when + WOLFSSL_AES_REQUIRE_KEY_SET is in effect (the default). + \return 0 On successfully setting key and initialization vector. \return BAD_FUNC_ARG Returned if key length is invalid. + \return other negative values An error from a crypto callback device. \param aes pointer to the AES structure to modify \param key 16, 24, or 32 byte secret key for encryption and decryption @@ -644,9 +649,13 @@ int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz, \ingroup AES \brief This function sets the key for an AES object using CCM (Counter with CBC-MAC). It takes a pointer to an AES structure and - initializes it with supplied key. + initializes it with supplied key. A nonce cached with + wc_AesCcmSetNonce() is kept. - \return none + \return 0 On successfully setting the key. + \return BAD_FUNC_ARG Returned if aes or key is NULL, or if the given key + is an invalid length. + \return other negative values An error from a crypto callback device. \param aes aes structure in which to store the supplied key \param key 16, 24, or 32 byte secret key for encryption and decryption diff --git a/doc/dox_comments/header_files/cryptocb.h b/doc/dox_comments/header_files/cryptocb.h index cd2f2cff03..3c94038ee2 100644 --- a/doc/dox_comments/header_files/cryptocb.h +++ b/doc/dox_comments/header_files/cryptocb.h @@ -271,7 +271,9 @@ void wc_CryptoCb_InfoString(wc_CryptoInfo* info); release any key it holds for this object and set aes->devCtx to NULL. wolfCrypt sets the new key up in software and leaves aes->devCtx alone, so a stale handle would keep the operations the callback accepts on the - old key. + old key. A WOLF_CRYPTO_CB_SETKEY callback must do the same before it + returns an error, since wolfCrypt clears aes->devCtx only after an + error from this request. \param aes AES context \param key Pointer to raw AES key material