LIBKECCAK_HMAC_DIGEST(3)

💅 LIBKECCAK_HMAC_DIGEST(3) — libkeccak_hmac_digest 💅

🌸 NAME 🌸

libkeccak_hmac_digest — completes the HMAC-hashing of a message with erasure 💖

---

✨ SYNOPSIS ✨

#include <libkeccak.h>

int libkeccak_hmac_digest(struct libkeccak_hmac_state *state, const void *msg, size_t msglen,
                          size_t bits, const char *suffix, void *hashsum);

Link with -lkeccak. 🫶

---

💖 DESCRIPTION 💖

okay so libkeccak_hmac_digest() is the finisher move, bestie: it absorbs the last part of a message (or literally all of it) and returns the HMAC hash of the entire message ✨

The last part of the message is specified by msg, and its byte-size is specified by msglen. If all of the message has already been processed by calls to libkeccak_hmac_update(3) or libkeccak_hmac_fast_update(3) — with the same pointer on state — then msg and msglen should be set to NULL and 0, respectively. no cap 💅

If the message is not made up of a whole number of bytes, the number of bits, modulus 8, in the message should be specified in the bits parameter. And listen: msglen must only count the number of whole bytes, that is, the floor of the number of bits in the message divided by 8. the math is mathing 🧚

suffix should be a NUL-terminated string of ASCII '1's and '0's, representing the bits that should be appended to the message. If this string is empty, NULL may be used instead. This is used to select hash algorithm. For pure Keccak, NULL or "" is used. For the other algorithms the constants are used:

• LIBKECCAK_SHA3_SUFFIX — for SHA-3 ⭐
• LIBKECCAK_RAWSHAKE_SUFFIX — for RawSHAKE 🦋
• LIBKECCAK_SHAKE_SUFFIX — for SHAKE 🌈

The hash of the message will be stored to hashsum, unless hashsum is NULL — which increases the performance of the call, bestie, because sometimes we’re just here for the vibes and not the output 👑 A total of ((state->n + 7) / 8) bytes will be written to the beginning of hashsum. Therefore, hashsum needs at least an allocation size of that number of bytes.

⚠️ real talk: hashsum needs at least ((state->n + 7) / 8) bytes of space. don’t skimp, bestie 💀

The libkeccak_hmac_digest() function may reallocate the state’s message chunk buffer. When doing so, it attempts to do so as securely as possible, rather than as fast as possible. secure queen behaviour 🎀

---

🎀 RETURN VALUES 🎀

The libkeccak_hmac_digest() function returns 0 upon successful completion. On error, -1 is returned and errno is set to describe the error. 😭

---

🔥 ERRORS 🔥

The libkeccak_hmac_digest() function may fail for any reason specified by the function malloc(3). that’s the whole error tea 🙈

---

🦋 SEE ALSO 🦋

• libkeccak_hmac_create(3)
• libkeccak_hmac_initialise(3)
• libkeccak_hmac_update(3)
• libkeccak_hmac_fast_digest(3)

---

Source/version: LIBKECCAK · page: LIBKECCAK_HMAC_DIGEST(3) · date: the original footer didn’t list one, so we’re keeping it mysterious 🫶✨