LIBKECCAK_SHA3SUM_FD(3)

💖 NAME 💖

libkeccak_sha3sum_fd — Calculate a SHA-3 hashsum of a file 💅

Hey bestie, this is the LIBKECCAK Library Functions Manual page for LIBKECCAK_SHA3SUM_FD(3), and it's about to eat. 🍓

---

✨ SYNOPSIS ✨

#include <libkeccak.h>

int libkeccak_sha3sum_fd(int fd, struct libkeccak_state *state, long int output, void *hashsum);

Link with -lkeccak.

---

💅 DESCRIPTION 💅

Okay so libkeccak_sha3sum_fd() calculates a SHA-3 hashsum of a file. The file descriptor is specified by fd, and bestie, it should be at the beginning of the file. The hash algorithm gets tuned by the output parameter — that one specifies the output size, in bits. 🎀

The hash is stored in binary form to hashsum. And hashsum needs an allocation size of at least (((output + 7) / 8) * sizeof(char)). No cap, size it right. 🌸

*state should not be initialised. libkeccak_sha3sum_fd() initialises *state itself. So if *state is already initialised, there would be a memory leak — very much not the vibe. 😭

---

🫶 RETURN VALUES 🫶

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

---

😭 ERRORS 😭

The libkeccak_sha3sum_fd() function may fail for any reason, except those resulting in errno being set to EINTR, specified for the functions read(2), malloc(3), and realloc(3). So yeah, it can fail for basically anything else — that's the rule, bestie. 💀

---

🧚 NOTES 🧚

Be aware: libkeccak_sha3sum_fd() hashes the file until the end has been reached. For pipes and sockets, this means until the file has been closed. But for character devices, this usually means never. Attempting to hash files in /dev is therefore usually a bad idea. 🚨

libkeccak_sha3sum_fd() does not check for the file length or file type before hashing, as this could limit what you can do, and make the library more complex.

libkeccak_sha3sum_fd() does not stop if interrupted (read(2) returns EINTR.)

libkeccak_sha3sum_fd() assumes all information is non-sensitive, and will therefore not perform any secure erasure of information. 🫶

libkeccak_sha3sum_fd() does not validate the tuning of the algorithm.

---

🍓 EXAMPLE 🍓

This example calculates the SHA3-256 hash of the input from stdin, and prints the hash, in hexadecimal form, to stdout.

struct libkeccak_state state;
if (libkeccak_sha3sum_fd(STDIN_FILENO, &state, 256, binhash) < 0)
     goto fail;
libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
printf("%s\n", hexhash);
libkeccak_state_destroy(&state);

---

🔥 SEE ALSO 🔥

• libkeccak_behex_lower(3)
• libkeccak_behex_upper(3)
• libkeccak_generalised_sum_fd(3)
• libkeccak_keccaksum_fd(3)
• libkeccak_rawshakesum_fd(3)
• libkeccak_shakesum_fd(3)
• libkeccak_spec_sha3(3)
• libkeccak_spec_check(3)
• libkeccak_generalised_spec_initialise(3)
• libkeccak_state_initialise(3)

---

Signed off from the LIBKECCAK manual — the footer source/version says LIBKECCAK and the page is LIBKECCAK_SHA3SUM_FD(3); there's no date in the footer, so I'm not inventing one, bestie 💜✨