From 5445b183ed0e67e275cc69c5f8d0bece6535e06d Mon Sep 17 00:00:00 2001
From: David Garske <david@wolfssl.com>
Date: Thu, 11 Aug 2022 08:59:14 -0700
Subject: [PATCH] Adding CMAC documentation. Fixes ZD14601.

---
 doc/dox_comments/header_files/cmac.h          | 158 ++++++++++++++++++
 .../header_files/doxygen_groups.h             |   1 +
 doc/dox_comments/header_files/doxygen_pages.h |   1 +
 3 files changed, 160 insertions(+)
 create mode 100644 doc/dox_comments/header_files/cmac.h

diff --git a/doc/dox_comments/header_files/cmac.h b/doc/dox_comments/header_files/cmac.h
new file mode 100644
index 000000000..a2f36a52c
--- /dev/null
+++ b/doc/dox_comments/header_files/cmac.h
@@ -0,0 +1,158 @@
+/*!
+    \ingroup CMAC
+    \brief Initialize the Cmac structure with defaults
+    \return 0 on success
+    \param cmac pointer to the Cmac structure
+    \param key key pointer
+    \param keySz size of the key pointer (16, 24 or 32)
+    \param type Always WC_CMAC_AES = 1
+    \param unused not used, exists for potential future use around compatiblity
+
+    _Example_
+    \code
+    Cmac cmac[1];
+    ret = wc_InitCmac(cmac, key, keySz, WC_CMAC_AES, NULL);
+    if (ret == 0) {
+        ret = wc_CmacUpdate(cmac, in, inSz);
+    }
+    if (ret == 0) {
+        ret = wc_CmacFinal(cmac, out, outSz);
+    }
+    \endcode
+
+    \sa wc_InitCmac_ex
+    \sa wc_CmacUpdate
+    \sa wc_CmacFinal
+*/
+int wc_InitCmac(Cmac* cmac,
+                const byte* key, word32 keySz,
+                int type, void* unused);
+
+/*!
+    \ingroup CMAC
+    \brief Initialize the Cmac structure with defaults
+    \return 0 on success
+    \param cmac pointer to the Cmac structure
+    \param key key pointer
+    \param keySz size of the key pointer (16, 24 or 32)
+    \param type Always WC_CMAC_AES = 1
+    \param unused not used, exists for potential future use around compatiblity
+    \param heap pointer to the heap hint used for dynamic allocation. Typically used with our static memory option. Can be NULL.
+    \param devId ID to use with async hardware. Set to INVALID_DEVID if not using async hardware.
+
+    _Example_
+    \code
+    Cmac cmac[1];
+    ret = wc_InitCmac_ex(cmac, key, keySz, WC_CMAC_AES, NULL, NULL, INVALID_DEVID);
+    if (ret == 0) {
+        ret = wc_CmacUpdate(cmac, in, inSz);
+    }
+    if (ret == 0) {
+        ret = wc_CmacFinal(cmac, out, &outSz);
+    }
+    \endcode
+
+    \sa wc_InitCmac_ex
+    \sa wc_CmacUpdate
+    \sa wc_CmacFinal
+*/
+int wc_InitCmac_ex(Cmac* cmac,
+                const byte* key, word32 keySz,
+                int type, void* unused, void* heap, int devId);
+
+/*!
+    \ingroup CMAC
+    \brief Add Cipher-based Message Authentication Code input data
+    \return 0 on success
+    \param cmac pointer to the Cmac structure
+    \param in input data to process
+    \param inSz size of input data
+
+    _Example_
+    \code
+    ret = wc_CmacUpdate(cmac, in, inSz);
+    \endcode
+
+    \sa wc_InitCmac
+    \sa wc_CmacFinal
+*/
+int wc_CmacUpdate(Cmac* cmac,
+                  const byte* in, word32 inSz);
+
+/*!
+    \ingroup CMAC
+    \brief Generate the final result using Cipher-based Message Authentication Code
+    \return 0 on success
+    \param cmac pointer to the Cmac structure
+    \param out pointer to return the result
+    \param outSz pointer size of output (in/out)
+
+    _Example_
+    \code
+    ret = wc_CmacFinal(cmac, out, &outSz);
+    \endcode
+
+    \sa wc_InitCmac
+    \sa wc_CmacFinal
+*/
+int wc_CmacFinal(Cmac* cmac,
+                 byte* out, word32* outSz);
+
+/*!
+    \ingroup CMAC
+    \brief Single shot fuction for generating a CMAC
+    \return 0 on success
+    \param out pointer to return the result
+    \param outSz pointer size of output (in/out)
+    \param in input data to process
+    \param inSz size of input data
+    \param key key pointer
+    \param keySz size of the key pointer (16, 24 or 32)
+
+    _Example_
+    \code
+    ret = wc_AesCmacGenerate(mac, &macSz, msg, msgSz, key, keySz);
+    \endcode
+
+    \sa wc_AesCmacVerify
+*/
+int wc_AesCmacGenerate(byte* out, word32* outSz,
+                       const byte* in, word32 inSz,
+                       const byte* key, word32 keySz);
+
+/*!
+    \ingroup CMAC
+    \brief Single shot fuction for validating a CMAC
+    \return 0 on success
+    \param check pointer to return the result
+    \param checkSz size of checkout buffer
+    \param in input data to process
+    \param inSz size of input data
+    \param key key pointer
+    \param keySz size of the key pointer (16, 24 or 32)
+
+    _Example_
+    \code
+    ret = wc_AesCmacVerify(mac, macSz, msg, msgSz, key, keySz);
+    \endcode
+
+    \sa wc_AesCmacGenerate
+*/
+int wc_AesCmacVerify(const byte* check, word32 checkSz,
+                     const byte* in, word32 inSz,
+                     const byte* key, word32 keySz);
+
+
+/*!
+    \ingroup CMAC
+    \brief Only used with WOLFSSL_HASH_KEEP when hardware requires single-shot and the updates must be cached in memory
+    \return 0 on success
+    \param in input data to process
+    \param inSz size of input data
+
+    _Example_
+    \code
+    ret = wc_CMAC_Grow(cmac, in, inSz)
+    \endcode
+*/
+int wc_CMAC_Grow(Cmac* cmac, const byte* in, int inSz);
diff --git a/doc/dox_comments/header_files/doxygen_groups.h b/doc/dox_comments/header_files/doxygen_groups.h
index e7102a52c..fc7c253c5 100644
--- a/doc/dox_comments/header_files/doxygen_groups.h
+++ b/doc/dox_comments/header_files/doxygen_groups.h
@@ -6,6 +6,7 @@
     \defgroup Camellia Algorithms - Camellia
     \defgroup ChaCha Algorithms - ChaCha
     \defgroup ChaCha20Poly1305 Algorithms - ChaCha20_Poly1305
+    \defgroup CMAC Algorithm - CMAC
     \defgroup Crypto Callbacks - CryptoCb
     \defgroup Curve25519 Algorithms - Curve25519
     \defgroup Curve448 Algorithms - Curve448
diff --git a/doc/dox_comments/header_files/doxygen_pages.h b/doc/dox_comments/header_files/doxygen_pages.h
index 39065f819..56b9025e0 100644
--- a/doc/dox_comments/header_files/doxygen_pages.h
+++ b/doc/dox_comments/header_files/doxygen_pages.h
@@ -34,6 +34,7 @@
         <li>\ref Camellia</li>
         <li>\ref ChaCha</li>
         <li>\ref ChaCha20Poly1305</li>
+        <li>\ref CMAC</li>
         <li>\ref Crypto Callbacks</li>
         <li>\ref Curve25519</li>
         <li>\ref Curve448</li>