Document how wc_AesGcmSetKey and a claiming callback treat the key

The wc_AesGcmSetKey() doxygen did not say what this series changed for
its callers: a new key drops the streaming state, so the update calls
return MISSING_IV until the next wc_AesGcmInit(); a nonce cached with
wc_AesGcmSetIV() or wc_AesGcmSetExtIV() is kept; and a key a crypto
callback device claims without a software schedule leaves streaming GCM
at MISSING_KEY.

The callback contract told a callback that sets aes->rounds to write a
key schedule into aes->key. That is not enough in every build: the
bitsliced and C-fallback builds read other fields, which the pre-claim
wipe has just zeroed, and the AES-NI and ARMv8 flags and the buffered
keystream would still describe the previous key. README.md, the
doxygen page and the cryptocb.h docs now say to build the schedule by
calling wc_AesSetKey() on the same object with aes->devId set to
INVALID_DEVID, as the existing test callback does, which sets all of
that. A WOLF_CRYPTO_CB_AES_SETKEY request carries no key direction, so
only a WOLF_CRYPTO_CB_SETKEY callback can do this.

Two comments in aes.c are reworded.

README.md

@@ -112,8 +112,11 @@ callback during AES key setup. The callback behavior determines the mode:
 - All subsequent AES operations route through CryptoCB; in default builds a
   mode the callback declines returns MISSING_KEY, as does streaming AES-GCM
 
-A callback that sets `aes->rounds` must also write a valid key schedule into
-`aes->key`, since wolfSSL then treats the key as a software key as well.
+A callback that sets `aes->rounds` must also build a software key schedule,
+since wolfSSL then treats the key as a software key as well. It does so by
+calling `wc_AesSetKey()` on the same object with `aes->devId` set to
+`INVALID_DEVID`. This request carries no key direction, so only a
+`WOLF_CRYPTO_CB_SETKEY` callback, which is given one, can build it.
 
 **If callback returns CRYPTOCB_UNAVAILABLE:**
 - SE doesn't support key import

doc/dox_comments/header_files/aes.h

@@ -353,6 +353,13 @@ int  wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len,
     given key. It is only enabled if the configure option
     HAVE_AESGCM is enabled at compile time.
 
+    A new key drops the streaming state, so wc_AesGcmInit() must be called
+    again before wc_AesGcmEncryptUpdate() or wc_AesGcmDecryptUpdate(),
+    which return MISSING_IV until then. A nonce cached with
+    wc_AesGcmSetIV() or wc_AesGcmSetExtIV() is kept. If a crypto callback
+    device claims the key without a software key schedule, the streaming
+    API returns MISSING_KEY.
+
     \return 0 On successfully setting the key.
     \return BAD_FUNC_ARG Returned if the given key is an invalid length.
 

doc/dox_comments/header_files/cryptocb.h

@@ -254,13 +254,16 @@ void wc_CryptoCb_InfoString(wc_CryptoInfo* info);
 
     If the callback returns success (0), the device owns the key. A callback
     that keeps the key only on the device must leave aes->rounds at 0:
-    wolfCrypt takes a non-zero aes->rounds to mean the callback also wrote a
-    software key schedule into aes->key. Without one, wolfCrypt keeps no copy
+    wolfCrypt takes a non-zero aes->rounds to mean the callback also built a
+    software key schedule, by calling wc_AesSetKey() on the same object with
+    aes->devId set to INVALID_DEVID. Without one, wolfCrypt keeps no copy
     in devKey and derives no GCM hash subkey or tables, so the callback must
     handle SetKey, Encrypt, Decrypt, and Free. The streaming GCM API then
     returns MISSING_KEY, and so does a mode the callback declines when
     WOLFSSL_AES_REQUIRE_KEY_SET is in effect (the default). The same applies
-    to a WOLF_CRYPTO_CB_SETKEY callback for WC_SETKEY_AES.
+    to a WOLF_CRYPTO_CB_SETKEY callback for WC_SETKEY_AES. Only that request
+    carries the key direction, so only such a callback can build a software
+    key schedule.
 
     A callback that returns CRYPTOCB_UNAVAILABLE for a new key must first
     release any key it holds for this object and set aes->devCtx to NULL.

doc/dox_comments/header_files/doxygen_pages.h

@@ -89,9 +89,12 @@
       builds a mode the callback declines returns MISSING_KEY, as does
       streaming AES-GCM
 
-    A callback that sets aes->rounds must also write a valid key schedule
-    into aes->key, since wolfSSL then treats the key as a software key as
-    well.
+    A callback that sets aes->rounds must also build a software key
+    schedule, since wolfSSL then treats the key as a software key as well.
+    It does so by calling wc_AesSetKey() on the same object with
+    aes->devId set to INVALID_DEVID. This request carries no key direction,
+    so only a WOLF_CRYPTO_CB_SETKEY callback, which is given one, can build
+    it.
 
     **If callback returns CRYPTOCB_UNAVAILABLE:**
     - SE doesn't support key import

wolfcrypt/src/aes.c

@@ -9349,7 +9349,7 @@ int wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len)
     if (aes->devId != INVALID_DEVID)
     #endif
     {
-        /* No schedule: a device claimed the key or the set-key failed. */
+        /* A claimed or failed key has no schedule to derive H from. */
         if ((ret != 0) || (aes->rounds == 0)) {
             WC_AES_GCM_WIPE_H(aes);
         #ifdef WOLFSSL_IMX6_CAAM_BLOB
@@ -15280,7 +15280,7 @@ int wc_AesGcmInit(Aes* aes, const byte* key, word32 len, const byte* iv,
         }
 
         if ((iv != NULL) && (!aes->gcmKeySet)) {
-            /* No GCM key yet: keep the IV cached for a later call. */
+            /* The IV stays cached until a GCM key is set. */
             aes->nonceSet = 0;
         }
         else if (iv != NULL) {