LIBKECCAK_ZEROCOPY_DIGEST(3)

💖 NAME 💖

libkeccak_zerocopy_digest — Complete the hashing of a message without copying (ADVANCED)

First things first: this is the LIBKECCAK_ZEROCOPY_DIGEST(3) page from the Library Functions Manual, and we are folding that manual name in right here like a cute little name tag 🫶.

🦋 SYNOPSIS 🦋

#include <libkeccak.h>

void libkeccak_zerocopy_digest(struct libkeccak_state *state, void *msg, size_t msglen,
                               size_t bits, const char *suffix, void *hashsum);

Link with -lkeccak.

✨ DESCRIPTION ✨

Okay bestie, libkeccak_zerocopy_digest() is the grand finale: it absorbs the last part of (or all of) a message, and gives you the hash of the entire message. The last part of the message is specified by the msg parameter, and its byte-size is specified by the msglen parameter. If all of the message has already been processed by calls to libkeccak_zerocopy_update(3) (with the same pointer on state), then msg and msglen should be set to NULL and 0, respectively. No cap, that's the whole setup. ✨

If the message is not comprised a whole number of bytes, the number of bits, modulus 8, in the message should be specified in the bits parameter. And msglen must only count the number of whole bytes — that is, the floor of the number of bits in the message divided by 8. Math check, bestie. 🧮

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 LIBKECCAK_SHA3_SUFFIX (for SHA-3), LIBKECCAK_RAWSHAKE_SUFFIX (for RawSHAKE), and LIBKECCAK_SHAKE_SUFFIX (for SHAKE), or the return of the libkeccak_cshake_suffix(3) function (for cSHAKE), are used. Algorithm selection is literally the vibe check here. 💅

The hash of the message will be stored to hashsum, unless hashsum is NULL (which increases the performance of the call). 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. Allocate accordingly, queen. 👑

🚨 Danger-ish territory, pay attention: libkeccak_zerocopy_digest() will write at and beyond &msg[msglen]. The caller must make sure that enough memory is allocated for the suffix as well as padding of at least 2 bits, for msg. The sum of msglen, the bits specified in suffix, and the padded, shall, in bytes, be an integer multiple of the bitrate divided by eight, which is returned by the libkeccak_zerocopy_chunksize(3) function. Like, do not skimp on this buffer, bestie — this is not the moment for guessing. 😭

🫶 RETURN VALUES 🫶

The libkeccak_zerocopy_digest() function does not return a value. Void function, no return era, periodt. 💀

💅 ERRORS 💅

The libkeccak_zerocopy_digest() function cannot fail. No errors, no drama, no surprise pop quiz. 🎀

📝 NOTES 📝

Calling the libkeccak_zerocopy_digest(3) function after the libkeccak_update(3) or libkeccak_fast_update(3) functions, with the same state argument, may cause the message to be misread. So like, don't mix those calls with the same state, iykyk. 🙈

🧚 NOTES 🧚

For cSHAKE, libkeccak_cshake_initialise(3), must be called, once, immediately after state initialisation; before the first call to any of the libkeccak_fast_update(), libkeccak_zerocopy_update(), libkeccak_update(), and libkeccak_zerocopy_digest() functions. cSHAKE girlies, do this first or the whole vibe is off. 🦋

🌈 SEE ALSO 🌈

• libkeccak_state_initialise(3)
• libkeccak_cshake_initialise(3)
• libkeccak_zerocopy_chunksize(3)
• libkeccak_fast_update(3)
• libkeccak_zerocopy_update(3)
• libkeccak_update(3)
• libkeccak_cshake_suffix(3)
• libkeccak_digest(3)
• libkeccak_zerocopy_digest(3)
• libkeccak_simple_squeeze(3)
• libkeccak_fast_squeeze(3)
• libkeccak_squeeze(3)

---

That's the whole page, bestie. 🎀 The footer's source/version is LIBKECCAK, and the footer page marker repeats LIBKECCAK_...COPY_DIGEST(3); there is no date line shown in the original, so I'm not inventing one. Byeee 💅✨