.TH LIBKECCAK_SHAKESUM_FD 3 LIBKECCAK-%VERSION%
.SH NAME
libkeccak_shakesum_fd - Calculate a SHAKE hashsum of a file
.SH SYNOPSIS
.LP
.nf
#include <libkeccak.h>
.P
int libkeccak_shakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP,
long \fIsemicapacity\fP, long \fIoutput\fP,
char *\fIhashsum\fP);
.fi
.P
Link with \fI-lkeccak\fP.
.SH DESCRIPTION
The
.BR libkeccak_shakesum_fd ()
calculates a SHAKE hashsum of a file, whose file desriptor is
specified by \fIfd\fP (and should be at the beginning of the file.)
The hash algorithm is tuned by the \fIsemicapacity\fP and \fIoutput\fP
parameters; they specify the half of the capacity and the output size,
respectively, in bits.
.PP
The hash is stored in binary form to \fIhashsum\fP. \fIhashsum\fP
should have an allocation size of at least
(((\fIoutput\fP + 7) / 8) * sizeof(char)).
.PP
\fI*state\fP should not be initialised.
.BR libkeccak_shakesum_fd ()
initialises \fI*state\fP itself. Therefore there would be a
memory leak if \fI*state\fP is already initialised.
.SH RETURN VALUES
The
.BR libkeccak_shakesum_fd ()
function return 0 upon successful completion.
On error, -1 is returned and \fIerrno\fP is set to describe
the error.
.SH ERRORS
The
.BR libkeccak_shakesum_fd ()
function may fail for any reason, except those resulting
in \fIerrno\fP being set to \fBEINTR\fP, specified for the
functions
.BR read (2),
.BR malloc (3),
and
.BR realloc (3).
.SH NOTES
Be aware,
.BR libkeccak_shakesum_fd ()
hashes the file until the end has been reached. For pipes
and sockets and 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.
.BR libkeccak_shakesum_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.
.PP
.BR libkeccak_shakesum_fd ()
does not stop if interrupted (\fBread\fP(2) returns
\fBEINTR\fP.)
.PP
.BR libkeccak_shakesum_fd ()
assumes all information is non-sensitive, and will
therefore not perform any secure erasure of information.
.PP
.BR libkeccak_shakesum_fd ()
does not validate the tuning of the algorithm.
.SH EXAMPLES
This example calculates the SHAKE256(, 512) hash of the input
from stdin, and prints the hash, in hexadecimal form, to stdout.
.LP
.nf
libkeccak_state_t state;
if (libkeccak_shakesum_fd(STDIN_FILNO, &state, 256, 512, binhash) < 0)
goto fail;
libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
printf("%s\\n", hexhash);
.fi
.SH SEE ALSO
.BR libkeccak_behex_lower (3),
.BR libkeccak_behex_upper (3),
.BR libkeccak_generalised_sum_fd (3),
.BR libkeccak_keccaksum_fd (3),
.BR libkeccak_sha3sum_fd (3),
.BR libkeccak_rawshakesum_fd (3),
.BR libkeccak_spec_shake (3),
.BR libkeccak_spec_check (3),
.BR libkeccak_generalised_spec_initialise (3)
.SH AUTHORS
Principal author, Mattias Andrée. See the LICENSE file for the full
list of authors.
.SH BUGS
Please report bugs to https://github.com/maandree/bus/issues or to
maandree@member.fsf.org
