Add one-shot HMAC generate and verify API

doc/dox_comments/header_files/hmac.h

@@ -125,6 +125,163 @@ int wc_HmacFinal(Hmac* hmac, byte* out);
 */
 int wolfSSL_GetHmacMaxSize(void);
 
+/*!
+    \ingroup HMAC
+
+    \brief Single shot function for generating an HMAC. Initializes, keys,
+    hashes the message and finalizes in one call. The full digest size tag of
+    the hash type is always written.
+
+    \return 0 on success
+    \return BAD_FUNC_ARG if out or outSz is NULL, in is NULL with a non-zero
+    inSz, key is NULL with a non-zero keySz, or type is invalid
+    \return BUFFER_E if *outSz is smaller than the digest size of type
+    \return MEMORY_E if allocating the HMAC context fails
+    \return HMAC_MIN_KEYLEN_E may be returned in FIPS builds when the key is
+    shorter than the FIPS minimum
+
+    \param type hash type, such as WC_SHA256 or WC_SHA3_384
+    \param out buffer to hold the tag
+    \param outSz on input the size of out, at least the digest size of type
+    (WC_MAX_DIGEST_SIZE always fits); on output the digest size
+    \param in message to authenticate
+    \param inSz length of the message
+    \param key HMAC key; may be NULL when keySz is 0
+    \param keySz length of the key
+
+    _Example_
+    \code
+    byte   tag[WC_SHA256_DIGEST_SIZE];
+    word32 tagSz = sizeof(tag);
+    ret = wc_HmacGenerate(WC_SHA256, tag, &tagSz, msg, msgSz, key, keySz);
+    \endcode
+
+    \sa wc_HmacGenerate_ex
+    \sa wc_HmacVerify
+*/
+int wc_HmacGenerate(int type, byte* out, word32* outSz,
+                    const byte* in, word32 inSz,
+                    const byte* key, word32 keySz);
+
+/*!
+    \ingroup HMAC
+
+    \brief Same as wc_HmacGenerate, but uses caller provided storage for the
+    HMAC context and takes a heap hint and device ID. The context is
+    initialized with wc_HmacInit and released with wc_HmacFree inside this
+    call, so it must not hold a live HMAC operation on entry.
+
+    \return see wc_HmacGenerate; also BAD_FUNC_ARG if hmac is NULL
+    \return WC_PENDING_E if a crypto callback device returned pending; the
+    context has been freed and no tag was produced. The caller may call
+    again, which starts a new operation.
+
+    \param hmac storage for the HMAC context
+    \param type hash type, such as WC_SHA256 or WC_SHA3_384
+    \param out buffer to hold the tag
+    \param outSz on input the size of out; on output the digest size
+    \param in message to authenticate
+    \param inSz length of the message
+    \param key HMAC key; may be NULL when keySz is 0
+    \param keySz length of the key
+    \param heap heap hint for dynamic memory, or NULL
+    \param devId device ID for crypto callbacks or async, or INVALID_DEVID
+
+    _Example_
+    \code
+    Hmac   hmac;
+    byte   tag[WC_SHA256_DIGEST_SIZE];
+    word32 tagSz = sizeof(tag);
+    ret = wc_HmacGenerate_ex(&hmac, WC_SHA256, tag, &tagSz, msg, msgSz,
+                             key, keySz, NULL, devId);
+    \endcode
+
+    \sa wc_HmacGenerate
+    \sa wc_HmacVerify_ex
+*/
+int wc_HmacGenerate_ex(Hmac* hmac, int type, byte* out, word32* outSz,
+                       const byte* in, word32 inSz,
+                       const byte* key, word32 keySz,
+                       void* heap, int devId);
+
+/*!
+    \ingroup HMAC
+
+    \brief Single shot function for validating an HMAC. Computes the tag over
+    the message and compares it against check in constant time. Only full
+    length tags are accepted.
+
+    \return 0 if the tag matches
+    \return MAC_CMP_FAILED_E if the tag does not match
+    \return BAD_FUNC_ARG if check is NULL, checkSz is not the digest size of
+    type, or any wc_HmacGenerate argument check fails
+    \return MEMORY_E if allocating the HMAC context fails
+    \return HMAC_MIN_KEYLEN_E may be returned in FIPS builds when the key is
+    shorter than the FIPS minimum
+
+    \param type hash type, such as WC_SHA256 or WC_SHA3_384
+    \param check expected tag
+    \param checkSz length of the expected tag; must equal the digest size of
+    type
+    \param in message that was authenticated
+    \param inSz length of the message
+    \param key HMAC key; may be NULL when keySz is 0
+    \param keySz length of the key
+
+    _Example_
+    \code
+    ret = wc_HmacVerify(WC_SHA256, tag, tagSz, msg, msgSz, key, keySz);
+    if (ret == MAC_CMP_FAILED_E) {
+        // reject the message
+    }
+    \endcode
+
+    \sa wc_HmacVerify_ex
+    \sa wc_HmacGenerate
+*/
+int wc_HmacVerify(int type, const byte* check, word32 checkSz,
+                  const byte* in, word32 inSz,
+                  const byte* key, word32 keySz);
+
+/*!
+    \ingroup HMAC
+
+    \brief Same as wc_HmacVerify, but uses caller provided storage for the
+    HMAC context and takes a heap hint and device ID. The context is
+    initialized and freed inside this call.
+
+    \return see wc_HmacVerify; also BAD_FUNC_ARG if hmac is NULL
+    \return WC_PENDING_E if a crypto callback device returned pending; the
+    context has been freed and the tag was not checked. The caller may call
+    again, which starts a new operation.
+
+    \param hmac storage for the HMAC context
+    \param type hash type, such as WC_SHA256 or WC_SHA3_384
+    \param check expected tag
+    \param checkSz length of the expected tag; must equal the digest size of
+    type
+    \param in message that was authenticated
+    \param inSz length of the message
+    \param key HMAC key; may be NULL when keySz is 0
+    \param keySz length of the key
+    \param heap heap hint for dynamic memory, or NULL
+    \param devId device ID for crypto callbacks or async, or INVALID_DEVID
+
+    _Example_
+    \code
+    Hmac hmac;
+    ret = wc_HmacVerify_ex(&hmac, WC_SHA256, tag, tagSz, msg, msgSz,
+                           key, keySz, NULL, devId);
+    \endcode
+
+    \sa wc_HmacVerify
+    \sa wc_HmacGenerate_ex
+*/
+int wc_HmacVerify_ex(Hmac* hmac, int type, const byte* check, word32 checkSz,
+                     const byte* in, word32 inSz,
+                     const byte* key, word32 keySz,
+                     void* heap, int devId);
+
 /*!
     \ingroup HMAC