Merge pull request #5459 from dgarske/docs

Improve documentation for CMAC

doc/dox_comments/header_files/asn_public.h

@@ -1994,7 +1994,7 @@ time_t wc_Time(time_t* t);
     \param cert Pointer to an initialized DecodedCert object.
     \param critical If 0, the extension will not be marked critical, otherwise
      it will be marked critical.
-    \param oid Dot separted oid as a string. For example "1.2.840.10045.3.1.7"
+    \param oid Dot separated oid as a string. For example "1.2.840.10045.3.1.7"
     \param der The der encoding of the content of the extension.
     \param derSz The size in bytes of the der encoding.
 
@@ -2080,7 +2080,7 @@ int wc_SetCustomExtension(Cert *cert, int critical, const char *oid,
     \sa ParseCert
     \sa wc_SetCustomExtension
 */
-WOLFSSL_ASN_API int wc_SetUnknownExtCallback(DecodedCert* cert,
+int wc_SetUnknownExtCallback(DecodedCert* cert,
                                              wc_UnknownExtCallback cb);
 /*!
     \ingroup ASN
@@ -2099,8 +2099,7 @@ WOLFSSL_ASN_API int wc_SetUnknownExtCallback(DecodedCert* cert,
     \param pubKeySz The size in bytes of pubKey.
     \param pubKeyOID OID identifying the algorithm of the public key.
     (ie: ECDSAk, DSAk or RSAk)
-
+*/
 int wc_CheckCertSigPubKey(const byte* cert, word32 certSz,
                                       void* heap, const byte* pubKey,
                                       word32 pubKeySz, int pubKeyOID);
-*/

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);

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

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>

wolfssl/wolfcrypt/types.h

@@ -226,7 +226,7 @@ typedef struct w64wrapper {
 #endif /* WORD64_AVAILABLE && WOLFSSL_W64_WRAPPER_TEST */
 } w64wrapper;
 
-#ifdef WC_PTR_TYPE /* Allow user suppied type */
+#ifdef WC_PTR_TYPE /* Allow user supplied type */
     typedef WC_PTR_TYPE wc_ptr_t;
 #elif defined(HAVE_UINTPTR_T)
     #include <stdint.h>