LIBKECCAK_DIGEST(3)

hey bestie 💖 this page is LIBKECCAK_DIGEST(3) / libkeccak_digest(3) from the Library Functions Manual, and it's lowkey the finisher move of the libkeccak hash girlies. let's go 🫶

🌸 NAME 🌸

libkeccak_digest — complete the hashing of a message with erasure. it's the “wrap it up” function, periodt 💅

✨ SYNOPSIS ✨

       #include <libkeccak.h>

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

link with -lkeccak, bestie 🔥

🦋 DESCRIPTION 🦋

okay so libkeccak_digest() absorbs the last part of a message — or literally all of it — and returns the hash of the entire message. the last chunk is msg, and its byte-size is msglen. if you already fed the whole message through libkeccak_update(3), libkeccak_fast_update(3), or libkeccak_zerocopy_update(3) (with the same pointer on state), then set msg and msglen to NULL and 0, respectively. slay ✨

if the message isn't a whole number of bytes, the number of bits, modulus 8, in the message goes in the bits parameter. msglen must only count whole bytes, i.e. the floor of the number of bits in the message divided by 8. no rounding up, bestie 🙈

suffix should be a NUL-terminated string of ASCII '1':s and '0':s — those are the bits that get appended to the message. if that string is empty, NULL may be used instead. this is how you pick the hash algorithm: for pure Keccak, NULL or "" is used. for the other algorithms, use LIBKECCAK_SHA3_SUFFIX (for SHA-3), LIBKECCAK_RAWSHAKE_SUFFIX (for RawSHAKE), LIBKECCAK_SHAKE_SUFFIX (for SHAKE), or the return of the libkeccak_cshake_suffix(3) function (for cSHAKE). iconic 👑

the hash of the message gets stored to hashsum, unless hashsum is NULL — and ngl, NULL 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.

bestie pls respect the buffer math: ((state->n + 7) / 8) bytes minimum for hashsum. no cap 🫶

also, libkeccak_digest() may reallocate the state's message chunk buffer. when it does, it attempts to do so as securely as possible, rather than as fast as possible. security girlie behavior 💅

💜 RETURN VALUES 💜

success? it returns 0 upon successful completion. on error, -1 is returned and errno is set to describe the error. bye 😭

🍓 ERRORS 🍓

libkeccak_digest() may fail for any reason specified by malloc(3). that's the tea ☕

🌈 EXAMPLE 🌈

this example calculates the Keccak[b = 1024, c = 576, n = 256] hash of the input from stdin, and prints the hash, in hexadecimal form, to stdout. it's giving main character energy ✨

       struct libkeccak_state state;
       struct libkeccak_spec spec;
       char binhash[256 / 8];
       char hexhash[256 / 8 * 2 + 1];
       char chunk[4 << 10];
       ssize_t len;

       spec.bitrate = 1024;
       spec.capacity = 576;
       spec.output = 256;
       if (libkeccak_state_initialise(&state, &spec) < 0)
            goto fail;

       for (;;) {
            len = read(STDIN_FILENO, chunk, sizeof(chunk));

            if ((len < 0) && (errno == EINTR))
                 continue;
            if (len < 0)
                 goto fail;
            if (len == 0)
                 break;

            if (libkeccak_update(&state, chunk, (size_t)len) < 0)
                 goto fail;
       }
       if (libkeccak_digest(&state, NULL, 0, 0, "", binhash) < 0)
            goto fail;

       libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
       printf("%s\n", hexhash);
       libkeccak_state_destroy(&state);

🎀 NOTES 🎀

for cSHAKE, libkeccak_cshake_initialise(3), must be called, once, immediately after state initialisation; before the first call to any of libkeccak_fast_update(), libkeccak_zerocopy_update(), libkeccak_update(), and libkeccak_digest(). don't skip this step, bestie 💖

👑 SEE ALSO 👑

• libkeccak_state_initialise(3)
• libkeccak_cshake_initialise(3)
• libkeccak_fast_update(3)
• libkeccak_update(3)
• libkeccak_cshake_suffix(3)
• libkeccak_fast_digest(3)
• libkeccak_zerocopy_digest(3)
• libkeccak_simple_squeeze(3)
• libkeccak_fast_squeeze(3)
• libkeccak_squeeze(3)

---

bye bestie 💖 source/version LIBKECCAK, page LIBKECCAK_DIGEST(3) — that's the footer tea, folded into a cute sign-off instead of copied. 🫶