diff options
Diffstat (limited to 'libkeccak_digest.3')
| -rw-r--r-- | libkeccak_digest.3 | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/libkeccak_digest.3 b/libkeccak_digest.3 new file mode 100644 index 0000000..5f42796 --- /dev/null +++ b/libkeccak_digest.3 @@ -0,0 +1,139 @@ +.TH LIBKECCAK_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_digest - Complete the hashing of a message with erasure +.SH SYNOPSIS +.nf +#include <libkeccak.h> + +int libkeccak_digest(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP, + size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP); +.fi +.PP +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_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 +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_update (3) +function or the +.BR libkeccak_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +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 +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I 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, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or \(dq\(dq is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.I hashsum +is +.I NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_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. +.SH RETURN VALUES +The +.BR libkeccak_digest () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_digest () +function may fail for any reason specified by the function +.BR malloc (3). +.SH 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. +.PP +.nf +libkeccak_state_t state; +libkeccak_spec_t 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, \(dq\(dq, binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf(\(dq%s\en\(dq, hexhash); +libkeccak_state_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (3) |