Peer review improvements.

Author: dgarske

doc/dox_comments/header_files/aes.h

@@ -2315,6 +2315,12 @@ int wc_AesCtrSetKey(Aes* aes, const byte* key, word32 len, const byte* iv,
     update parameter. It allows for key updates in certain hardware
     implementations.
 
+    \note This function is currently only available when building with
+    Xilinx hardware acceleration. It requires one of the following build
+    options: WOLFSSL_XILINX_CRYPT (for Xilinx SecureIP integration) or
+    WOLFSSL_AFALG_XILINX_AES (for Xilinx AF_ALG support). This API may
+    be exposed for additional build configurations in the future.
+
     \return 0 On success.
     \return BAD_FUNC_ARG If aes or key is NULL, or if key length is invalid.
 
@@ -2460,8 +2466,15 @@ int wc_AesGcmEncryptInit_ex(Aes* aes, const byte* key, word32 len,
     It processes plaintext and/or additional authentication data (AAD)
     in a streaming fashion.
 
+    All the AAD must be passed to update before the plaintext.
+    The last part of AAD can be passed with the first part of plaintext.
+
+    Must set key and IV before calling this function.
+    Must call wc_AesGcmInit() before calling this function.
+
     \return 0 On success.
-    \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.
+    \return BAD_FUNC_ARG If aes is NULL, or a length is non-zero but
+    buffer is NULL.
 
     \param aes pointer to the AES structure
     \param out pointer to buffer to store ciphertext (can be NULL if sz=0)
@@ -2480,7 +2493,7 @@ int wc_AesGcmEncryptInit_ex(Aes* aes, const byte* key, word32 len,
     byte aad[20] = { }; // additional data
 
     wc_AesInit(&aes, NULL, INVALID_DEVID);
-    wc_AesGcmEncryptInit(&aes, key, 16, iv, 12);
+    wc_AesGcmInit(&aes, key, 16, iv, 12);
     int ret = wc_AesGcmEncryptUpdate(&aes, ciphertext, plaintext, 100,
                                      aad, 20);
     if (ret != 0) {
@@ -2489,6 +2502,7 @@ int wc_AesGcmEncryptInit_ex(Aes* aes, const byte* key, word32 len,
     wc_AesFree(&aes);
     \endcode
 
+    \sa wc_AesGcmInit
     \sa wc_AesGcmEncryptInit
     \sa wc_AesGcmEncryptFinal
 */
@@ -2575,8 +2589,15 @@ int wc_AesGcmDecryptInit(Aes* aes, const byte* key, word32 len,
     It processes ciphertext and/or additional authentication data (AAD)
     in a streaming fashion.
 
+    All the AAD must be passed to update before the ciphertext.
+    The last part of AAD can be passed with the first part of ciphertext.
+
+    Must set key and IV before calling this function.
+    Must call wc_AesGcmInit() before calling this function.
+
     \return 0 On success.
-    \return BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.
+    \return BAD_FUNC_ARG If aes is NULL, or a length is non-zero but
+    buffer is NULL.
 
     \param aes pointer to the AES structure
     \param out pointer to buffer to store plaintext (can be NULL if sz=0)
@@ -2595,7 +2616,7 @@ int wc_AesGcmDecryptInit(Aes* aes, const byte* key, word32 len,
     byte aad[20] = { }; // additional data
 
     wc_AesInit(&aes, NULL, INVALID_DEVID);
-    wc_AesGcmDecryptInit(&aes, key, 16, iv, 12);
+    wc_AesGcmInit(&aes, key, 16, iv, 12);
     int ret = wc_AesGcmDecryptUpdate(&aes, plaintext, ciphertext, 100,
                                      aad, 20);
     if (ret != 0) {
@@ -2604,6 +2625,7 @@ int wc_AesGcmDecryptInit(Aes* aes, const byte* key, word32 len,
     wc_AesFree(&aes);
     \endcode
 
+    \sa wc_AesGcmInit
     \sa wc_AesGcmDecryptInit
     \sa wc_AesGcmDecryptFinal
 */

doc/dox_comments/header_files/signature.h

@@ -177,7 +177,7 @@ int wc_SignatureGenerate(
     word32 sigLen = sizeof(sig);
 
     wc_ecc_init(&eccKey);
-    // import public key and compute hash
+    // import public key, signature, and pre-computed hash ...
     int ret = wc_SignatureVerifyHash(WC_HASH_TYPE_SHA256,
                                      WC_SIGNATURE_TYPE_ECC, hash,
                                      sizeof(hash), sig, sigLen,
@@ -231,7 +231,7 @@ int wc_SignatureVerifyHash(enum wc_HashType hash_type,
     wc_InitRng(&rng);
     wc_ecc_init(&eccKey);
     wc_ecc_make_key(&rng, 32, &eccKey);
-    // compute hash
+    // generate signature from pre-computed hash
     int ret = wc_SignatureGenerateHash(WC_HASH_TYPE_SHA256,
                                        WC_SIGNATURE_TYPE_ECC, hash,
                                        sizeof(hash), sig, &sigLen,

wolfcrypt/src/aes.c

@@ -12095,24 +12095,7 @@ int wc_AesGcmEncryptInit_ex(Aes* aes, const byte* key, word32 len, byte* ivOut,
     return ret;
 }
 
-/* Update the AES GCM for encryption with data and/or authentication data.
- *
- * All the AAD must be passed to update before the plaintext.
- * Last part of AAD can be passed with first part of plaintext.
- *
- * Must set key and IV before calling this function.
- * Must call wc_AesGcmInit() before calling this function.
- *
- * @param [in, out] aes       AES object.
- * @param [out]     out       Buffer to hold cipher text.
- * @param [in]      in        Buffer holding plaintext.
- * @param [in]      sz        Length of plaintext in bytes.
- * @param [in]      authIn    Buffer holding authentication data.
- * @param [in]      authInSz  Length of authentication data in bytes.
- * @return  0 on success.
- * @return  BAD_FUNC_ARG when aes is NULL, or a length is non-zero but buffer
- *          is NULL.
- */
+/* Update the AES GCM for encryption with data and/or authentication data. */
 int wc_AesGcmEncryptUpdate(Aes* aes, byte* out, const byte* in, word32 sz,
     const byte* authIn, word32 authInSz)
 {
@@ -12254,24 +12237,7 @@ int wc_AesGcmDecryptInit(Aes* aes, const byte* key, word32 len, const byte* iv,
     return wc_AesGcmInit(aes, key, len, iv, ivSz);
 }
 
-/* Update the AES GCM for decryption with data and/or authentication data.
- *
- * All the AAD must be passed to update before the cipher text.
- * Last part of AAD can be passed with first part of cipher text.
- *
- * Must set key and IV before calling this function.
- * Must call wc_AesGcmInit() before calling this function.
- *
- * @param [in, out] aes       AES object.
- * @param [out]     out       Buffer to hold plaintext.
- * @param [in]      in        Buffer holding cipher text.
- * @param [in]      sz        Length of cipher text in bytes.
- * @param [in]      authIn    Buffer holding authentication data.
- * @param [in]      authInSz  Length of authentication data in bytes.
- * @return  0 on success.
- * @return  BAD_FUNC_ARG when aes is NULL, or a length is non-zero but buffer
- *          is NULL.
- */
+/* Update the AES GCM for decryption with data and/or authentication data. */
 int wc_AesGcmDecryptUpdate(Aes* aes, byte* out, const byte* in, word32 sz,
     const byte* authIn, word32 authInSz)
 {