NAME¶

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

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¶

The libkeccak_zerocopy_digest() function absorbs the last part of (or all of) a message, and returns 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 be processed by calls to the libkeccak_zerocopy_update(3) function (with the same pointer on state,) msg and msglen should be set to NULL and 0, respectively.

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. msglen must only count the number of whole bytes, that is, the floor of the number of bits in the message divided by 8.

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.

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.

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.

RETURN VALUES¶

The libkeccak_zerocopy_digest() function does not return a value.

ERRORS¶

The libkeccak_zerocopy_digest() function cannot fail.

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.

NOTES¶

For cSHAKE, the 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.

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)